Published-release documentation · release compatibility

Grids

Cartesian grid creators and editors accept strokeDashMap: [{ value, strokeDash }] alongside the uniform strokeDash pattern. A matching raw typed value overrides only that line; unmatched values use the uniform pattern. strokeDashMap: "auto" or [] clears only the overrides. Entries do not add grid values. Patterns are even-length arrays of finite non-negative lengths, with [] solid. Duplicate typed keys are errors. Band-boundary grids use the first selected band’s pattern for a shared edge.

At a glance

createGrid(options?)

Cartesian grids accept continuous, band and point scales. Band grids use centers by default; set bandPosition: "boundary" for both edges of each selected cell. Categorical grids accept category values and reject count.

An explicit bandPosition, including "center", requires a band scale; continuous and point scales reject it. In createLinePlot, only a categorical x band scale can use it through guides.grid.vertical. The horizontal grid follows the line’s continuous y scale and does not accept band positioning. Density plots use continuous value and density scales; Horizon and Rug plots use continuous quantitative or temporal measure scales. Their facade grids also reject explicit band positioning. Area plots retain categorical band grids on the independent channel: vertical for valueChannel: "y", horizontal for valueChannel: "x".

Set Cartesian zIndex to a finite rank: positive values draw above related marks, zero or negative values draw behind them. Grids on each side sort by rank, with horizontal before vertical on a tie. Editors and resizing retain the chosen order.

Creates Cartesian or Polar grid geometry from encoded scales. Cartesian defaults to horizontal only. A Polar-only chart creates theta spokes when theta is encoded and radial circles when radius is encoded; charts with both channels create both families.

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.

program.createGrid();

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.

program.createGrid({
  horizontal: {
    color: "#e2e8f0",
    lineWidth: 1,
    strokeDash: []
  },
  vertical: true
});

Direction options are:

When values and count are omitted, a grid reuses compatible existing axis ticks. Without an axis it uses histogram bin boundaries for a binned x scale, or five nice ticks for another continuous scale. Explicit values and count always take precedence.

alongOffset is independent of tick and label displacement. It applies after scale mapping and band-boundary construction, survives edits and Canvas/scale updates, and does not change the scale domain or mark positions. Use zero to reset it. Polar grids do not accept this option.

Horizontal lines span the plot width at y-scale positions. Vertical lines span the plot height at x-scale positions. Grid graphics are inserted before the first related mark in rendering order, even when createGrid is called after that mark was created.

Canvas and connected scale changes explicitly rematerialize concrete grid positions. Grid style is graphical state; only the resolved scale and coordinate IDs are stored in semanticSpec.

The trace preserves direction-level actions:

createGrid
├─ createHorizontalGrid?
└─ createVerticalGrid?

Polar dispatch uses createRadialGrid for concentric closed paths and createThetaGrid for center-to-edge spokes. Theta defaults to six ticks; radius defaults to five. A zero radial tick remains available to the axis but does not create a degenerate zero-radius circle. Polar grid color defaults to #d7e0ea.

Use false to disable a direction. If scale or coordinate inference is ambiguous, provide its ID explicitly.

Editing grids

Use the direction-specific edit actions after that grid exists:

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.

program
  .editHorizontalGrid({ count: 6, color: "#cbd5e1" })
  .editVerticalGrid({ values: [50, 100, 150], strokeDash: [4, 2] });

Edit options are count, values, color, lineWidth, and strokeDash. Use either count or values. values: "auto" restores current axis/scale inference. At least one option is required.

Use editGrid() to update both directions through one aggregate 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.

program.editGrid({
  horizontal: { count: 6, color: "#cbd5e1" },
  vertical: { values: [50, 100, 150], strokeDash: [4, 2] }
});

Both selected directions must already exist. The complete request is validated before either directional edit runs, so an invalid vertical patch cannot leave a partially edited horizontal grid.

Grid edits preserve the existing scale and coordinate binding. They invoke a wrapped directional rematerialization action, replacing only that direction’s concrete line geometry and appearance. editGrid delegates to these same directional actions, which remain available for focused edits.

Polar grids use the same pattern through editThetaGrid, editRadialGrid, or editGrid({ theta: {...}, radial: {...} }). removeGrid accepts the same direction names.

createGuides() selects this default horizontal grid automatically when a y encoding is present. Pass createGuides({ grid: false }) to opt out.

Removing grids

removeGrid() removes every existing direction. Select a subset with explicit booleans:

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 noGrid = program.removeGrid();
const horizontalOnly = program.removeGrid({ vertical: true });

At least one direction must be selected; explicit false/false is an error. Scales, coordinates, marks, and axes remain.

Errors and limitations

Each selected direction requires one compatible resolved scale and matching Cartesian or Polar coordinate. Ambiguous resources require explicit IDs.

Related

Guides · Axes · Advanced axis components