Plot
A chart: axes, a camera and the marks inside it, in 2D or 3D.
Static preview; loading the interactive plot
import hmplot as hm
data = {"x": [1, 2, 3, 4], "y": [3, 1, 4, 2]}
with hm.Plot(data=data, height=300, axes2d=True) as plot:
hm.Points(x="x", y="y")
plot
Usage
Use Plot for ordinary charts. data supplies a local table; x/y/z configure the implicit frame. Defaults include a white background and atomic initial loading. Handles expose Fit, settlement, settings, selections, and export.
animateBounds={true} animates numeric axis domains and ranges independently of mark
updates, using boundsDuration and boundsEasing. Mark animation keeps its separate animation, animationDuration, and animationEasing controls. They share one clock; see Frame animated scales for interruptions, exports, and changes that snap.
Axis titles default to the plotted column: an axis is named after the one column its marks plot there (x={{label}} and y={{label}} override it, and an empty label means automatic); an axis whose marks plot several columns, arrays or expressions has no title (see Frame axis titles).
axes2d shows the implicit frame’s 2D axes (on by default for Cartesian 2D). Given explicitly, it holds whatever the Plot contains. Without it, a child Frame that draws an axis on the plot’s side (a twin axis with no range) turns the axes on; ranged or anchored Frames and facet cells, and Frames inside them, draw their axes in their own boxes and never do.
dynamicMargins={false} (Python: dynamic_margins=False) fits the initial axis labels, then holds this plot’s own margins during pan and zoom, including after a gesture ends. Resize, font, axis-style/title and data-domain changes fit again. Longer navigation labels may clip; use a shorter axis format or numeric Theme.axes.marginLeft/marginRight/marginTop/marginBottom to reserve predictable space. Aligned plots still share the space their peers need, so this option does not lock the entire plot rectangle against changes elsewhere. The settings pane exposes Fit margins during navigation. The default remains true. axisMarginZoom separately controls axis-only zoom gestures in the margins.
type="3d" uses Z-up, so an x/y terrain grid rises along z. Use type="3d-y-up" for scenes whose height is y. cameraUp overrides either preset (Python: camera_up); the settings pane offers both presets. Switching the preset changes the up direction without remapping data coordinates.
In 3D, cameraMode chooses orbit or flyover navigation (flyover is map-style: a drag keeps the ground point under the cursor, the wheel zooms toward the cursor, right-drag or Alt-drag looks, WASD/QE fly, two fingers pinch toward their midpoint on touch, flySpeed and Shift scale the wheel and keys). cameraPosition, cameraTarget, cameraUp, and cameraFov set the camera; the handle’s getCamera(), setCamera(partial, {animate}), and fit() move it programmatically, and oncamerachange reports moves.
flyoverMomentum (default true; “Flyover momentum” in the settings pane) lets a flyover ground drag released while still moving glide on along the ground for a moment, slowing to a stop within about a second and a half and at most one and a half camera heights away, with the camera’s height and direction kept. A drag held still before release does not glide, and only ground drags do (not looking, pinching, the wheel or the keys). Any new input (a press, the wheel, a key, Escape), leaving the page, a programmatic camera change and disabling the controls stop a glide; whenSettled() and exports wait for it to stop. flyoverMomentum={false}, and the system’s reduced-motion setting, stop the view on release.
lights lists the lights used by marks with lit=true: ambient, directional,
hemisphere and point. The settings pane edits their color, intensity and position.
Python uses lights=[hm.light("ambient", intensity=0.3)]; Svelte uses lights={[light("ambient", { intensity: 0.3 })]}.
effects composites effects over the whole plot: a 3D plot’s sky ({ kind: "sky", image } or a gradient) and distance fog ({ kind: "fog", near: 100, far: 300 }, distances from the camera in world units; the plot’s box spans -50 to 50), how glowing marks bloom ({ kind: "bloom", strength, radius }), and plugins’ effects. They are drawn after the scene (docs/RENDERING.md “Sky, fog and glow”): picking ignores them, empty background stays clear, and marks that do not write depth, such as labels, take the fog of what is behind them. The settings pane shows fog with the camera settings (3D fog, start, end and color), and bloom’s strength and radius.
antialias chooses how the screen smooths edges: "msaa" (4x multisampling, the default), "ssaa8" or "ssaa16" (hybrid MSAA + supersampling), "smaa" (a post pass: faster when fills are heavy, softer thin lines) or "off". The hybrid modes render 2x/4x as many pixels with native 4x MSAA, then downsample through the presentation compositor: nominal 8x/16x sampling density at greater GPU and memory cost. They preserve CSS mark sizes and picking coordinates. WebGPU’s native MSAA is limited to 4x. Points, lines and text smooth their own edges in every mode, and so do 2D Rects, Bars, Histograms and BoxPlot boxes without MSAA (docs/RENDERING.md “Analytic edges”); other fills (Area, Pie and polar sectors, hexagons, GeoJSON, 3D) need MSAA for smooth edges. Exports always render with 4x MSAA at the requested export resolution, whatever the screen uses. Python uses the same values: hm.Plot(antialias="ssaa16").
Default size and axes
Without dimensions, a Plot fits its container up to 800 px wide, and is 450 px tall;
its title, caption and top or bottom legends take their room from that height. In a Python
notebook view or an exported HTML page it fills the cell or page instead; hm.export_png, export_svg and export_pdf, with no page to fill, draw it 800 px wide. Set width and height for fixed dimensions;
set responsive={true} (Python: responsive=True) for uncapped container width, including
when a width is supplied. responsive={false} uses the supplied width or 800 px.
Facet cells continue to fill their allocated space.
Axes and grids are visible by default only in 2D Cartesian plots. Polar, spherical and 3D plots keep them off unless requested.
Use axes2d={false} or axes3d={false} (Python: axes2d=False, axes3d=False) to hide them.
For 2D Cartesian plots, the default theme draws subtle major grids; minor grids remain off. Set x={{ grid: "off" }} and y={{ grid: "off" }} to hide the grids, or choose another theme.
Cartesian proportions and 3D guides
aspect="equal" makes equal transformed data units equally long on every Cartesian axis,
including 3D. Linear axes preserve ordinary data proportions; log/symlog axes preserve
proportions after their scale transform. User domains, range centers and reversed directions
are retained: in 2D the spare length goes to an axis whose domain is automatic, which shows
more than its data, and where it would fall on a domain you gave, the plot area narrows
(letterboxes) so that domain fills it exactly, leaving at most 45% of the plot on a side. Nested Frames share the root metric; explicit nested placements remain placements.
Changing domains or aspect updates the geometry without resetting camera orientation.
Polar and spherical geometry retains its natural proportions.
<Plot type="3d" aspect="equal" axes3d={{ style: "box", gridPlanes: ["xy", "xz"] }}> axes3d defaults to false. True uses theme.axes.threeD; an object enables guides with its
overrides. A box shows every edge; a triad shows three incident axes. Labels use near-facing
edges, stay upright and avoid duplicate shared-corner labels; selected grid planes occupy
far faces as the camera moves. Per-axis controls style baselines, ticks, titles, arrows and
grids. Explicit box/triad objects require Cartesian coordinates.
Borders and data masks
axisFrame={true} adds the missing sides of a rectangular Cartesian 2D border, without
opposite-side ticks or labels. axisMask clips points, thick lines, fills and data text to
the visible axes interior. Hidden fragments cannot be picked. Nested masks intersect with
ancestor masks; facet cells are supported. Axis guides, titles, legends and brush handles
remain visible. Masks work with hidden baselines and transparent backgrounds, and SVG/PDF
exports use the same boundaries as PNG and the screen.
HMPlot enables masks by default; Minimal leaves them off. A theme’s mask is ignored outside
supported Cartesian 2D frames; an explicit unsupported request raises an error. Python spells
the options axis_frame and axis_mask.
Cartesian 2D rules draw above marks, using the theme’s axis text color unless a rule supplies
its own color. Grid lines and shaded bands stay behind marks. Rule width, dash and color apply consistently to the canvas and vector exports.
animationGroup (animation_group in Python) on Data, Plot or Frame matches animated
rows by a column or list of columns independently of Data keys. It inherits through the
tree; a child Frame overrides its branch, and explicit null (Python None) restores
Data-key/position matching. Filter to one row per group before tweening: a country/year
table can keep key=["country", "year"] and animate by "country" after filtering
to one year. Groups must be unique in each tweened snapshot, and changing the group
column scheme resets motion history. Selection, hover and connections keep Data identity.