Layout

The layout section controls the whitespace around the chart — the outer padding, and the gaps between the regions the engine arranges (header, legend, axes, plot). Two neighbouring keys change how much room the chart needs, so they’re covered here too: panel.overflow and appearance.textScale.

config({
  layout: { padding: 32 },
});

Padding

number | EdgePaddingConfig | null

default:"null (24px)"

Outer padding in pixels. A number applies to all four sides; an object ({ top?, right?, bottom?, left? }) sets sides individually. null uses the engine default of 24 on every side.

Any side you leave out of the object form keeps the 24px default, so this trims the left edge and opens up the top while the other two stay put:

config({
  layout: { padding: { top: 40, left: 0 } },
});

An explicit 0 removes a side’s padding.

Region gaps

The chart is laid out as a grid of named regions. gaps overrides the spacing around any of them; anything left unset keeps the default.

config({
  layout: {
    padding: 24,
    gaps: {
      header: 40, // space below the header
      bottomLegend: 16,
    },
  },
});

A gap value is either a number (sets the trailing/after gap) or { before, after } to set each edge independently. The overridable rows, with their default gaps:

Row	`before`	`after`
`header`	0	10
`headline`	0	4
`topLegend`	0	8
`topAxisLabel`	0	8
`topAxis`	0	0
`bottomAxis`	0	4
`bottomAxisLabel`	0	16
`bottomLegend`	16	10
`footer`	16	0

footer is the row that holds the caption, source and provenance mark; its before gap is what keeps them off the chart body whatever precedes them. And the columns:

Column	`before`	`after`
`leftLegend`	0	10
`leftAxis`	0	4
`rightAxis`	4	10

There is deliberately no rightLegend gap — a right-hand legend takes its spacing from the rightAxis column beside it.

Adjacent regions share a boundary using a max(previous.after, next.before) rule, so a lone after can’t shrink a boundary below the following region’s before.

Panel overflow

The panel is the plot area. Data labels and difference arrows can reach past its edge, and panel.overflow says what the engine does about it — per content type, per direction:

config({
  panel: {
    overflow: {
      dataLabels: { x: 'inside', y: 'outside' },
      differenceArrows: { x: 'outside', y: 'outside' },
    },
  },
});

{ x: PanelOverflowStrategy; y: PanelOverflowStrategy }

default:"{ x: 'inside', y: 'inside' }"

Strategy for data labels that reach past the panel edge.

{ x: PanelOverflowStrategy; y: PanelOverflowStrategy }

default:"{ x: 'outside', y: 'outside' }"

Strategy for difference-arrow annotations.

Each direction takes one of three strategies:

'outside' — the element lands outside the panel frame and the frame shrinks to make room.
'inside' — the element stays inside the frame and the content within the frame shrinks instead.
'none' — no accommodation; the element may overlap whatever is beside it.

Overflow accommodation applies to cartesian charts.

Text scale

number

default:"1"

A multiplier applied to every text element in the chart. 1.2 makes titles, axis labels, tick labels and data labels 20% larger.

config({
  appearance: { textScale: 1.2 },
});

It sits with layout because it changes measured text, and therefore the size of every region the engine arranges.

Renderer contract: a custom renderer must apply textScale at both text measurement and CSS render time. The engine assumes the measured sizes it receives already include the multiplier, so applying it to only one of the two throws the layout out.

Styling — the graph background, frame ring and corner radius
Legend — legend position feeds the region layout

Get Started

Core concepts

Chart types

Annotations & emphasis

Rendering

Configuration

Advanced

Extending

Padding

Region gaps

Panel overflow

Text scale

​Padding

​Region gaps

​Panel overflow

​Text scale

​Related

Padding

Region gaps

Panel overflow

Text scale

Related