Colorbars in Python

A colorbar explains a continuous color scale. Add xy.colorbar() after a compatible continuous-color mark and XY derives the validated domain, colormap, and a useful title from that mark. The built-in colorbar renders in the browser, SVG, native PNG, and Chromium PNG.

The two orientations share the same title and explicit-tick API. Browser DOM chrome additionally exposes the class and slot styling shown here:

The last compatible continuous mark wins when a chart layers several scales. XY derives colorbars for heatmaps, continuous scatter, hexbin, contour, continuous segments, and triangle meshes. A field or mark name supplies the default title; title= overrides it, ticks= supplies finite tick positions, and orientation= accepts "vertical" or "horizontal".

XY deliberately emits no built-in colorbar for constant or categorical color, RGB(A) heatmaps, or density-tier scatter whose per-row color channel is not resident in the browser. colorbar(show=False) removes an inferred scale. xy.pyplot has its own Matplotlib-shaped colorbar-authoring API.

Passing an explicit mark domain= pins the colorbar to a known range instead of the data extent, so the scale stays comparable across refreshes:

A hexbin's aggregated counts feed the colorbar just like any continuous channel, and when several continuous marks are layered the colorbar derives from the last compatible one — here the stations scatter (0–50 PPM on viridis), not the heatmap beneath it:

render= (or one positional child) remains an opaque integration hook:

Core XY stores that object but does not mount it, and the shipped reflex_xy.chart adapter does not currently mount custom chrome either. A custom adapter must read chrome_components() and place the returned component itself; standalone HTML, SVG, and PNG ignore the opaque replacement.

Seven chart slots target every visible part of built-in browser colorbar chrome: colorbar, colorbar_bar, colorbar_tick, colorbar_title, colorbar_extension, colorbar_line, and colorbar_minor_tick.

The declarative xy.colorbar() API creates the container, gradient bar, major ticks, and title shown below. The Matplotlib-shaped xy.pyplot colorbar API can add contour-line and minor-tick nodes. It creates separate colorbar_extension triangles only for an extended, line-only contour colorbar; filled-contour extensions are painted as part of colorbar_bar instead. These remain stable CSS/Tailwind targets whenever their nodes are present, but listing their classes on a plain declarative colorbar would not create them.

See the Reflex integration for the shipped chart adapter and Marks and components reference for the complete signature.

Add xy.colorbar() as a chart child after a continuous-color mark such as a heatmap or a scatter with a numeric color= channel. XY derives the validated domain, colormap, and a default title from that mark, and the built-in colorbar renders in the browser, SVG, native PNG, and Chromium PNG.

Pass them to the component: xy.colorbar(title="Temperature (°C)", ticks=[-3, 0, 5]). title= overrides the default title derived from the field or mark name, and ticks= supplies explicit finite tick positions; both work in either orientation.

Yes — xy.colorbar(orientation="horizontal"). The orientation= option accepts "vertical" (the default) or "horizontal", and both orientations share the same title and ticks API.

XY only derives colorbars for continuous-color marks: heatmaps, continuous scatter, hexbin, contour, continuous segments, and triangle meshes. Constant or categorical color, RGB(A) heatmaps, and density-tier scatter whose per-row color channel is not resident in the browser deliberately get no built-in colorbar. When several continuous scales are layered, the last compatible mark wins, and xy.colorbar(show=False) removes an inferred scale you don't want.