Published-release documentation · release compatibility

Canvas

At a glance

createCanvas(options?)

Creates the program’s single canvas and establishes bounds for later position encodings.

Contextual fragment. Use an ES module with the imports, data, and prepared resource state described in this section. Resolve these names from setup in this fragment or section; alternatives branch from the same base.

const program = chart().createCanvas({
  width: 640,
  height: 400,
  background: "white",
  margin: { top: 30, right: 30, bottom: 60, left: 70 }
});

Exact inner dimensions

Use createCanvas({ plot: { width: 30, height: 30 } }) to fix the data region while guide authoring measures and expands the outer Canvas. Both Full and Basic support this mode. Numeric margins provide initial space; insufficient sides grow on a quarter-pixel grid. Rotated axis labels use their measured outer edge and remain outside the plot. Chart titles are placed beyond the existing guides.

Do not combine plot with outer width or height. On Full, use editCanvas({ plot: { width: 60, height: 45 } }) to resize the data region, or editCanvas({ plot: false }) to return to fixed outer dimensions. Font-metric updates rerun the same measured layout. Explicit scale ranges retain their usual fixed-coordinate behavior. Automatic margins do not resolve overlapping labels or other incompatible guide geometry; those errors still reject the action.

Plot outline.

Set plotBorder: {} to draw an outline around the data region in Full or Basic. The default style is color: "#ddd" and lineWidth: 1. The stroke sits entirely inside the plot: its outer painted edge matches the plot bounds. It draws above ordinary marks and below axes by default. Set underlay: true to paint it before ordinary marks, without changing mark positions, scale ranges, plot size, margins, or clipping.

Contextual fragment. Use an ES module with the imports, data, and prepared resource state described in this section. Resolve these names from setup in this fragment or section; alternatives branch from the same base.

const bordered = chart().createCanvas({ plotBorder: {} });
const recolored = bordered.editCanvas({ plotBorder: { color: "#888" } });
const unbordered = recolored.editCanvas({ plotBorder: false });

On Full, omitting plotBorder from editCanvas preserves its setting. An object replaces the complete border style: omitted color or lineWidth returns to its default, rather than keeping an earlier value. Omitting underlay from a new border object also restores the default overlay; include underlay: true to retain that choice. See compositing marks over guides. false removes the outline. Colors must be non-empty strings. Line width must be positive and finite, and strictly smaller than both resolved plot dimensions. Resizing, scale or data edits, and facet replay preserve the border setting and update its bounds.

editCanvas(options)

Updates one or more existing canvas options. Omitted values are preserved. A numeric margin applies to every side; a partial object updates only named sides. The plotBorder object replaces its complete style as described above.

Contextual fragment. Use an ES module with the imports, data, and prepared resource state described in this section. Caller-provided receivers: program. Resolve these names from setup in this fragment or section; alternatives branch from the same base.

const resized = program.editCanvas({
  width: 800,
  margin: { left: 80 }
});

Width, height, or margin changes explicitly rematerialize connected automatic position scales, line marks, axes, legends, and chart titles. Background-only edits do not.

Margin is immutable materialization configuration used with the concrete Canvas dimensions to derive plot bounds. It is neither a drawable node in graphicSpec nor transient authoring context.

fitCanvas(options?)

After marks, guides, and titles exist, a Full chart can shrink its margins while keeping the Canvas size fixed. Disable exact-inner sizing with plot: false before calling this action:

Contextual fragment. Use an ES module with the imports, data, and prepared resource state described in this section. Caller-provided receivers: program. Resolve these names from setup in this fragment or section; alternatives branch from the same base.

const fitted = program.fitCanvas({
  padding: 4,
  minPlotWidth: 160,
  minPlotHeight: 120
});

The action searches top, right, bottom, then left on a deterministic 0.25-pixel grid. Every probe uses the same rematerialization and collision checks as editCanvas. It preserves semantic state, scale domains, explicit scale ranges, Canvas width, and Canvas height. Automatic ranges follow the fitted plot bounds.

The default policy rejects an unsatisfied fit without changing the source program. overflow: "report" applies the last valid margins and stores the normalized policy, status, issues, fitted plot size, probe count, and layout signature under materializationConfigs.fitting. Calling fitCanvas again with the same layout and policy converges exactly. It runs only when explicitly called; later edits are fitted by another explicit call.

Errors and limitations

Only one Canvas can exist in a program. Dimensions must remain positive and margins must leave positive plot bounds. fitCanvas is a Full unit action; Basic does not expose it and compositions reject it. An enabled plot border must fit strictly inside both plot dimensions, including after Canvas edits. plotBorder: true and unknown border style keys are rejected.

Related

Rendering · Coordinates · Scale options