Skip to main content

Axis (S2)

The Axis component in the S2 package supports nearly all props from the base Axis component plus S2-exclusive features: axis label hover tooltips and axis label click callbacks.

import { Chart, Axis } from '@spectrum-charts/react-spectrum-charts-s2';

Axis label hover tooltips​

Set hasTooltip to show a Spectrum 2 tooltip when hovering an axis label. By default the tooltip shows the label's full, untruncated value — useful when combined with truncateLabels or labelLimit.

<Chart data={data}>
  <Axis position="bottom" truncateLabels hasTooltip title="Browser" />
  <Bar dimension="browser" metric="downloads" />
</Chart>

Custom tooltip text (tooltipText)​

Pass tooltipText to override the tooltip content for specific values. Values not listed keep the default (full label value). Set text: null to suppress the tooltip entirely for one value.

<Chart data={data}>
  <Axis
    position="bottom"
    truncateLabels
    hasTooltip
    title="Browser"
    tooltipText={[
      { value: 'Other', text: 'Clicking Other may expand the chart' },
      { value: 'Mac Safari', text: null },
    ]}
  />
  <Bar dimension="browser" metric="downloads" />
</Chart>

Axis label click​

Set onClick to run a callback when an axis label is clicked. The callback receives the native mouse event, the label's value, and its tick index.

<Chart data={data}>
  <Axis position="bottom" title="Browser" onClick={(event, value, index) => console.log(value, index)} />
  <Bar dimension="browser" metric="downloads" />
</Chart>

AxisThumbnail​

AxisThumbnail is a child of Axis that replaces each tick label with a thumbnail image, read from a key in the data.

<Chart data={data}>
  <Axis position="bottom" title="Browser">
    <AxisThumbnail urlKey="thumbnail" />
  </Axis>
  <Bar dimension="browser" metric="downloads" />
</Chart>

AxisThumbnail props​

nametypedefaultdescription
urlKeystring'thumbnail'The data field key that contains the URL of the thumbnail image.

ReferenceLine​

ReferenceLine is a child of Axis that draws a labeled line at a specific value.

<Chart data={data}>
  <Axis position="left" title="Users">
    <ReferenceLine value={50} label="Target" />
  </Axis>
  <Line dimension="datetime" metric="users" />
</Chart>

ReferenceLine props​

nametypedefaultdescription
value*number | string–The value on the axis where the reference line should be drawn.
position'before' | 'after' | 'center'–Position the line on the value, or between the previous/next value. Only supported in Bar visualizations.
labelstring–Axis text label for the reference line.
size'S' | 'M' | 'L'–Size variant controlling stroke weight and caret triangle dimensions. When omitted, stroke width reacts to chart size automatically.
secondaryboolean–When true, renders a lighter secondary style: no caret caps, and a lighter stroke color for size 'S'.

Axis props (S2)​

nametypedefaultdescription
position*'left' | 'bottom' | 'top' | 'right'–Sets where the axis will be displayed.
childrenAxisThumbnail | ReferenceLine–Optional child components for tick thumbnails and reference lines.
namestring–Sets the name of the component.
baselinebooleanfalseAdds a baseline rule for this axis.
baselineOffsetnumber0Adds an offset to the baseline. Ignored if baseline is false, or if the baseline is drawn relative to a categorical axis.
granularity'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year'–Sets the granularity of the primary axis labels for a time axis. Ignored if this axis is not a time axis.
gridbooleanfalseDisplays gridlines at each tick location.
hasTooltipboolean–Enables a Spectrum 2 hover tooltip on axis labels. See Axis label hover tooltips.
hideDefaultLabelsbooleanfalseHides the axis labels. If labels have been explicitly added using the labels prop, those remain visible.
labelAlign'center' | 'start' | 'end''center'Sets the alignment of axis labels.
labelFontWeightFontWeight–Sets the font weight of axis labels.
labelFormat'duration' | 'linear' | 'percentage' | 'time'–Sets the format of the axis labels.
labelLimitnumber180Sets the maximum allowed length, in pixels, of axis tick labels. Combine with truncateLabels to keep the limit within the tick bandwidth.
labelOrientation'horizontal' | 'vertical''horizontal'Sets the orientation of the label.
labels(Label | string | number)[]–Explicitly sets the axis labels (controlled). Providing a Label object allows control over the display value, alignment, and font weight per label.
numberFormatstring–d3 number format specifier. Only valid if labelFormat is 'linear' or unset.
onClick(event: MouseEvent, value: string | number | Date, index: number) => void–Callback fired when an axis label is clicked. See Axis label click.
range[number, number]–The minimum and maximum values for the axis. Only supported for axes with linear or time scale types.
subLabelsSubLabel[]–Adds sublabels below the axis labels.
tickCountMinimumnumber2Sets the minimum number of axis ticks. Smaller charts may want a minimum of 3 for a more accurate representation of the data.
tickCountLimitnumber–Sets the upper limit on the number of axis ticks. On time-based axes, setting this overrides the automatic granularity-based tick interval and can produce duplicate labels — you are responsible for aligning it with the data granularity.
tickMinStepnumber–The minimum desired step between axis ticks, in scale domain values. Only supported for linear axes.
ticksbooleanfalseDisplays ticks at each label location.
titlestring | string[]–Sets the axis title. Pass an array for a multi-line title.
tooltipText{value: string | number, text: string | null}[]–Per-value tooltip text overrides. See Custom tooltip text.
truncateLabelsbooleanfalseIf the text is wider than the tick's bandwidth, truncates it so it stays within that bandwidth.
currencyLocalestring–⚠️ Limited support. Sets the locale for currency formatting (affects symbol position and spacing). Requires currencyCode to take effect.
currencyCodestring–⚠️ Limited support. Overrides the currency symbol from the chart locale. Requires currencyLocale to take effect.