reflex-charts

Chart.js for Reflex — every chart type, from pure Python.

reflex-charts is a Reflex custom component that wraps Chart.js (via its React bindings, react-chartjs-2). It exposes the full Chart.js feature set through a small, Pythonic API so you can build interactive, reactive charts in a Reflex app without writing any JavaScript.

Status: v0.2.1 — Reflex 0.10. Base wrapper, generic component, typed factories, data builders, and a demo gallery covering every chart type, now targeting Reflex 0.10.

Features

• All eight Chart.js types from one versatile component: line, bar, radar, doughnut, pie, polar area, bubble, scatter — plus area, horizontal bar and mixed variants.
• Pure Python. Configure charts with data/options dicts that mirror the Chart.js docs one-to-one. Any chartjs.org example pastes straight in.
• Reactive. Bind chart data to rx.State computed vars; charts update when state changes.
• Interactive. Surface the canvas on_click event (with the clicked elements) as a Reflex event handler.
• Zero setup. All Chart.js controllers, scales and plugins are registered automatically — no manual Chart.register(...).
• Optional builders for datasets, palettes and options; raw dicts always work.

Install

pip install reflex-charts        # or: uv add reflex-charts
# or from a clone:
pip install -e .

Requires Reflex ≥ 0.10.0 and Python ≥ 3.11. Projects still on Reflex 0.8/0.9 can pin reflex-charts==0.1.0.

Quick start

import reflex as rx
import reflex_charts as rxc

data = rxc.chart_data(
    labels=["Jan", "Feb", "Mar", "Apr"],
    datasets=[rxc.dataset("Sales", [10, 25, 18, 30], tension=0.3)],
)

def index() -> rx.Component:
    return rx.box(
        rxc.line(data=data, options=rxc.options(title="Monthly sales")),
        height="320px",
        width="100%",
    )

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

Put charts in a fixed-height box — the options() builder sets maintainAspectRatio=False so the chart fills its container.

Chart types

See docs/usage.md for an example of each.

Run the demo

A standalone demo app (reflex_charts_demo/) shows a gallery of every chart type plus a state-driven, click-aware interactive example.

uv sync                          # installs reflex + the component (editable)
cd reflex_charts_demo
uv run reflex run                # open http://localhost:3000

Test

uv run pytest                    # unit tests
cd reflex_charts_demo && uv run reflex compile   # demo compiles against the component

CI (.github/workflows/ci.yml) runs the tests, builds the wheel (checking it carries the .pyi stubs) and compiles the demo on every push and pull request.

Build & publish

Reflex 0.10 removed the reflex component CLI (init, build, publish, share). The package is a plain setuptools project, so it is built and uploaded with the standard Python tooling.

Releases are automated. Bump the version, merge to main, then tag:

git tag v0.2.1 && git push origin v0.2.1

The Publish workflow (.github/workflows/publish.yml) checks that the tag matches pyproject.toml, runs the tests, builds, and uploads to PyPI through Trusted Publishing (GitHub environment pypi, no API token).

Manual build/upload, for local checks or emergencies:

uv build                         # build the wheel/sdist into dist/
uv run twine check dist/*        # validate metadata / README rendering
uv run twine upload dist/*       # upload to PyPI (token via ~/.pypirc)
# or: uv publish                 # token via UV_PUBLISH_TOKEN

Bump version in pyproject.toml and __version__ in custom_components/reflex_charts/__init__.py before every release (a test keeps them in sync).

The wheel ships typed .pyi stubs (and a py.typed marker) for editor autocomplete. The stubs are committed; to regenerate them after changing component props, run Reflex's stub generator on the package:

PYTHONPATH="$PWD" uv run python -m reflex_base.utils.pyi_generator custom_components/reflex_charts

Project layout

reflex-charts/
├── custom_components/
│   └── reflex_charts/          # the importable component package (PyPI: reflex-charts)
│       ├── base.py             # ChartJSBase: deps + Chart.js registration
│       ├── chart.py            # ChartCanvas + typed factories
│       ├── helpers.py          # dataset / chart_data / options builders
│       ├── constants.py        # npm pins, chart types, palette
│       └── examples/data.py    # canonical sample figures
├── reflex_charts_demo/         # standalone demo app (gallery + interactive)
│   ├── rxconfig.py
│   └── reflex_charts_demo/reflex_charts_demo.py
├── specs/                      # Spec-Driven Design artifacts (see below)
├── docs/usage.md               # usage guide
├── tests/                      # unit tests
└── scripts/                    # GitHub bootstrap helper

Design docs (Spec-Driven Design)

This repository is built spec-first. The full SDD set lives in specs/:

• Specification / PRD
• Architecture (incl. ADRs)
• Component API v1
• Data model
• Phases
• Implementation plan
• Task breakdown

How it works

Reflex compiles Python components to React. reflex-charts declares a component whose generated JSX is the generic <Chart> from react-chartjs-2, with Chart.js registered globally (Chart.register(...registerables)) so any type renders. Your data/options dicts are serialized to props; on interaction, Chart.js events are forwarded back to your Reflex state. See the architecture doc for the details and the decision records.

Acknowledgements

Built on the excellent Chart.js and react-chartjs-2 projects (both MIT licensed — see NOTICE) and the Reflex framework.

License

Apache-2.0 © 2026 Ernesto Crespo.