Chart Chrome

Installation

pnpm add @blakeui/pro-react

npm install @blakeui/pro-react

yarn add @blakeui/pro-react

bun add @blakeui/pro-react

Usage

Chrome is everything a chart draws that is not the data — and it is not a component you import. It is settings on the charts you already have, so there is nothing extra to install and nothing extra to compose. This page collects the four that exist across the library and shows what each one does.

Which chart you are on decides how you reach them. The composable charts — AreaChart, BarChart, LineChart — expose the grid, the reference area, and the plot background as children you render, which is what gives each its own prop surface. Every other chart is a single component, so its grid is a boolean on the root with no sub-options, and it has neither of the other two. The projection tail is narrower still: it lives on one series type of one chart.

import { AreaChart, ComposedChart } from "@blakeui/pro-react";

// Composable — the grid is a child with its own props.
<AreaChart data={data}>
  <AreaChart.Grid horizontal vertical numTicksRows={4} />
  <AreaChart.Area dataKey="visitors" fill="var(--chart-2)" />
</AreaChart>;

// Single-component — the grid is a boolean, and the tail is a series field.
<ComposedChart
  data={data}
  series={[{ dataKey: "revenue", dashFromIndex: 8, type: "line" }]}
  showGrid
/>;

Chrome is not a series

Everything on this page maps to a neutral token, never to --chart-1 through --chart-5. Gridlines default to var(--separator); a reference area and a plot background both default to var(--muted), at low opacities picked so they stay separable when stacked; the projection tail inherits its series' own colour and changes only its dash. That split is deliberate — reserving the categorical scale for data is what keeps chrome from reading as a series that nobody labelled.

Grid

Gridlines are horizontal or vertical rules across the plot, drawn behind the series. They let someone read a value off the chart without hovering it, which matters when the chart is being read across a room or in a screenshot. Turn them off when the shape is the point and the exact numbers are not — a sparkline, a KPI mini-chart, a candlestick hero.

On a composable chart there is no "off" switch: the grid is a child, so you render it or you don't.

Directions

horizontal and vertical name the direction of the lines on screen, not the axis they come from. Horizontal lines are on by default because they are the ones you read a value against; vertical lines are off by default because on most charts they duplicate the x-axis ticks.

On BarChart this reads relative to the chart's orientation: horizontal lines are the value gridlines and vertical lines are the category separators in a vertical chart, and the two swap when orientation="horizontal".

Density and style

numTicksRows and numTicksColumns are approximate counts — the scale picks the nearest round values, so asking for 5 may give you 4 or 6. strokeDasharray takes any SVG dash pattern and is omitted by default, which is what makes the lines solid.

Which charts have one

AreaChart, BarChart, and LineChart take the Grid child. ComposedChart, ScatterChart, LiveLineChart, CandlestickChart, and LineChart take a showGrid boolean on the root — on everywhere except CandlestickChart, where the default is off because the reference hero omits it. RadarChart's grid is a different shape entirely: concentric rings rather than rules, sized by levels.

PieChart, RingChart, GaugeChart, and HeatmapChart have no grid. None of them plots against a continuous axis, so there is nothing for a rule to mark.

Grid child props

Taken by AreaChart.Grid, BarChart.Grid, and LineChart.Grid. Where a prop is not on all three, the description says so.

Root grid props

On the single-component charts the grid is one boolean, with no sub-options.

Reference area

A reference area is a shaded region marking a range on the chart — a recession, a maintenance window, a target band. It is a child you render, with x1 and x2 naming the range in the same terms the chart's x axis already uses. y1 and y2 are optional; leave both off and the region spans the full plot height, which is what you want for a window of time.

Use one when the shape of the data needs an explanation the axis cannot give. A trough that reads as noise becomes a labelled event once the band names it. Skip it when the region would only decorate — a shaded rectangle that marks nothing is chrome that costs contrast and returns nothing.

It paints under the data, never over it

The region is drawn above the grid and below the series. That ordering is fixed and does not depend on where you write the child: put ReferenceArea before the grid or after the series and it still lands in between. An annotation that covered the line it annotates would be a bug, so the layer does not let you write one.

The rect is decorative and carries aria-hidden, so a screen reader never announces it and it is never a tab stop or a hit target — hovering it still reaches the series tooltip underneath. The label is real visible text.

What x1 and x2 accept

Each chart takes bounds in whatever its own x scale already speaks, so the values you pass match the ones in your data.

• AreaChart is a time scale: pass a Date, an ISO string, or epoch milliseconds.
• BarChart and LineChart are keyed on the row index, so pass a category label — the same string your xDataKey yields — or the row index as a number. A label that is itself numeric ("3") falls back to the index, which is what keeps ambiguous categories resolvable.

The two differ in what a category covers. On BarChart the region spans whole bands, from the first category's leading edge to the last one's trailing edge, so the bars it names sit entirely inside it. On LineChart it spans point to point: x1="Mar" starts at March's own point.

Bounds are forgiving in both directions. Pass them inverted and they are ordered rather than drawn backwards; pass one past the end of the domain and it clamps to the plot edge instead of overflowing. Several ReferenceArea children on one chart all render.

Where it exists

AreaChart, BarChart, and LineChart take the ReferenceArea child — the three composable engines. No other chart has one yet: ComposedChart, ScatterChart, LiveLineChart, CandlestickChart, and RadarChart are single components with no child slot to render it into, and PieChart, RingChart, GaugeChart, and HeatmapChart plot nothing against a continuous axis for a range to mark.

Reference area child props

Taken by AreaChart.ReferenceArea, BarChart.ReferenceArea, and LineChart.ReferenceArea.

Projection line

A projection line marks part of a series as forecast rather than measured. dashFromIndex splits the path at a row index: everything up to it stays solid, everything from it on is dashed. The two halves share the pivot row, so they join at a point instead of leaving a gap — the line reads as one series that changes confidence partway along, not as two series.

Give the pivot to the last measured row, not the first projected one. Index 8 on a twelve-month series means September is the last real number and the dash covers October through December.

Colour stays with the series

The tail keeps its series' colour and changes only the dash. Recolouring it — to a muted token, or to a second --chart hue — is the tempting move and the wrong one: colour is how a reader tells series apart, so a second colour reads as a second series. The dash is already carrying the distinction.

Where it exists

Only on ComposedChart, and only on a type: "line" series. Bars and areas in the same ComposedChart have no equivalent.

Two nearby things are not this. LineChart.Line takes a strokeDasharray that dashes the series whole — right for a target or a benchmark, not for a tail. And LiveLineChart draws a dashed rule across to the y-axis at the live value, which marks a level rather than a stretch of time.

Projection props

Fields on a ComposedChart type: "line" series entry.

Background

A background is a tint over the whole plot area, painted underneath everything else. It gives the plot a surface of its own, so the data reads as sitting on a defined field rather than floating on the card. It is a child you render, and it takes no bounds — it always spans the full plot.

That is the whole difference between it and a reference area. A reference area marks a range and says something about the data inside it. A background marks nothing; it is the field the data sits on. Reach for it when the plot needs separating from a busy card, and skip it when the card already gives the chart an edge — a second surface inside a bordered card is one boundary too many.

It is the bottom-most layer

The tint paints below the grid, below any reference area, and below the series, wherever you write the child. That ordering is fixed for the same reason the reference area's is: chrome that covers the data it frames is a bug, and this layer is one step further down than the reference area, so there is nothing it may cover at all.

The demo above stacks all three. The band still reads as distinct against the tint because it is the darker of the two — the default opacities are chosen so that stacking them keeps them separable rather than merging into one flat wash.

Like the reference area, the rect carries aria-hidden and is never focusable or a hit target, so hovering it still reaches the series tooltip underneath. It has no label, because it names nothing.

Colour and weight

The default is var(--muted) at 0.07 — deliberately fainter than the reference area's 0.12, because a wash across the entire plot at the same strength would compete with the series everywhere instead of in one marked place. Both are on the neutral scale, never on --chart-1 through --chart-5, which stays reserved for data. You can pass a --chart token through fill if you want the surface tied to a series, but at these opacities a hue reads as a stain rather than as a surface.

radius rounds the corners of the plot rect and defaults to 0. Nothing in these engines clips the plot to a rounded shape, so the radius is the only thing rounding that rect and it has no existing clip to fight — the entrance reveal is a left-to-right wipe, which crosses the rounded corners without squaring them off.

Where it exists

AreaChart, BarChart, and LineChart take the Background child — the three composable engines, the same three that take ReferenceArea. No other chart has one yet: ComposedChart, ScatterChart, LiveLineChart, CandlestickChart, and RadarChart are single components with no child slot to render it into, and PieChart, RingChart, GaugeChart, and HeatmapChart have no rectangular plot area for a background to cover.

Background child props

Taken by AreaChart.Background, BarChart.Background, and LineChart.Background. The three are identical — the layer has no per-engine differences, because it takes no bounds to interpret.

CSS classes

Grid lines are grouped under a per-chart BEM class, so a utility or a stylesheet rule can reach all of them at once without touching the series.

• .area-chart__grid — the AreaChart grid group.
• .bar-chart__grid — the BarChart grid group.
• .line-chart__grid — the LineChart grid group.
• .composed-chart__grid, .scatter-chart__grid, .candlestick-chart__grid, .live-line-chart__grid — the single-component charts' grid groups.

The plot background is a single rect per chart, with no label to split off:

• .area-chart__background, .bar-chart__background, .line-chart__background — the tinted plot rect.

A reference area splits its rect and its label, so a rule can restyle one without the other:

• .area-chart__reference-area, .bar-chart__reference-area, .line-chart__reference-area — the shaded rect.
• .area-chart__reference-label, .bar-chart__reference-label, .line-chart__reference-label — the label text.

The projection tail has no class of its own — it is the same path element as the rest of the series, split in two and given a dash.