reflex-schedule-x

Schedule-X event calendar for Reflex — a modern alternative to FullCalendar and react-big-calendar, driven entirely from Python.

• 6 views: day, week, month grid, month agenda, week agenda and list.
• Events in Reflex state: pass a list[dict] with plain date strings; edits in Python update the running calendar.
• Every callback (on_event_click, on_range_update, on_click_date_time, on_view_change, ...) as typed Reflex event triggers.
• Plugins: events service, calendar controls, current time, event modal, scroll controller, event recurrence (RRULE / EXDATE), iCalendar import, timezone select.
• Custom components: fill any Schedule-X slot (timeGridEvent, monthGridEvent, eventModal, header slots, ...) with Reflex components.
• i18n & timezones: 37 locales, translation overrides, IANA timezones, dark mode, default and shadcn themes.
• Standalone date picker and time picker components.
• Imperative API (ScheduleXAPI) for rx.call_script driven control.

Bundles @schedule-x/* 4.8.0 (open-source packages). Premium plugins (drag & drop, resize, drag-to-create, resource scheduler, ...) are not included.

Installation

pip install reflex-schedule-x
# or
uv add reflex-schedule-x

Requires Python 3.11+ and reflex>=0.10.0. The npm packages are installed automatically by Reflex.

Quick start

import reflex as rx
from reflex_schedule_x import calendar_type, schedule_x


class State(rx.State):
    events: list[dict] = [
        {
            "id": "1",
            "title": "Coffee with John",
            "start": "2026-09-17 10:05",
            "end": "2026-09-17 10:35",
            "calendarId": "work",
        },
        {"id": "2", "title": "Ski trip", "start": "2026-09-19", "end": "2026-09-21"},
    ]
    selected: dict = {}

    @rx.event
    def on_event_click(self, event: dict):
        self.selected = event


def index():
    return schedule_x(
        events=State.events,
        calendars={"work": calendar_type("work", "#f91c45", "#ffd2dc", "#59000d", label="Work")},
        views=["day", "week", "month-grid", "month-agenda"],
        default_view="week",
        timezone="America/Caracas",
        locale="es-ES",
        is_dark=rx.color_mode_cond(light=False, dark=True),
        event_modal=True,
        current_time_indicator=True,
        on_event_click=State.on_event_click,
        height="800px",
    )


app = rx.App()
app.add_page(index)

Dates and times

Schedule-X uses the Temporal API. The component converts strings for you:

Payloads sent back to Python use "YYYY-MM-DD" for dates and "YYYY-MM-DD HH:mm" (calendar timezone) for date-times, so they round-trip with your state. Set datetime_format="iso" to receive RFC 9557 strings instead.

Helpers: to_sx_datetime(date | datetime), to_sx_date(...), parse_sx_datetime(str), calendar_event(...), background_event(...), calendar_type(...).

schedule_x props

Props marked live update the running calendar; changing any other prop re-creates it.

The calendar defaults to width="100%", height="800px", max_height="90vh"; override with normal style props.

Event triggers

Lazy loading: load events in on_range_update (and on_scroll_day_into_view for the list view) and assign them to the events state var.

Custom components (slots)

Put schedule_x_slot(name, *children) components inside schedule_x. Slot content is normal Reflex UI, so it can use state. Inside a slot:

• schedule_x_field(name, format=None) renders slot data. Event fields: title, description, location, people, start, end, calendarId, custom keys; virtual fields time_range, date_range, calendar_label. Other slots expose date, day, hour, events. Formats: time, date, datetime, weekday, weekday_short, day, month, hour, count, upper, json.
• schedule_x_show(name, *children, negate=False) renders children when the field is truthy (is_all_day too).
• schedule_x_event_card(*children, variant="container" | "main") paints the event's calendar colors.
• schedule_x_action(*children, action="delete", close_modal=True) sends clicks to on_slot_action.

schedule_x(
    schedule_x_slot(
        "timeGridEvent",
        schedule_x_event_card(
            schedule_x_field("title", tag_name="strong"),
            schedule_x_field("time_range"),
            schedule_x_show("location", schedule_x_field("location")),
        ),
    ),
    schedule_x_slot(
        "eventModal",
        rx.card(
            schedule_x_field("title", tag_name="h3"),
            schedule_x_action(rx.button("Delete"), action="delete", close_modal=True),
        ),
    ),
    schedule_x_slot("headerContentRightPrepend", rx.button("New", on_click=State.new_event)),
    events=State.events,
    event_modal=True,
    on_slot_action=State.on_slot_action,
)

Supported slots: timeGridEvent, dateGridEvent, monthGridEvent, monthAgendaEvent, weekAgendaEvent, monthAgendaDateDots, eventModal, headerContent, headerContentLeftPrepend, headerContentLeftAppend, headerContentRightPrepend, headerContentRightAppend, weekGridDate, weekGridHour, monthGridDayName, monthGridDate.

Imperative API

from reflex_schedule_x import ScheduleXAPI

api = ScheduleXAPI("my-calendar")  # schedule_x(id="my-calendar")

rx.button("Week", on_click=api.set_view("week"))
rx.button("Today", on_click=api.set_date(datetime.date.today()))
rx.button("Dump", on_click=api.get_events(callback=State.receive_events))

Methods: set_view, set_date, set_theme, add_event, update_event, remove_event, set_events, close_event_modal, scroll_to, get_view, get_date, get_range, get_events, get_event.

Date and time pickers

schedule_x_date_picker(value=State.date, on_change=State.set_date, locale="es-ES", label="Fecha", min="2026-01-01")
schedule_x_time_picker(value=State.time, on_change=State.set_time, is_12_hour=True, label="Hora")

Demo app

The schedule_x_demo/ folder contains a multi-page demo: playground with every option, events CRUD and callback log, custom components, recurrence + background events + iCal, language and timezones, imperative API with the list view, and the pickers.

uv venv && uv pip install -e .
cd schedule_x_demo
uv pip install -r requirements.txt
uv run reflex run

Development

uv sync --extra dev
uv run ruff check . && uv run ruff format --check .
uv run pytest --cov
uv run --python 3.12 python -m reflex_base.utils.pyi_generator custom_components/reflex_schedule_x   # regenerate .pyi stubs
uv build                                                                                        # sdist + wheel

Regenerate the stubs with Python 3.12, as CI does: Python 3.13 strips docstring indentation, so stubs generated with it fail the CI freshness check.

Branches: work happens on develop; main only receives pull requests from develop. The Quality (ruff, pytest on Python 3.11–3.13, build, stub freshness, demo bundle on Node 24) and Security (CodeQL, Bandit, pip-audit, Gitleaks, dependency review) workflows must pass before merging.

Releasing

1. Bump version in pyproject.toml, update CHANGELOG.md, and merge develop into main.

2. Tag main and push the tag:

   git checkout main && git pull
   git tag -a v0.2.0 -m "v0.2.0"
   git push origin v0.2.0
   

The Release workflow checks that the tag matches the version, runs the tests, builds the sdist and wheel, publishes them to PyPI with Trusted Publishing (no API token) from the pypi environment, and creates the GitHub release with the files attached.

License

MIT © Ernesto Crespo. Schedule-X is MIT licensed, © Tom Österlund.