XAxis | Coinbase Design System

XAxis

@coinbase/cds-web-visualization@3.4.0

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

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

Source

View as Markdown

Peer dependencies

framer-motion: ^10.18.0

Related components

Basic Example

The XAxis component provides a horizontal 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],
    },
  ]}
  xAxis={{
    data: ['April 1', 'April 2', 'April 3', 'April 4', 'April 5', 'April 6', 'April 7'],
  }}
>
  <XAxis showLine showTickMarks showGrid />
  <Line seriesId="prices" showArea />
  <Scrubber />
</CartesianChart>

Multiple X Axes (Horizontal Layout)

When layout="horizontal", you can configure multiple x-axes and bind each series to an axis with xAxisId. Use XAxis's axisId prop to render each axis configuration.

Live Code

<CartesianChart
  enableScrubbing
  height={300}
  layout="horizontal"
  series={[
    {
      id: 'temperature',
      label: 'Temperature',
      data: [72, 68, 74, 70],
      color: 'var(--color-accentBoldBlue)',
      xAxisId: 'temperature-axis',
    },
    {
      id: 'volume',
      label: 'Volume',
      data: [1200, 900, 1500, 1100],
      color: 'var(--color-accentBoldOrange)',
      xAxisId: 'volume-axis',
    },
  ]}
  xAxis={[
    {
      id: 'temperature-axis',
      domain: { min: 60, max: 80 },
      domainLimit: 'strict',
    },
    {
      id: 'volume-axis',
      domain: { min: 0, max: 2000 },
      domainLimit: 'strict',
    },
  ]}
  yAxis={{
    scaleType: 'band',
    data: ['Mon', 'Tue', 'Wed', 'Thu'],
  }}
>
  <YAxis showLine showTickMarks />
  <XAxis axisId="temperature-axis" label="Temp (F)" position="bottom" showLine />
  <XAxis axisId="volume-axis" label="Volume" position="top" showLine />
  <Line seriesId="temperature" />
  <Line seriesId="volume" />
  <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

XAxis supports linear (default), log, and band scale types. linear and log are numeric scales while band is a categorical scale. band scale is required for bar charts.

Live Code

<CartesianChart
  height={250}
  series={[
    {
      id: 'prices',
      data: [10, 22, 29, 45, 98, 45, 22, 52, 21, 4, 68, 20, 21, 58],
    },
  ]}
  xAxis={{
    scaleType: 'band',
  }}
>
  <XAxis showLine showTickMarks showGrid />
  <Line seriesId="prices" showArea />
</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],
    },
  ]}
  xAxis={{
    domain: ({ min, max }) => ({ min: min - 5, max: max + 5 }),
  }}
>
  <XAxis showLine showTickMarks showGrid tickInterval={16} />
  <Line seriesId="prices" showArea />
</CartesianChart>

Domain Limit

For numeric scales, you can set the domain limit to nice or strict (default for XAxis). 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],
    },
  ]}
  xAxis={{
    range: ({ min, max }) => ({ min, max: max - 64 }),
  }}
>
  <Line seriesId="prices" showArea />
</CartesianChart>

Data

Data sets x values for the axis.

String Data

Using string data will allow you to set string x values for each data point.

Live Code

<CartesianChart
  height={250}
  series={[
    {
      id: 'prices',
      data: [10, 22, 29, 45, 98, 45, 22, 52, 21, 4, 68, 20, 21, 58],
    },
  ]}
  xAxis={{
    data: ['April 1', 'April 2', 'April 3', 'April 4', 'April 5', 'April 6', 'April 7'],
  }}
>
  <XAxis showLine showTickMarks showGrid />
  <Line seriesId="prices" showArea />
</CartesianChart>

Number Data

Using number data with a numeric scale will allow you to adjust the x values for each data point.

Live Code

<LineChart
  enableScrubbing
  series={[
    {
      id: 'line',
      data: [2, 5.5, 2, 8.5, 1.5, 5],
    },
  ]}
  height={250}
  showArea
  points
  curve="natural"
  showXAxis
  xAxis={{ data: [1, 2, 3, 5, 8, 10], showLine: true, showTickMarks: true, showGrid: true }}
  showYAxis
  yAxis={{
    domain: { min: 0 },
    position: 'left',
    showLine: true,
    showTickMarks: true,
    showGrid: true,
  }}
>
  <Scrubber />
</LineChart>

Category Padding

For band scales, you can set the category padding to adjust the spacing between categories. The default is 0.1. This is a value between 0 and 1, where 0.1 = 10% spacing.

Live Code

<BarChart
  showXAxis
  height={400}
  series={[
    {
      id: 'weekly-data',
      data: [45, 52, 38, 45, 19, 23, 32],
    },
  ]}
  xAxis={{
    data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
    showTickMarks: true,
    showLine: true,
    categoryPadding: 0.5,
  }}
/>

Axis Props

Properties related to the visual appearance of the XAxis 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 top or bottom (default).

Live Code

function XAxisPositionExample() {
  const lineA = [5, 5, 10, 90, 85, 70, 30, 25, 25];
  const lineB = [90, 85, 70, 25, 23, 40, 45, 40, 50];

  const timeData = useMemo(
    () =>
      [
        new Date(2023, 7, 31),
        new Date(2023, 7, 31, 12),
        new Date(2023, 8, 1),
        new Date(2023, 8, 1, 12),
        new Date(2023, 8, 2),
        new Date(2023, 8, 2, 12),
        new Date(2023, 8, 3),
        new Date(2023, 8, 3, 12),
        new Date(2023, 8, 4),
      ].map((d) => d.getTime()),
    [],
  );

  const dateFormatter = useCallback(
    (index) => {
      return new Date(timeData[index]).toLocaleDateString('en-US', {
        month: '2-digit',
        day: '2-digit',
      });
    },
    [timeData],
  );

  const timeOfDayFormatter = useCallback(
    (index) => {
      return new Date(timeData[index]).toLocaleTimeString('en-US', {
        hour: '2-digit',
      });
    },
    [timeData],
  );

  const timeOfDayTicks = useMemo(() => {
    return timeData.map((d, index) => index);
  }, [timeData]);

  const dateTicks = useMemo(() => {
    return timeData.map((d, index) => index).filter((d) => d % 2 === 0);
  }, [timeData]);

  return (
    <LineChart
      enableScrubbing
      height={400}
      series={[
        {
          id: 'lineA',
          data: lineA,
          color: 'var(--color-accentBoldBlue)',
        },
        {
          id: 'lineB',
          data: lineB,
          color: 'var(--color-accentBoldGreen)',
        },
      ]}
      yAxis={{
        domain: { min: 0, max: 100 },
      }}
    >
      <XAxis
        showLine
        showTickMarks
        position="top"
        tickLabelFormatter={dateFormatter}
        ticks={dateTicks}
      />
      <XAxis
        showGrid
        showLine
        showTickMarks
        tickLabelFormatter={timeOfDayFormatter}
        ticks={timeOfDayTicks}
      />
      <Scrubber />
    </LineChart>
  );
}

Grid

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

Live Code

function XAxisGridExample() {
  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],
          },
        ]}
        xAxis={{
          data: ['April 1', 'April 2', 'April 3', 'April 4', 'April 5', 'April 6', 'April 7'],
        }}
      >
        <XAxis showLine showTickMarks 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} />);

  return (
    <CartesianChart
      enableScrubbing
      height={250}
      series={[
        {
          id: 'prices',
          data: [10, 22, 29, 45, 98, 45, 22, 52, 21, 4, 68, 20, 21, 58],
        },
      ]}
      xAxis={{
        data: ['April 1', 'April 2', 'April 3', 'April 4', 'April 5', 'April 6', 'April 7'],
      }}
    >
      <XAxis showLine showTickMarks showGrid GridLineComponent={ThinSolidLine} />
      <Line seriesId="prices" showArea />
      <Scrubber />
    </CartesianChart>
  );
}

On band scales, you can also use bandGridLinePlacement to control where grid lines appear relative to each band.

Using edges will place a grid line at the start of each band, plus a grid line at the end of the last band.

Live Code

function BandGridPlacement() {
  const bandGridLinePlacements = [
    { id: 'edges', label: 'Edges' },
    { id: 'start', label: 'Start' },
    { id: 'middle', label: 'Middle' },
    { id: 'end', label: 'End' },
  ];
  const [selectedBandGridPlacement, setSelectedBandGridPlacement] = useState(
    bandGridLinePlacements[0],
  );

  return (
    <VStack gap={2}>
      <HStack justifyContent="flex-end" gap={2} alignItems="center">
        <Text as="h3" font="headline">
          Band Grid Placement
        </Text>
        <SegmentedTabs
          activeTab={selectedBandGridPlacement}
          onChange={setSelectedBandGridPlacement}
          tabs={bandGridLinePlacements}
        />
      </HStack>
      <CartesianChart
        height={250}
        series={[
          {
            id: 'prices',
            data: [10, 22, 29, 45, 98, 45, 22],
          },
        ]}
        xAxis={{
          scaleType: 'band',
          data: ['April 1', 'April 2', 'April 3', 'April 4', 'April 5', 'April 6', 'April 7'],
        }}
        yAxis={{ domain: { min: 0 } }}
      >
        <XAxis
          bandGridLinePlacement={selectedBandGridPlacement.id}
          GridLineComponent={SolidLine}
          showGrid
          showLine
          showTickMarks
        />
        <BarPlot />
      </CartesianChart>
    </VStack>
  );
}

Line

You can show the axis line using the showLine prop.

Live Code

function XAxisLineExample() {
  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],
          },
        ]}
        xAxis={{
          data: ['April 1', 'April 2', 'April 3', 'April 4', 'April 5', 'April 6', 'April 7'],
        }}
      >
        <XAxis showLine={showLine} showTickMarks showGrid />
        <Line seriesId="prices" showArea />
        <Scrubber />
      </CartesianChart>
    </VStack>
  );
}

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

Live Code

function XAxisLineStylesExample() {
  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],
          },
        ]}
      >
        <XAxis
          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 32 for XAxis, but can be adjusted to fit the size of your data.

Live Code

<CartesianChart
  enableScrubbing
  height={250}
  series={[
    {
      id: 'prices',
      data: [10, 22, 29, 45, 98, 45, 22, 52, 21, 4, 68, 20, 21, 58],
    },
  ]}
  xAxis={{
    data: ['April 1', 'April 2', 'April 3', 'April 4', 'April 5', 'April 6', 'April 7'],
  }}
>
  <XAxis showLine showTickMarks showGrid height={64} />
  <Line seriesId="prices" showArea />
  <Scrubber />
</CartesianChart>

Ticks

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

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],
    },
  ]}
>
  <XAxis showLine showTickMarks showGrid ticks={[0, 2, 4, 6]} />
  <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.

Live Code

<CartesianChart
  enableScrubbing
  height={250}
  series={[
    {
      id: 'prices',
      data: [10, 22, 29, 45, 98, 45, 22, 52, 21, 4, 68, 20, 21, 58],
    },
  ]}
>
  <XAxis showLine showTickMarks showGrid requestedTickCount={4} />
  <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],
    },
  ]}
>
  <XAxis showLine showTickMarks showGrid tickInterval={16} />
  <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 XAxisTickMarksExample() {
  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],
          },
        ]}
        xAxis={{
          data: ['April 1', 'April 2', 'April 3', 'April 4', 'April 5', 'April 6', 'April 7'],
        }}
      >
        <XAxis showLine showTickMarks={showTickMarks} tickMarkSize={16} showGrid />
        <Line seriesId="prices" showArea />
        <Scrubber />
      </CartesianChart>
    </VStack>
  );
}

On band scales, you can also use bandTickMarkPlacement to control where tick marks appear relative to each band.

Using edges will place a tick mark at the start of each band, plus a tick mark at the end of the last band.

Live Code

function BandTickMarkPlacement() {
  const bandTickMarkPlacements = [
    { id: 'middle', label: 'Middle' },
    { id: 'edges', label: 'Edges' },
    { id: 'start', label: 'Start' },
    { id: 'end', label: 'End' },
  ];
  const [selectedBandTickMarkPlacement, setSelectedBandTickMarkPlacement] = useState(
    bandTickMarkPlacements[0],
  );

  return (
    <VStack gap={2}>
      <HStack justifyContent="flex-end" gap={2} alignItems="center">
        <Text as="h3" font="headline">
          Band Tick Mark Placement
        </Text>
        <SegmentedTabs
          activeTab={selectedBandTickMarkPlacement}
          onChange={setSelectedBandTickMarkPlacement}
          tabs={bandTickMarkPlacements}
        />
      </HStack>
      <CartesianChart
        height={250}
        series={[
          {
            id: 'prices',
            data: [10, 22, 29, 45, 98, 45, 22],
          },
        ]}
        xAxis={{
          scaleType: 'band',
          data: ['April 1', 'April 2', 'April 3', 'April 4', 'April 5', 'April 6', 'April 7'],
        }}
        yAxis={{ domain: { min: 0 } }}
      >
        <XAxis
          bandTickMarkPlacement={selectedBandTickMarkPlacement.id}
          showLine
          showTickMarks
          tickMarkSize={8}
        />
        <BarPlot />
      </CartesianChart>
    </VStack>
  );
}

Tick Labels

You can customize the tick labels using the tickLabelFormatter prop. It will receive the x data value of the tick. Meaning, if data is provided for the axis, it will receive the string label for the tick.

Live Code

<CartesianChart
  enableScrubbing
  height={250}
  series={[
    {
      id: 'prices',
      data: [10, 22, 29, 45, 98, 45, 22, 52, 21, 4, 68, 20, 21, 58],
    },
  ]}
  xAxis={{
    data: ['April 1', 'April 2', 'April 3', 'April 4', 'April 5', 'April 6', 'April 7'],
  }}
>
  <XAxis showGrid tickLabelFormatter={(value) => `Day of ${value}`} />
  <Line seriesId="prices" showArea />
  <Scrubber />
</CartesianChart>

If no data is set for the axis, it will receive the regular number value of the tick, which is normally the index corresponding to each value in the series.

Live Code

<CartesianChart
  enableScrubbing
  height={250}
  series={[
    {
      id: 'prices',
      data: [10, 22, 29, 45, 98, 45, 22, 52, 21, 4, 68, 20, 21, 58],
    },
  ]}
  xAxis={{
    domain: { min: -4, max: 16 },
  }}
>
  <XAxis showGrid tickLabelFormatter={(value) => value * 2} />
  <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],
    },
  ]}
  xAxis={{
    data: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul'],
  }}
>
  <XAxis showLine showTickMarks showGrid label="Month" />
  <YAxis showGrid />
  <Line seriesId="prices" showArea />
  <Scrubber />
</CartesianChart>

Custom Tick Labels

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

Live Code

function CustomTickLabelExample() {
  const CustomXAxisTickLabel = useCallback(
    (props) => <DefaultAxisTickLabel {...props} color="var(--color-accentBoldBlue)" />,
    [],
  );

  return (
    <CartesianChart
      enableScrubbing
      height={250}
      series={[
        {
          id: 'prices',
          data: [10, 22, 29, 45, 98, 45, 22, 52, 21, 4, 68, 20, 21, 58],
        },
      ]}
      xAxis={{
        data: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul'],
      }}
    >
      <XAxis showLine showTickMarks showGrid TickLabelComponent={CustomXAxisTickLabel} />
      <YAxis showGrid />
      <Line seriesId="prices" showArea />
      <Scrubber />
    </CartesianChart>
  );
}

Basic Example​

Multiple X Axes (Horizontal Layout)​

Axis Config​

Scale Type​

Domain​

Domain Limit​

Range​

Data​

String Data​

Number Data​

Category Padding​

Axis Props​

Position​

Grid​

Line​

Size​

Ticks​

Tick Marks​

Tick Labels​

Label​

Custom Tick Labels​

Is this page useful?

Basic Example

Multiple X Axes (Horizontal Layout)

Axis Config

Scale Type

Domain

Domain Limit

Range

Data

String Data

Number Data

Category Padding

Axis Props

Position

Grid

Line

Size

Ticks

Tick Marks

Tick Labels

Label

Custom Tick Labels