Skip to content
garn

Bar List

A ranked list of label/value rows, each backed by a bar sized to its share of the max.

Stablev0.4.2added in v0.2.0@garn/ui/bar-list
On this page

Default

Top pages by views, ranked.

Installation

garn is copy-in — the garn CLI writes this component's source into your project, so you own and can edit it. It resolves any base files and installs the npm dependencies below for you.

terminal
npx garn-ui add bar-list
First time? Set up garn in your project
Registry
bar-list
Deps
None
Registry deps
utils

Import

import { BarList } from "@garn/ui/bar-list";

Props

The component's public props and their types.

color
Description
Default bar tint (token ref) for rows without their own `color`.
Type
string
Default
"var(--garn-chart-1)"
itemsRequired
Description
Rows to rank and render — each a `label` + `value`, optionally a `href` and per-row `color`.
Type
BarListItem[]
max
Description
Scale bars against this value instead of the largest row — use it to hold the axis fixed across lists. Defaults to the largest value present.
Type
number
sortOrder
Description
Row order: `"desc"` ranks largest-first, `"asc"` smallest-first, `"none"` keeps `items` order.
Type
"asc" | "desc" | "none"
Default
"desc"
valueFormatter
Description
Format the value shown at the row end.
Type
(value: number) => React.ReactNode
Default
(v) => v.toLocaleString()

Plus 281 inherited native <ol> attributes.

Styling

Target these data-slots and states, and remap these tokens, to restyle without forking the component.

[data-slot="bar-list"][data-slot="bar-list-item"]

When to use

Show a ranked breakdown — the top N items by a metric (pages, referrers, products, errors).

Reach for something else when

  • Comparing categories on a shared axis (use a Bar chart)
  • one measure vs a target (use Bullet)
  • a trend over time (use Sparkline/Line).

Overview

Bar List is the ranked-breakdown widget every dashboard needs — top pages, top referrers, top errors — a compact list where each row's bar shows its share of the largest value. It's not a bar chart: there are no axes and the emphasis is the ordering. Pure markup means it renders on the server and reads cleanly as a list to assistive tech.

Guidelines

Rank, don't plot. Bar List answers "what are the biggest N", not "how do these compare on an axis". For an axis comparison across categories use a Bar chart; for one value vs a target use Bullet.

Keep the value truthful and formatted. Pass a valueFormatter (compact, currency) so the number is legible, and let the bar carry the relative sense. It sorts descending by default — override with sortOrder only when input order is meaningful.

Tint from a token. The bar uses a --garn-chart-* token at low opacity so the label stays readable on top; set per-row color to distinguish categories when useful.

Best practices

Do
  • Provide a valueFormatter for large/compact/currency values.
  • Let it sort descending; set href to link rows.
Don't
  • Don't use it as a substitute for an axis-based bar chart.
  • Don't hand-pre-sort unless sortOrder="none" (input order) is intended.

Troubleshooting

Bars all look full.

Cause. max is below the largest value, or all values are equal.

Fix. Omit max to auto-scale to the peak, or pass a max ≥ the largest value.

Accessibility

Role
list
A1.3.1Info and Relationships
  • An ordered list (`<ol>`) of `label, value` rows — the ranking order is conveyed structurally.
  • The bar is decorative (`aria-hidden`); the value is read as text.
  • Rows with an `href` render as links.