Skip to main content

Bar (S2)

The Bar component in the S2 package supports nearly all props from the base Bar component plus S2-exclusive features: inline direct labels and Spectrum 2 styled visuals.

note

The S2 Bar component does not yet support Trendline as a child component.

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

Bar direct labels (BarDirectLabel)​

The BarDirectLabel component is an S2-exclusive child of Bar. It places a numeric label outside the tip of each bar, reading directly from the metric value. Labels are positioned automatically based on orientation — above or below the bar for vertical charts, left or right for horizontal charts — and flip to the opposite side for negative values.

<Chart data={data}>
  <Axis position="bottom" baseline title="Browser" />
  <Axis position="left" grid title="Downloads" />
  <Bar dimension="browser" metric="downloads">
    <BarDirectLabel />
  </Bar>
</Chart>

Bar direct label light Bar direct label dark

Horizontal bars​

The same component works for horizontal bar charts. Labels appear to the right of positive bars and to the left of negative bars.

<Chart data={data}>
  <Axis position="left" baseline title="Browser" />
  <Axis position="bottom" grid title="Downloads" />
  <Bar dimension="browser" metric="downloads" orientation="horizontal">
    <BarDirectLabel />
  </Bar>
</Chart>

Bar direct label horizontal light Bar direct label horizontal dark

BarDirectLabel props​

The label text is derived automatically from the parent Bar's metric, dimension, and orientation.

nametypedefaultdescription
position'start' | 'middle' | 'end' | 'end-outside''end-outside'Where to place the label relative to the bar. 'end-outside' places it outside the bar tip; 'end' places it inside the bar, 8px from the tip; 'middle' centers it within the bar; 'start' places it inside the bar, 8px from the baseline edge.
format'currency' | 'shortCurrency' | 'shortNumber' | 'standardNumber' | 'percentage' | string',.2~f'Number format for the label value. Accepts a named preset or a custom d3-format specifier string (e.g. '.1f').

Diverging bars​

Set diverging on Bar for a metric that spans positive and negative values (e.g. percent change). It moves the categorical axis to the zero baseline and flips each axis label to the side opposite its bar, so labels never overlap the bars.

<Chart data={data}>
  <Axis position="left" baseline />
  <Axis position="bottom" grid labelFormat="percentage" />
  <Bar dimension="channel" metric="changeRate" orientation="horizontal" diverging>
    <BarDirectLabel position="start" format="percentage" />
  </Bar>
</Chart>
Single-series only

diverging only supports a single-series bar (no color, lineType, or opacity facet, and not type="dodged") that is the only bar mark on the chart. It is also a no-op on a trellised chart or when the axis has subLabels. In any of these cases the axis stays at its normal position and diverging has no effect.

Bar props (S2)​

nametypedefaultdescription
childrenChartInspect | ChartPopover | BarAnnotation | BarDirectLabel–Optional child components for tooltips, popovers, annotations, and inline direct labels.
colorstring | {value: string}'categorical-100'Key in the data used to map each series to a color, or a fixed color value object.
dimensionstring'category'Key in the data used for the categorical axis.
divergingboolean–Moves the categorical axis to the zero baseline and flips each label to the opposite side of its bar. Single-series bars only — see the note above.
metricstring'value'Key in the data used for the metric axis value.
namestring'bar0'Name of the bar component. Useful when referencing a specific bar programmatically.
onClick(datum: Datum) => void–Callback fired when a bar is clicked.
orientation'vertical' | 'horizontal''vertical'Controls whether bars extend vertically (default) or horizontally.
type'stacked' | 'dodged''stacked'Controls whether multi-series bars are stacked on top of each other or placed side by side.