useChart

The useChart hook provides a set of utilities to manage and format data for charts efficiently. It offers various helpers for:

• aggregating the series data to compute values such as totals, minimums, maximums, and percentages
• formatting numbers and dates
• querying color, size, and spacing tokens

Usage

import { useChart } from "@chakra-ui/charts"

const chart = useChart({
  data: [
    { date: "2024-01-01", revenue: 1000 },
    { date: "2024-01-02", revenue: 2000 },
    { date: "2024-01-03", revenue: 3000 },
  ],
  series: [{ name: "revenue", color: "blue.500" }],
})

Series

getKey

Returns the key for a given series item. It's an identity function but provides a typesafe way to access the series data.

const key = chart.getKey("revenue")

Aggregation

getTotal

Computes the total sum of a given series across all entries.

console.log(chart.getTotal("revenue")) // 6000

getMin

Finds the minimum value for a given key in the dataset.

console.log(chart.getMin("revenue")) // 1000

getMax

Finds the maximum value for a given key in the dataset.

console.log(chart.getMax("revenue")) // 3000

getValuePercent

Calculates the percentage of a value relative to the dataset or a given domain.

const percentage = chart.getValuePercent("revenue", 5000)
console.log(percentage) // 0.5

Formatting

formatNumber

Formats numbers using the current locale from EnvironmentProvider and Intl.NumberFormatOptions provided.

const format = chart.formatNumber({ style: "currency", currency: "USD" })
console.log(format(1000)) // "$1,000.00"

formatDate

Formats a date string based on locale settings.

const formatDate = chart.formatDate({ year: "numeric", month: "short" })
console.log(formatDate("2024-03-28")) // "Mar 2024"

Design Tokens

color

Retrieves a Chakra UI color token.

const barColor = chart.color("blue.500") // var(--chakra-colors-blue-500)

size

Retrieves a Chakra UI size token.

const chartSize = chart.size("4") // var(--chakra-sizes-4)

spacing

Retrieves a Chakra UI spacing token.

const barColor = chart.color("blue.500") // var(--chakra-colors-blue-500)
const chartPadding = chart.spacing("4") // var(--chakra-spacing-4)

Sorting

Automatically sorts the chart data based on a specified key and direction.

const chart = useChart({
  data: [
    { date: "2024-01-01", revenue: 1000 },
    { date: "2024-01-02", revenue: 2000 },
    { date: "2024-01-03", revenue: 3000 },
  ],
  sort: { by: "date", direction: "asc" },
  series: [{ name: "revenue", color: "blue.500" }],
})

Highlighting

When interacting with the chart legends, the series can be highlighted based on click or hover events. The highlightedSeries state is used to track which series is currently highlighted.

This is mostly useful when you have multiple series in the chart.

highlightedSeries

Tracks which series is currently highlighted.

setHighlightedSeries

Sets the highlighted series.

chart.setHighlightedSeries("revenue")

isHighlightedSeries

Checks if a series is highlighted.

const isActive = chart.isHighlightedSeries("revenue")

API Table