Composition Model

An XY chart starts with one container and a set of small Python specifications. The container creates the plotting surface. Marks turn data into visible geometry, while axes, annotations, legends, tooltips, themes, and interaction policies describe how that surface should behave.

Shared values such as data, title, dimensions, and callbacks are container props. Methods such as show(), to_html(), and write_image() operate on the composed chart after it has been built.

This interactive example combines bars, a line, an annotation, axes, a legend, a shared tooltip, and crosshair behavior in one panel:

The xy chart is independent of Reflex; reflex_xy.chart(...) is only the adapter used to mount this documentation preview.

1. Shared data flows down. A chart-level data= supplies every mark that uses named columns. A mark-level data= overrides it for that mark.
2. Declaration order controls layering. Marks render in order, so the target line above is painted after the bars.
3. Settings resolve by family. Singleton configuration nodes—such as legends, tooltips, colorbars, modebars, export settings, and animation settings—use the last node of their family. Themes and interaction_config() nodes merge in declaration order; later explicit values win only where they overlap.

The container communicates intent; it does not select a different rendering engine.

Here every rendered observation is a point, so scatter_chart() is the clearest container:

Family containers such as scatter_chart() return the same Chart interface as neutral chart(). facet_chart() repeats a composition over groups and returns a FacetChart with grid-aware output methods.

interaction_config() describes browser behavior; the host connects chart events to Python application state. Core callbacks are for a live notebook widget, while Reflex events are configured on reflex_xy.chart(...). A chart rendered without a Python event bridge still pans, zooms, and resolves tooltips locally.

See Interactions and Selections for the interaction model and Reflex integration for server callback examples.

Adding or removing marks means composing a new chart. Live APIs can append points to line and scatter traces, inspect rendered points, or select a range from scatter data; Reflex server-driven updates require a registered live chart. See Large Data and Performance for representation choices and Reflex integration for live updates.

For output, use show() or widget() in notebooks, to_html() for a standalone document, to_image() for bytes, and write_image() for a file.

For finished examples, browse the Gallery. For browser entrance and data-update motion, continue with Animations and data transitions.