Bar List
A ranked list of label/value rows, each backed by a bar sized to its share of the max.
@garn/ui/bar-listDefault
Top pages by views, ranked.
- /21,068
- /pricing8,422
- /docs6,210
- /blog3,120
- /changelog1,290
Links
Linked rows with compact-formatted values.
- google.com9.8K
- github.com4.2K
- twitter.com2.1K
- reddit.com980
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.
npx garn-ui add bar-list- Registry
bar-list- Source
- bar-list.tsx
- Deps
- None
- Registry deps
utils
Import
import { BarList } from "@garn/ui/bar-list";Props
Generated from the component's TypeScript types.
color- Description
- Default bar tint (token ref) when a row has no `color`.
- Type
string
itemsRequired- Description
- No description.
- Type
BarListItem[]
max- Description
- Scale bars to this max (default: the largest value).
- Type
number
sortOrder- Description
- Sort rows by value. Default "desc" (ranking).
- Type
"asc" | "desc" | "none"
valueFormatter- Description
- Format the displayed value.
- Type
(value: number) => React.ReactNode
Plus 281 inherited native <ol> attributes.
Styling
Target these data-slots and remap these tokens to restyle without forking the component.
[data-slot="bar-list"][data-slot="bar-list-item"]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
- Provide a
valueFormatterfor large/compact/currency values. - Let it sort descending; set
hrefto link rows.
- 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.
Accessibility
- Role
list
- • 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.
- Status
- Stable
- Version
v0.3.0- Introduced
v0.2.0
garn doesn't yet record a per-release version history. This reflects the component's current lifecycle state; full changelog entries will appear once the metadata pipeline emits a lifecycle.history field.