Reflex

The experimental Reflex integration bundled with xy renders an XY chart as a first-class Reflex component. The core stays framework-neutral at runtime: application state and events remain in Reflex while XY owns chart data, rendering, and interaction math.

Install the reflex extra from PyPI. It installs the supported Reflex dependency floor; the reflex_xy import namespace is already included in every xy wheel:

Then register the bundled plugin:

The plugin attaches XY's binary data plane to the Reflex app's existing Socket.IO server. It does not add another HTTP service or websocket endpoint to deploy.

Pass concrete columns through data= when they do not depend on state. The adapter compiles a content-addressed binary asset during the frontend build, so the result works with reflex export and needs no backend connection.

Static charts retain browser-local hover, pan, zoom, and density refinement. They do not dispatch backend event handlers because there is no live kernel to resolve semantic event payloads.

Use @rxy.data when chart columns depend on session state. Declare the chart where it renders and return only its columns from the state method. The chart structure is validated when reflex run compiles the app, without running the data method. At runtime the computed var holds only a typed handle; numeric columns travel as binary frames over the app's existing websocket rather than through Reflex state JSON.

The TypedDict return annotation lets the integration catch misspelled column names while the page compiles. A plain mapping return type also works, but its column names can only be checked when the data method first runs. Data methods may be async def and may return None when no data is currently available.

For multiple marks, pass data-free XY nodes to rxy.chart. Channel values are column-name strings, and every mark binds to the same data handle:

Both the flat factories such as rxy.scatter_chart and composed rxy.chart build a data-free plan at page evaluation. Invalid chart options and unknown columns in a typed schema therefore fail at compile time rather than producing a blank chart in the browser. Changing state republishes only the columns under the stable data handle, preserving the mounted chart's view and selection.

Data handles are ordinary Reflex vars. They can be selected with rx.cond, or collected in a typed list[rxy.DataHandle[Schema]] for rx.foreach, as long as each source satisfies the chart's column schema.

Use @rxy.data for every state-backed chart whose marks, axes, and other structure can be declared in the page. @rxy.figure remains an escape hatch only for the uncommon case where state changes that structure itself.

on_point_hover, on_point_click, on_select_end, on_view_change, on_animation_start, and on_animation_end dispatch small semantic payloads through normal Reflex event handlers. Large chart buffers never enter those payloads. These props belong on the outer rxy chart factory and work with a live @rxy.data source.

They are separate from the core callbacks accepted by xy chart containers. Core on_hover, on_click, on_brush, on_select, and on_view_change callbacks are ordinary Python callables for the notebook widget. The Reflex adapter does not turn those callbacks into Reflex events. Instead, use its component props:

In particular, notebook on_select receives an xy.Selection with canonical row indices, while Reflex on_select_end receives a compact summary suitable for an ordinary Reflex event. See Interactions and selections for the core callback contract.

State-driven full payloads update the existing browser view in place, so stable mark key= values and an xy.animation(match="key") child preserve identity across a Reflex recompute. See Animations and data transitions.

To extend a registered chart from an event or background task, append new points without rebuilding the component:

See Real-time and streaming data for the mutation and snapshot contract.

Prefer the concrete-column form for fixed data and @rxy.data for state-backed data. Both use the same compile-validated chart API; only the transport changes.

Legend, tooltip, and colorbar components can retain opaque framework objects:

The shipped adapter does not currently mount those objects beside its chart host. A custom adapter can read chart.chrome_components() (or its reflex_components() alias) and mount them alongside the chart. Opaque render objects never enter standalone HTML. For ordinary DOM customization, use the Customize Each Part slot styling guide.