Skip to content

shadcn.io is an independent project built on shadcn/ui

Free

Waffle chart

Shares as cells you can count, easier to compare than pie slices when the parts are small. Give it a total and the leftover cells become a progress track.

Charting library: TanStack Charts

Preview

Preview width

Installation

The command adds the example above to components/charts/ and, the first time, the chart kit to components/ui/charts/. Both are source files in your project from then on: read them, change them, delete what you don't use.

Sign in to get your install command
Free with an account. It carries your token, so the CLI installs everything in one go.
GoogleGitHub
Use email insteadNo credit card

Usage

Each item has a label and a value, filled in the order you list them. The grid is 10 by 10, so by default each cell is 1% of the sum.

<script setup lang="ts">
import { ChartTooltip, WaffleChart } from "@/components/ui/charts";

const data = [
  { label: "Card", value: 6160 },
  { label: "Wallet", value: 3140 },
  { label: "Bank transfer", value: 1900 },
];

const formatPayments = (value: number) => value.toLocaleString("en-US");
</script>

<template>
  <WaffleChart
    ariaLabel="Payments by method"
    class="max-w-72"
    :data="data"
    :format-value="formatPayments"
    value-label="Payments"
  >
    <ChartTooltip />
  </WaffleChart>
</template>

Anatomy

WaffleChart draws the whole grid from data. Its only child is an optional ChartTooltip, and a legend, if you want one, goes beside it.

<WaffleChart :columns="20" :data="data" :rows="5" shape="circle">
  <ChartTooltip />
</WaffleChart>
  • WaffleChart: Shares the cells out between the categories and draws the grid.
  • ChartTooltip: The hovered category's value and share.

Progress against a total

Set total above the sum of your values and the cells past the sum stay empty, as a muted track. A total below the sum is ignored. With 4,260 seats sold of 6,000, 71% of the cells fill.

shape="circle" draws dots instead of rounded squares.

Preview width

Grid size and fill order

columns and rows set the grid, 10 by 10 by default, so each cell is the total divided by their product. fill="columns" fills top to bottom, column by column, and each category reads as a band from left to right.

Values round to whole cells, and the rounding keeps the total right. A category smaller than half a cell can end up with none, so make the grid fine enough for your smallest one.

Preview width

With a legend

onHoverChange reports the hovered category's index. Keep it in state, pass it to a ChartLegend as hoveredIndex, and wrap both in ChartLegendHoverProvider so hovering either one lights the other. The example at the top of the page does this.

Customization

The kit is in your project, in components/ui/charts/: your framework's components over a shared core/. Change a default there and every chart picks it up.

class goes on the chart's container, so size and spacing are utility classes.

content on ChartTooltip gets the category as point: label, value, share, and the cells it fills out of totalCells.

gap (3 px) spaces the cells and radius rounds them, as a share of the side from 0 to 0.5. Colors come from each item's color, then from colors, then --chart-1 to --chart-5.

<ChartTooltip>
  <template #content="{ point }">
    <TooltipBox>
      <div class="grid gap-1 px-3 py-2 text-sm">
        <span class="font-medium">{{ String(point.label) }}</span>
        <span class="text-muted-foreground">
          {{ Number(point.cells) }} of {{ Number(point.totalCells) }} cells
        </span>
      </div>
    </TooltipBox>
  </template>
</ChartTooltip>

Where a part renders content of its own, you pass it in. In Vue:

  • ChartTooltip: <template #content="{ point, index }">
  • ChartLegend: <template #render-item="{ item, index, isHovered, isFaded, percentage }">

Loading state

With status="loading" the whole grid turns into muted cells that shimmer, and the pointer is ignored. On "ready" the categories fill in.

<WaffleChartLoading /> takes the same columns, rows, gap, shape and radius, so the placeholder matches the chart that replaces it.

Preview width

Animation

Cells pop in on a spring, one after another in fill order. :animate="false" skips the entrance, and so does reduced motion.

Theming

Every color in the kit is one of your theme's tokens or a mix of them, except --chart-positive, a fixed green. A preset or the .dark class restyles the chart, and overriding a token in your CSS changes it everywhere.

The empty cells past the categories, the track, are painted with --legend-track, the same token as a legend's progress bars.

TokenDefaultPaints
--chart-1your theme'sthe first series
--chart-2your theme'sthe second series
--chart-3your theme'sthe third series
--chart-4your theme'sthe fourth series
--chart-5your theme'sthe fifth series
--chart-tooltip-background--popoverthe tooltip panel
globals.css
:root {
  --chart-tooltip-background: var(--card);
}

Accessibility

The chart is an image named by ariaLabel ("Waffle chart" by default). The keyboard moves from category to category, not cell to cell, and each one shows its value and share when there's a ChartTooltip.

Tab
Moves focus to the chart.
Arrow Right
Moves to the next category. ArrowDown does the same.
Arrow Left
Moves to the previous category. ArrowUp does the same.
Home
Jumps to the first category.
End
Jumps to the last category.

API reference

Vue takes the same props as React, in camelCase or kebab-case, with class for className. Render props are scoped slots (#content), and callbacks such as onHoverChange can be written as listeners (@hover-change).

WaffleChart

PropType
datareadonly WaffleDatum[]

The categories, in fill order.

onHoverChange?(index: number | null) => void

Called with the hovered category's index, and null when the pointer leaves (pair it with a ChartLegend).

Type
(index: number | null) => void
total?number

The value of the whole grid: cells past the categories' sum stay empty (a track). Defaults to the sum, so the grid is full.

columns?number

Cells per row.

Default
10
rows?number

Rows of cells.

Default
10
gap?number

Gap between cells, in px.

Default
3
shape?"square" | "circle"

"square" cells (rounded by radius) or "circle" dots.

Type
"square" | "circle"
Default
"square"
radius?number

Corner radius of a square cell, as a share of its side (0 to 0.5).

Default
0.2
fill?"rows" | "columns"

Fill order: "rows" left to right from the top, "columns" top to bottom from the left.

Type
"rows" | "columns"
Default
"rows"
colors?readonly string[]

Category colours, in order (cycled). Defaults to --chart-1 … --chart-5.

formatValue?(value: number) => string

Formats a value in the tooltip.

Type
(value: number) => string
valueLabel?string

The value's name in the tooltip.

Default
"Value"
aspectRatio?string | number

Width over height: a number or a string such as "2 / 1". Defaults to the grid's own, columns / rows.

Type
string | number
height?number

A fixed height in px instead of an aspect ratio.

animate?boolean

Play the entrance: the cells pop in, in fill order.

Default
true
status?ChartStatus

"loading" draws a shimmering skeleton (the grid's muted cells) in place of the chart and ignores the pointer; switching to "ready" plays the entrance. Switching back to "loading" fades the chart out first.

Default
"ready"
loadingLabel?string

Text shown centered over the plot, with a shimmer, while status is "loading". Nothing is shown when it is unset or empty.

ariaLabel?string
ariaDescription?string
class?string

Extra class name for the chart's root element.

style?CSSProperties

Inline style for the chart's root element.

children?ReactNode

Carriers: ChartTooltip and the family's own.

ChartTooltip

PropType
showDatePill?boolean

Show the date pill that rides along the bottom of the plot.

Default
true
showCrosshair?boolean

Show the vertical crosshair line. Bar charts leave it off unless this is true (the dots and the category pill mark the bar).

Default
true
showDots?boolean

Show a dot on every series at the hovered position.

Default
true
dotVariant?"dot" | "ring"

Dot style: a filled "dot" or a transparent "ring" square. Read by BarChart only.

Type
"dot" | "ring"
Default
"dot"
dotSize?number

Dot radius in px.

Default
5
dotRadiusFraction?number

Corner radius of the "ring" variant as a fraction of its side (0 is square, 0.5 is a circle). Read by BarChart only.

Default
0.25
dotScale?number

Multiplier applied to the dot or ring size. Read by BarChart and LiveLineChart.

Default
1
dotStrokeWidth?number

Stroke width of the dots in px.

Default
2
indicatorColor?string | ((point: Record<string, unknown>) => string)

Color of the crosshair. Only a string is applied; the function form that bklit-ui accepts is ignored and the default is used.

Type
string | ((point: Record<string, unknown>) => string)
Default
"var(--chart-crosshair)"
#content?slot: { point, index }

Replaces the default tooltip panel body. Receives the hovered data row and its index; with pinnable, also whether the panel is pinned and a dismiss that unpins it (for a close button in a pinned panel's detail).

pinnable?boolean

A click (or Enter, or Space) on the chart pins the tooltip where it is: the panel takes the pointer, so its content can grow into detail and hold controls, until another click, Escape or dismiss lets it go.

Default
false
rows?(point: Record<string, unknown>) => { readonly color: string; readonly label: string; readonly value: string | number }[]

Replaces the default rows (one per series) with your own list of { color, label, value }.

Type
(point: Record<string, unknown>) => { readonly color: string; readonly label: string; readonly value: string | number }[]
dotColor?string | ((point: Record<string, unknown>, line: ChartLineConfig) => string)

Fill of the tooltip dots. A function receives the hovered row and the series config, and is called again each time the hovered row changes. Defaults to each series' color; a ProfitLossLine's dot takes the color of the hovered value's sign.

Type
string | ((point: Record<string, unknown>, line: ChartLineConfig) => string)
#default?slot

Extra content rendered below the rows in the default panel, for example marker details. Without it, a chart with ChartMarkers lists the markers on the hovered date there.

class?string

Extra class name for the tooltip panel.

springConfig?SpringConfig

Spring for the floating panel when matchCrosshair is on. Defaults to the chart's tooltip spring.

matchCrosshair?boolean

Make the floating panel follow the pointer with the same spring as the crosshair instead of damping.

Default
false
damping?number

Spring damping for the floating panel when matchCrosshair is off, on bklit's 0 to 100 scale: lower is bouncier, higher slower, 0 moves the panel instantly. The default, 20, is the snappy hover spring (stiffness 3600, damping 120); every other value is bklit's spring for it played six times faster.

Default
20
indicatorDasharray?string

Dash pattern of the crosshair. Omit for a solid line.

indicatorFadeEdges?IndicatorFadeEdges

Vertical fade of the crosshair: both ends, the top, the bottom, or none (solid).

Default
"both"
indicatorFadeLength?number

Size of the crosshair's fade, as a percentage of its height (2 to 40).

Default
10
indicatorEndColor?string

Bottom colour of the crosshair: it ramps from indicatorColor at the top to this at the bottom (composes with the fade).

indicatorEnd?"plot" | "point"

How far down the crosshair reaches: the whole plot, or down to the hovered point of the first series.

Type
"plot" | "point"
Default
"plot"
dotHaloBlur?number

Blur in px on the dots' halo, for a soft glow.

Default
0
topOffset?number

Extra gap in px between the top of the plot and the tooltip panel.

Default
0
dateLabels?readonly string[]

The date pill's text for each data row, in row order (pair it with XAxis labels).

boxSpringConfig?SpringConfig

Spring for the floating panel. Takes priority over matchCrosshair and damping.

indicatorWidth?IndicatorWidth

Thickness of the crosshair: a width in px, or "line" (1px), "thin" (2px), "medium" (4px) or "thick" (8px).

Default
"line"

ChartLegend

PropType
itemsLegendItem[]

The items to list.

hoveredIndex?number | null

Hovered item index (null for none). Pair it with onHover to share hover with a chart.

Type
number | null
Default
null
onHover?(index: number | null) => void

Called with the item index when the pointer enters a row, and null when it leaves.

Type
(index: number | null) => void
showProgress?boolean

Show a progress bar under each item that has a maxValue.

Default
false
showMarker?boolean

Show the colored dot before each label.

Default
true
showValue?boolean

Show each item's value.

Default
true
showPercentage?boolean

Show each item's percentage of maxValue, under its progress bar: it takes effect only with showProgress and an item maxValue, as in bklit-ui (chart-legend.tsx:115, where the plain row has no percentage). For a percentage without a bar, compose Legend with LegendValue showPercentage.

Default
the value of `showProgress`
formatValue?(value: number) => string

Formats each value.

Type
(value: number) => string
Default
en-US number format, for example "1,234"
title?string

Heading shown above the items.

class?string

Class names added to the legend container.

titleClassName?string

Class names added to the title, on top of the default title style.

itemClassName?string

Class names added to each row.

labelClassName?string

Class names that replace the default label text style.

valueClassName?string

Class names that replace the default value text style.

#render-item?slot: { item, index, isHovered, isFaded, percentage }

Renders a row yourself. Receives the item, its index, hover flags and its percentage of maxValue. When set, the show* options are ignored.

Type
slot: { item, index, isHovered, isFaded, percentage }

WaffleChartLoading

PropType
aspectRatio?string | number

Width over height: a number or a string such as "2 / 1". Defaults to the chart's own.

Type
string | number
height?number

A fixed height in px instead of an aspect ratio.

label?string

Text shown centered over the skeleton, with a shimmer. Nothing is shown when it is unset or empty.

class?string

Extra CSS class name for the placeholder's root element.

Default
""
radius?number

Corner radius of a square cell, as a share of its side (0 to 0.5).

Default
0.2
gap?number

Gap between cells, in px.

Default
3
shape?"square" | "circle"

"square" cells (rounded by radius) or "circle" dots.

Type
"square" | "circle"
Default
"square"
columns?number

Cells per row.

Default
10
rows?number

Rows of cells.

Default
10

Examples

4 examples on Vue, each live with its code and its own install command.

All 4 waffle chart examples