BarChart | Coinbase Design System

BarChart

@coinbase/cds-web@9.28.0

A bar chart component for comparing values across categories. Supports horizontal and vertical orientations, stacked bars, and grouped series.

import { BarChart } from '@coinbase/cds-web/visualizations/chart'

Source

Storybook

View as Markdown

Peer dependencies

framer-motion: ^10.18.0

Related components

BarChart is a wrapper for CartesianChart for comparing discrete categories, with a default value-axis minimum that follows the baseline (0 when baseline is not set).

Basics

Bar charts are a useful component for comparing discrete categories of data. They are helpful for highlighting trends to users or allowing them to compare proportions at a glance.

To start, pass in a series of data to the chart.

Layout

You can set layout to horizontal to render the chart horizontally.

Multiple Series

You can also provide multiple series of data to the chart. Series will have their bars for each data point rendered side by side.

Series Stacking

You can also configure stacking for your chart using the stacked prop.

You can also configure multiple stacks by setting the stackId prop on each series.

Stack Gap

Border Radius

Bars have a default borderRadius of 4. You can change this by setting the borderRadius prop on the chart.

Stacks will only round the top corners of touching bars.

Round Baseline

You can also round the baseline of the bars by setting the roundBaseline prop on the chart.

Data

Negative

Null

You can pass in null or 0 values to not render a bar for that data point.

You can also use the BarStackComponent prop to render an empty circle for zero values.

Range

You can pass in [min, max] tuples as data points to render bars that span a range of values.

Customization

Bar Spacing

There are two ways to control the spacing between bars. You can set the barPadding prop to control the spacing between bars within a series. You can also set the categoryPadding prop to control the spacing between stacks of bars.

Minimum Size

To better emphasize small values, you can set the stackMinSize or barMinSize prop to control the minimum size for entire stacks or individual bar.

Minimum Stack Size

You can set the stackMinSize prop to control the minimum size for entire stacks. This will only apply to stacks that have a value that is not null or 0. It will proportionally scale the values of each bar in the stack to reach the minimum size.

Minimum Bar Size

You can also set the barMinSize prop to control the minimum size for individual bars. This will only apply to bars that have a value that is not null or 0.

Multiple Axes

You can render bars from separate y axes in one BarPlot, however they aren't able to be stacked.

When using horizontal layout, you can use multiple x axes.

Custom Components

Outlined Stacks

You can set the BarStackComponent prop to render a custom component for stacks.

Animations

You can configure chart transitions using the transitions prop. Also, you can toggle animations by setting animate to true or false.

Live Code

function AnimatedStackedBars() {
  const dataCount = 12;
  const minValue = 20;
  const maxValue = 100;
  const minStep = 10;
  const maxStep = 40;
  const updateInterval = 600;
  const seriesSpacing = 30;

  const seriesConfig = [
    { id: 'red', label: 'Red', color: 'rgb(var(--red40))' },
    { id: 'orange', label: 'Orange', color: 'rgb(var(--orange40))' },
    { id: 'yellow', label: 'Yellow', color: 'rgb(var(--yellow40))' },
    { id: 'green', label: 'Green', color: 'rgb(var(--green40))' },
    { id: 'blue', label: 'Blue', color: 'rgb(var(--blue40))' },
    { id: 'indigo', label: 'Indigo', color: 'rgb(var(--indigo40))' },
    { id: 'purple', label: 'Purple', color: 'rgb(var(--purple40))' },
  ];

  const domainLimit = maxValue + seriesConfig.length * seriesSpacing;

  function generateNextValue(previousValue) {
    const range = maxStep - minStep;
    const offset = Math.random() * range + minStep;

    let direction;
    if (previousValue >= maxValue) {
      direction = -1;
    } else if (previousValue <= minValue) {
      direction = 1;
    } else {
      direction = Math.random() < 0.5 ? -1 : 1;
    }

    let newValue = previousValue + offset * direction;
    newValue = Math.max(minValue, Math.min(maxValue, newValue));
    return newValue;
  }

  function generateInitialData() {
    const data = [];

    let previousValue = minValue + Math.random() * (maxValue - minValue);
    data.push(previousValue);

    for (let i = 1; i < dataCount; i++) {
      const newValue = generateNextValue(previousValue);
      data.push(newValue);
      previousValue = newValue;
    }

    return data;
  }

  function AnimatedChart(props) {
    const [data, setData] = useState(generateInitialData);

    useEffect(() => {
      const intervalId = setInterval(() => {
        setData((currentData) => {
          const lastValue = currentData[currentData.length - 1] ?? minValue;
          const newValue = generateNextValue(lastValue);

          return [...currentData.slice(1), newValue];
        });
      }, updateInterval);

      return () => clearInterval(intervalId);
    }, []);

    const series = seriesConfig.map((config, index) => ({
      id: config.id,
      label: config.label,
      color: config.color,
      data: index === 0 ? data : Array(dataCount).fill(seriesSpacing),
    }));

    return (
      <BarChart
        stacked
        height={{ base: 200, tablet: 250, desktop: 300 }}
        series={series}
        transitions={{
          enter: { type: 'spring', stiffness: 700, damping: 80 },
          update: { type: 'spring', stiffness: 700, damping: 20 },
        }}
        inset={0}
        showYAxis
        yAxis={{
          showGrid: true,
          width: 0,
          tickLabelFormatter: () => '',
          domain: { min: 0, max: domainLimit },
        }}
        {...props}
      />
    );
  }

  function AnimatedChartExample() {
    const animatedStates = [
      { id: 'on', label: 'On' },
      { id: 'off', label: 'Off' },
    ];
    const [animatedState, setAnimatedState] = useState(animatedStates[0]);

    return (
      <VStack gap={2}>
        <HStack justifyContent="flex-end" gap={2} alignItems="center">
          <Text as="h3" font="headline">
            Animations
          </Text>
          <SegmentedTabs
            activeTab={animatedState}
            onChange={setAnimatedState}
            tabs={animatedStates}
          />
        </HStack>
        <AnimatedChart animate={animatedState.id === 'on'} />
      </VStack>
    );
  }

  return <AnimatedChartExample />;
}

Composed Examples

Candlesticks

You can render a candlestick chart by setting the BarComponent prop to a custom candlestick component.

Live Code

function Candlesticks() {
  const infoTextId = useId();
  const infoTextRef = React.useRef(null);
  const selectedIndexRef = React.useRef(null);
  const stockData = [...btcCandles].reverse().slice(0, 90);
  const min = Math.min(...stockData.map((data) => parseFloat(data.low)));

  const ThinSolidLine = memo((props) => <SolidLine {...props} strokeWidth={1} />);

  // Custom line component that renders a rect to highlight the entire bandwidth
  const BandwidthHighlight = memo(({ d, stroke }) => {
    const { getXScale, drawingArea, getXAxis } = useCartesianChartContext();
    const { scrubberPosition } = useScrubberContext();
    const xScale = getXScale();
    const xAxis = getXAxis();

    if (!xScale || scrubberPosition === undefined) return;

    const xPos = xScale(scrubberPosition);

    if (xPos === undefined) return;

    return (
      <rect
        fill={stroke}
        height={drawingArea.height}
        width={xScale.bandwidth()}
        x={xPos}
        y={drawingArea.y}
      />
    );
  });

  const candlesData = stockData.map((data) => [parseFloat(data.low), parseFloat(data.high)]);

  const staggerDelay = 0.25;

  const CandlestickBarComponent = memo(({ x, y, width, height, originY, dataX, ...props }) => {
    const { getYScale, drawingArea } = useCartesianChartContext();
    const yScale = getYScale();

    const normalizedX = React.useMemo(
      () => (drawingArea.width > 0 ? (x - drawingArea.x) / drawingArea.width : 0),
      [x, drawingArea.x, drawingArea.width],
    );

    const transition = React.useMemo(
      () => ({
        type: 'tween',
        duration: 0.325,
        delay: normalizedX * staggerDelay,
      }),
      [normalizedX],
    );

    const wickX = x + width / 2;

    const timePeriodValue = stockData[dataX];

    const open = parseFloat(timePeriodValue.open);
    const close = parseFloat(timePeriodValue.close);

    const bullish = open < close;
    const color = bullish ? 'var(--color-fgPositive)' : 'var(--color-fgNegative)';
    const openY = yScale?.(open) ?? 0;
    const closeY = yScale?.(close) ?? 0;

    const bodyHeight = Math.abs(openY - closeY);
    const bodyY = openY < closeY ? openY : closeY;

    return (
      <m.g animate={{ opacity: 1, y: 0 }} initial={{ opacity: 0, y: 12 }} transition={transition}>
        <line stroke={color} strokeWidth={1} x1={wickX} x2={wickX} y1={y} y2={y + height} />
        <rect fill={color} height={bodyHeight} width={width} x={x} y={bodyY} />
      </m.g>
    );
  });

  const formatPrice = React.useCallback((price) => {
    return new Intl.NumberFormat('en-US', {
      style: 'currency',
      currency: 'USD',
    }).format(parseFloat(price));
  }, []);

  const formatThousandsPrice = React.useCallback((price) => {
    const formattedPrice = new Intl.NumberFormat('en-US', {
      style: 'currency',
      currency: 'USD',
      minimumFractionDigits: 0,
      maximumFractionDigits: 0,
    }).format(parseFloat(price) / 1000);

    return `${formattedPrice}k`;
  }, []);

  const formatVolume = React.useCallback((volume) => {
    const volumeInThousands = parseFloat(volume) / 1000;
    return (
      new Intl.NumberFormat('en-US', {
        style: 'decimal',
        minimumFractionDigits: 0,
        maximumFractionDigits: 2,
      }).format(volumeInThousands) + 'k'
    );
  }, []);

  const formatTime = React.useCallback(
    (index) => {
      if (index === null || index === undefined || index >= stockData.length) return '';
      const ts = parseInt(stockData[index].start);
      return new Date(ts * 1000).toLocaleDateString('en-US', {
        month: 'short',
        day: 'numeric',
      });
    },
    [stockData],
  );

  const updateInfoText = React.useCallback(
    (index) => {
      if (!infoTextRef.current) return;

      const text =
        index !== null && index !== undefined
          ? `Open: ${formatThousandsPrice(stockData[index].open)}, Close: ${formatThousandsPrice(
              stockData[index].close,
            )}, Volume: ${(parseFloat(stockData[index].volume) / 1000).toFixed(2)}k`
          : formatPrice(stockData[stockData.length - 1].close);

      infoTextRef.current.textContent = text;
      selectedIndexRef.current = index;
    },
    [stockData, formatPrice, formatVolume],
  );
  const initialInfo = formatPrice(stockData[stockData.length - 1].close);

  return (
    <VStack gap={2}>
      <Text font="headline" id={infoTextId} aria-live="polite">
        <span ref={infoTextRef}>{initialInfo}</span>
      </Text>
      <BarChart
        enableScrubbing
        showXAxis
        showYAxis
        BarComponent={CandlestickBarComponent}
        BarStackComponent={({ children }) => <g>{children}</g>}
        borderRadius={0}
        height={{ base: 150, tablet: 200, desktop: 250 }}
        inset={{ top: 8, bottom: 8, left: 0, right: 0 }}
        onScrubberPositionChange={updateInfoText}
        series={[
          {
            id: 'stock-prices',
            data: candlesData,
          },
        ]}
        xAxis={{
          tickLabelFormatter: formatTime,
        }}
        yAxis={{
          domain: { min },
          tickLabelFormatter: formatThousandsPrice,
          width: 40,
          showGrid: true,
          GridLineComponent: ThinSolidLine,
        }}
        aria-labelledby={infoTextId}
      >
        <Scrubber
          hideOverlay
          LineComponent={BandwidthHighlight}
          lineStroke="var(--color-fgMuted)"
          seriesIds={[]}
        />
      </BarChart>
    </VStack>
  );
}

Monthly Sunlight

You can combine custom and BarPlot components and transitions to create a springy sunlight chart.

Live Code

function SunlightChartExample() {
  const dayLength = 1440;
  type SunlightChartData = Array<{
    label: string;
    value: number;
  }>;
  const sunlightData: SunlightChartData = [
    { label: 'Jan', value: 598 },
    { label: 'Feb', value: 635 },
    { label: 'Mar', value: 688 },
    { label: 'Apr', value: 753 },
    { label: 'May', value: 812 },
    { label: 'Jun', value: 855 },
    { label: 'Jul', value: 861 },
    { label: 'Aug', value: 828 },
    { label: 'Sep', value: 772 },
    { label: 'Oct', value: 710 },
    { label: 'Nov', value: 648 },
    { label: 'Dec', value: 605 },
  ];

  function SunlightChart({
    data,
    height = 300,
    ...props
  }: Omit<CartesianChartProps, 'series' | 'children'> & { data: SunlightChartData }) {
    return (
      <CartesianChart
        {...props}
        height={height}
        series={[
          {
            id: 'sunlight',
            data: data.map(({ value }) => value),
            yAxisId: 'sunlight',
            color: 'rgb(var(--yellow40))',
          },
          {
            id: 'day',
            data: data.map(() => dayLength),
            yAxisId: 'day',
            color: 'rgb(var(--blue100))',
          },
        ]}
        xAxis={{
          ...props.xAxis,
          scaleType: 'band',
          data: data.map(({ label }) => label),
        }}
        yAxis={[
          {
            id: 'day',
            domain: { min: 0, max: dayLength },
            domainLimit: 'strict',
          },
          {
            id: 'sunlight',
            domain: { min: 0, max: dayLength },
            domainLimit: 'strict',
          },
        ]}
      >
        <YAxis axisId="day" showGrid showLine position="left" label="Minutes of sunlight" />
        <XAxis showLine />
        <BarPlot seriesIds={['day']} transitions={{ enter: null }} />
        <BarPlot
          borderRadius={0}
          seriesIds={['sunlight']}
          transitions={{ enter: { type: 'spring', stiffness: 700, damping: 40, staggerDelay: 1 } }}
        />
      </CartesianChart>
    );
  }

  function Example() {
    return (
      <VStack gap={2}>
        <SunlightChart data={sunlightData} />
        <Text color="fgMuted" font="legal" textAlign="center">
          2026 sunlight data for the first day of each month in Atlanta, Georgia, provided by{' '}
          <Link
            href="https://gml.noaa.gov/grad/solcalc/table.php?lat=33.733&lon=-84.383&year=2026"
            target="_blank"
          >
            NOAA
          </Link>
          .
        </Text>
      </VStack>
    );
  }

  return <Example />;
}

Buy vs Sell

You can combine a horizontal BarChart with a custom legend to create a buy vs sell chart.

Basics​

Layout​

Multiple Series​

Series Stacking​

Stack Gap​

Border Radius​

Round Baseline​

Data​

Negative​

Null​

Range​

Customization​

Bar Spacing​

Minimum Size​

Minimum Stack Size​

Minimum Bar Size​

Multiple Axes​

Custom Components​

Outlined Stacks​

Animations​

Composed Examples​

Candlesticks​

Monthly Sunlight​

Buy vs Sell​

Is this page useful?

Basics

Layout

Multiple Series

Series Stacking

Stack Gap

Border Radius

Round Baseline

Data

Negative

Null

Range

Customization

Bar Spacing

Minimum Size

Minimum Stack Size

Minimum Bar Size

Multiple Axes

Custom Components

Outlined Stacks

Animations

Composed Examples

Candlesticks

Monthly Sunlight

Buy vs Sell