YAxis | Coinbase Design System

YAxis

@coinbase/cds-web-visualization@3.4.0

A vertical axis component for CartesianChart. Displays tick marks, labels, gridlines, and supports custom formatting, positioning, and data domains.

import { YAxis } from '@coinbase/cds-web-visualization'

Source

View as Markdown

Peer dependencies

framer-motion: ^10.18.0

Related components

Basic Example

The YAxis component provides a vertical axis for charts with automatic tick generation and labeling.

Live Code

<CartesianChart
  enableScrubbing
  height={250}
  series={[
    {
      id: 'prices',
      data: [10, 22, 29, 45, 98, 45, 22, 52, 21, 4, 68, 20, 21, 58],
    },
  ]}
>
  <YAxis showGrid />
  <Line seriesId="prices" showArea />
  <Scrubber />
</CartesianChart>

Axis Config

Properties related to the scale of an axis are set on the Chart component. This includes scaleType, domain, domainLimit, range, data, and categoryPadding.

Scale Type

YAxis supports linear (default) and log scale types. Both linear and log are numeric scales.

Live Code

<CartesianChart
  height={400}
  series={[
    {
      id: 'growthExponential',
      data: [
        1, 2, 4, 8, 15, 30, 65, 140, 280, 580, 1200, 2400, 4800, 9500, 19000, 38000, 75000, 150000,
      ],
      color: 'var(--color-fgPositive)',
    },
  ]}
  yAxis={{
    scaleType: 'log',
  }}
>
  <Line seriesId="growthExponential" showArea />
  <YAxis
    showGrid
    showLine
    showTickMarks
    requestedTickCount={6}
    width={70}
    tickLabelFormatter={(value) => value.toLocaleString()}
  />
</CartesianChart>

Domain

An axis's domain is the range of values that the axis will display. You can pass in either an object (AxisBounds) with min and max properties (both optional), or a function that receives initial AxisBounds and returns an adjusted AxisBounds.

Live Code

<CartesianChart
  height={250}
  series={[
    {
      id: 'prices',
      data: [10, 22, 29, 45, 98, 45, 22, 52, 21, 4, 68, 20, 21, 58],
    },
  ]}
  yAxis={{
    domain: ({ min, max }) => ({ min: min - 50, max: max + 50 }),
  }}
>
  <YAxis showGrid />
  <Line seriesId="prices" showArea />
</CartesianChart>

Domain Limit

You can set the domain limit to nice (default for YAxis) or strict. nice will round the domain to human-friendly values, while strict will use the exact min/max values from the data. See d3-scale for more details.

Range

An axis's range is the range of values that the axis will display in pixels. This is most useful for adjusting the sizing of the data inside of the chart's drawing area.

You can pass in either an object (AxisBounds) with min and max properties (both optional), or a function that receives initial AxisBounds and returns an adjusted AxisBounds.

Live Code

<CartesianChart
  height={250}
  series={[
    {
      id: 'prices',
      data: [10, 22, 29, 45, 98, 45, 22, 52, 21, 4, 68, 20, 21, 58],
    },
  ]}
  yAxis={{
    range: ({ min, max }) => ({ min: min + 96, max: max - 96 }),
  }}
>
  <Line seriesId="prices" showArea />
</CartesianChart>

Axis Props

Properties related to the visual appearance of the YAxis are set on the component itself. This includes position, showGrid, showLine, showTickMarks, size, tickInterval, ticks, tickLabelFormatter, and tickMarkSize.

Position

You can set the position of an axis to left or right (default).

Live Code

<CartesianChart
  enableScrubbing
  height={512}
  series={[
    {
      id: 'linear',
      yAxisId: 'linearAxis',
      data: [1, 10, 30, 50, 70, 90, 100],
      label: 'linear',
    },
    { id: 'log', yAxisId: 'logAxis', data: [1, 10, 30, 50, 70, 90, 100], label: 'log' },
  ]}
  xAxis={[{ data: [1, 10, 30, 50, 70, 90, 100] }]}
  yAxis={[
    { id: 'linearAxis', scaleType: 'linear' },
    { id: 'logAxis', scaleType: 'log' },
  ]}
>
  <YAxis showLine showTickMarks axisId="logAxis" position="left" />
  <YAxis showLine showTickMarks axisId="linearAxis" />
  <Line curve="natural" seriesId="linear" />
  <Line curve="natural" seriesId="log" />
  <Scrubber />
</CartesianChart>

When layout="horizontal", CartesianChart supports only one y-axis configuration.

Grid

You can show grid lines at each tick position using the showGrid prop.

Live Code

function YAxisGridExample() {
  const [showGrid, setShowGrid] = useState(true);
  return (
    <VStack gap={2}>
      <HStack gap={2} style={{ flexWrap: 'wrap' }}>
        <Switch checked={showGrid} onChange={() => setShowGrid(!showGrid)}>
          Show Grid
        </Switch>
      </HStack>
      <CartesianChart
        enableScrubbing
        height={250}
        series={[
          {
            id: 'prices',
            data: [10, 22, 29, 45, 98, 45, 22, 52, 21, 4, 68, 20, 21, 58],
          },
        ]}
      >
        <YAxis showGrid={showGrid} />
        <Line seriesId="prices" showArea />
        <Scrubber />
      </CartesianChart>
    </VStack>
  );
}

You can also customize the grid lines using the GridLineComponent prop.

Live Code

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

  const categories = Array.from({ length: 31 }, (_, i) => `3/${i + 1}`);
  const gains = [
    5, 0, 6, 18, 0, 5, 12, 0, 12, 22, 28, 18, 0, 12, 6, 0, 0, 24, 0, 0, 4, 0, 18, 0, 0, 14, 10, 16,
    0, 0, 0,
  ];
  const losses = [
    -4, 0, -8, -12, -6, 0, 0, 0, -18, 0, -12, 0, -9, -6, 0, 0, 0, 0, -22, -8, 0, 0, -10, -14, 0, 0,
    0, 0, 0, -12, -10,
  ];
  const series = [
    { id: 'gains', data: gains, color: 'var(--color-fgPositive)', stackId: 'bars' },
    { id: 'losses', data: losses, color: 'var(--color-fgNegative)', stackId: 'bars' },
  ];

  return (
    <CartesianChart
      height={420}
      padding={4}
      series={series}
      xAxis={{ data: categories, scaleType: 'band' }}
    >
      <XAxis />
      <YAxis
        showGrid
        GridLineComponent={ThinSolidLine}
        tickLabelFormatter={(value) => `$${value}M`}
      />
      <BarPlot />
      <ReferenceLine LineComponent={SolidLine} dataY={0} />
    </CartesianChart>
  );
}

Line

You can show the axis line using the showLine prop.

Live Code

function YAxisLineExample() {
  const [showLine, setShowLine] = useState(true);
  return (
    <VStack gap={2}>
      <HStack gap={2} style={{ flexWrap: 'wrap' }}>
        <Switch checked={showLine} onChange={() => setShowLine(!showLine)}>
          Show Line
        </Switch>
      </HStack>
      <CartesianChart
        enableScrubbing
        height={250}
        series={[
          {
            id: 'prices',
            data: [10, 22, 29, 45, 98, 45, 22, 52, 21, 4, 68, 20, 21, 58],
          },
        ]}
      >
        <YAxis showLine={showLine} />
        <Line seriesId="prices" showArea />
        <Scrubber />
      </CartesianChart>
    </VStack>
  );
}

You can also customize the axis line using the classNames and styles props.

Live Code

function YAxisLineStylesExample() {
  const [showLine, setShowLine] = useState(true);
  return (
    <VStack gap={2}>
      <HStack gap={2} style={{ flexWrap: 'wrap' }}>
        <Switch checked={showLine} onChange={() => setShowLine(!showLine)}>
          Show Line
        </Switch>
      </HStack>
      <CartesianChart
        enableScrubbing
        height={250}
        series={[
          {
            id: 'prices',
            data: [10, 22, 29, 45, 98, 45, 22, 52, 21, 4, 68, 20, 21, 58],
          },
        ]}
      >
        <YAxis
          showLine={showLine}
          showGrid
          styles={{ line: { stroke: 'var(--color-accentBoldGreen)', strokeWidth: 4 } }}
        />
        <Line seriesId="prices" showArea />
        <Scrubber />
      </CartesianChart>
    </VStack>
  );
}

Size

The size prop sets the size of the axis in pixels. The default is 44 for YAxis, but can be adjusted to fit the size of your data.

Live Code

<CartesianChart
  height={400}
  series={[
    {
      id: 'growthExponential',
      data: [
        1, 2, 4, 8, 15, 30, 65, 140, 280, 580, 1200, 2400, 4800, 9500, 19000, 38000, 75000, 150000,
      ],
      color: 'var(--color-fgPositive)',
    },
  ]}
>
  <Line curve="natural" showArea seriesId="growthExponential" />
  <YAxis
    showGrid
    showLine
    showTickMarks
    requestedTickCount={6}
    width={70}
    tickLabelFormatter={(value) => value.toLocaleString()}
  />
</CartesianChart>

Ticks

You can use the ticks, requestedTickCount (default for YAxis), and tickInterval props to control the number and placement of ticks on the YAxis.

ticks accepts an array of numbers, which corresponds to the values of that axis that you would like to display ticks for.

Live Code

<CartesianChart
  enableScrubbing
  height={250}
  series={[
    {
      id: 'prices',
      data: [10, 22, 29, 45, 98, 45, 22, 52, 21, 4, 68, 20, 21, 58],
    },
  ]}
>
  <YAxis showLine showTickMarks showGrid ticks={[34, 56, 80]} />
  <Line seriesId="prices" showArea />
  <Scrubber />
</CartesianChart>

Using requestedTickCount will use D3's ticks function to determine the number and placement of ticks. Note that this count is not guaranteed to be respected.

This is the default behavior for YAxis, and defaults to 5.

Live Code

<CartesianChart
  enableScrubbing
  height={250}
  series={[
    {
      id: 'prices',
      data: [10, 22, 29, 45, 98, 45, 22, 52, 21, 4, 68, 20, 21, 58],
    },
  ]}
>
  <YAxis showLine showTickMarks showGrid requestedTickCount={5} />
  <Line seriesId="prices" showArea />
  <Scrubber />
</CartesianChart>

tickInterval, which accepts a number for the gap between ticks in pixels, will measure the available space and try to create evenly spaced ticks. It will always include the first and last values of the domain.

Live Code

<CartesianChart
  enableScrubbing
  height={250}
  series={[
    {
      id: 'prices',
      data: [10, 22, 29, 45, 98, 45, 22, 52, 21, 4, 68, 20, 21, 58],
    },
  ]}
>
  <YAxis showLine showTickMarks showGrid tickInterval={8} />
  <Line seriesId="prices" showArea />
  <Scrubber />
</CartesianChart>

Tick Marks

You can show tick marks on the axis using the showTickMarks prop. You can also customize the tick mark size using the tickMarkSize prop.

Live Code

function YAxisTickMarksExample() {
  const [showTickMarks, setShowTickMarks] = useState(true);
  return (
    <VStack gap={2}>
      <HStack gap={2} style={{ flexWrap: 'wrap' }}>
        <Switch checked={showTickMarks} onChange={() => setShowTickMarks(!showTickMarks)}>
          Show Tick Marks
        </Switch>
      </HStack>
      <CartesianChart
        enableScrubbing
        height={250}
        series={[
          {
            id: 'prices',
            data: [10, 22, 29, 45, 98, 45, 22, 52, 21, 4, 68, 20, 21, 58],
          },
        ]}
      >
        <YAxis showLine showTickMarks={showTickMarks} tickMarkSize={16} showGrid />
        <Line seriesId="prices" showArea />
        <Scrubber />
      </CartesianChart>
    </VStack>
  );
}

Tick Labels

You can customize the tick labels using the tickLabelFormatter prop.

Live Code

<CartesianChart
  enableScrubbing
  height={250}
  series={[
    {
      id: 'prices',
      data: [10, 22, 29, 45, 98, 45, 22, 52, 21, 4, 68, 20, 21, 58],
    },
  ]}
>
  <YAxis showGrid tickLabelFormatter={(value) => `$${value}`} />
  <Line seriesId="prices" showArea />
  <Scrubber />
</CartesianChart>

Label

You can add a label to the axis using the label prop.

Live Code

<CartesianChart
  enableScrubbing
  height={250}
  series={[
    {
      id: 'prices',
      data: [10, 22, 29, 45, 98, 45, 22, 52, 21, 4, 68, 20, 21, 58],
    },
  ]}
>
  <YAxis showGrid label="Price ($)" tickLabelFormatter={(value) => `$${value}`} />
  <Line seriesId="prices" showArea />
  <Scrubber />
</CartesianChart>

Custom Tick Labels

You can create custom tick label components using the TickLabelComponent prop for advanced styling and positioning that works cross-platform.

Live Code

function CustomTickLabelExample() {
  const CustomYAxisTickLabel = useCallback(
    (props) => <DefaultAxisTickLabel {...props} dx={4} dy={-12} horizontalAlignment="left" />,
    [],
  );

  return (
    <CartesianChart
      enableScrubbing
      height={250}
      series={[
        {
          id: 'prices',
          data: [10, 22, 29, 45, 98, 45, 22, 52, 21, 4, 68, 20, 21, 58],
        },
      ]}
    >
      <YAxis
        showGrid
        position="left"
        width={0}
        tickLabelFormatter={(value) => `$${value}`}
        TickLabelComponent={CustomYAxisTickLabel}
      />
      <Line seriesId="prices" showArea />
      <Scrubber />
    </CartesianChart>
  );
}

Customization

Multiple Y Axes

Live Code

<CartesianChart
  height={400}
  series={[
    {
      id: 'revenue',
      data: [455, 520, 380, 455, 285, 235],
      yAxisId: 'revenue',
      color: 'var(--color-accentBoldYellow)',
    },
    {
      id: 'profitMargin',
      data: [23, 20, 16, 38, 12, 9],
      yAxisId: 'profitMargin',
      color: 'var(--color-fgPositive)',
    },
  ]}
  xAxis={{
    data: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'],
    scaleType: 'band',
  }}
  yAxis={[
    {
      id: 'revenue',
      domain: { min: 0 },
    },
    {
      id: 'profitMargin',
      domain: { min: 0, max: 100 },
    },
  ]}
  inset={{ left: 0, right: 0 }}
>
  <XAxis showLine showTickMarks label="Month" />
  <YAxis
    showGrid
    showLine
    showTickMarks
    axisId="revenue"
    position="left"
    label="Revenue"
    width={80}
    requestedTickCount={5}
    tickLabelFormatter={(value) => `$${value}k`}
  />
  <YAxis
    showLine
    showTickMarks
    axisId="profitMargin"
    label="Profit Margin"
    width={70}
    requestedTickCount={5}
    tickLabelFormatter={(value) => `${value}%`}
  />
  <BarPlot />
</CartesianChart>

Basic Example​

Axis Config​

Scale Type​

Domain​

Domain Limit​

Range​

Axis Props​

Position​

Grid​

Line​

Size​

Ticks​

Tick Marks​

Tick Labels​

Label​

Custom Tick Labels​

Customization​

Multiple Y Axes​

Is this page useful?

Basic Example

Axis Config

Scale Type

Domain

Domain Limit

Range

Axis Props

Position

Grid

Line

Size

Ticks

Tick Marks

Tick Labels

Label

Custom Tick Labels

Customization

Multiple Y Axes