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

Helper	Purpose
getSeries(item)	Finds details of a series item
getSeriesOpacity(name, fallback)	Controls series opacity
getTotal(key)	Computes total sum of a key
getMin(key)	Gets minimum value for a key
getMax(key)	Gets maximum value for a key
getValuePercent(key, value, domain)	Calculates percentage of a value
formatNumber(options)	Formats numbers based on locale
formatDate(options)	Formats dates based on locale
color(key)	Retrieves Chakra UI color token
size(key)	Retrieves Chakra UI size token
spacing(key)	Retrieves Chakra UI spacing token
data	The resolved chart data
highlightedSeries	Tracks highlighted series
setHighlightedSeries(name)	Sets highlighted series
isHighlightedSeries(name)	Checks if a series is highlighted