Bar List
Rank labeled values with a bar for each, relative to the largest.
A bar list ranks a short list of labeled values, such as top pages or traffic sources. Each row writes its label over a bar and its value at the end. The largest value fills the track and every other bar takes its share of it, so the rows compare at a glance. The rows keep the order of data, so sort the data to rank it.
Installation
pnpm dlx shadcn@4.18.0 add @siteplane/bar-listComplete the one-time setup first. Registry JSON lists source files and dependencies.
For this page’s examples, also install:
pnpm dlx shadcn@4.18.0 add @siteplane/toggle-groupUsage
import { BarList } from "@/siteplane/components/bar-list";
<BarList
label="Top pages"
data={[
{ id: "pricing", label: "/pricing", value: 8420 },
{ id: "installation", label: "/docs/installation", value: 5160 },
]}
/>;Formatted values
Values are written as numbers in the format of locale, en-US by default, such as 8,420. Pass formatValue to write them another way, such as a currency or with a unit. A value with digits rolls to its new value when the data changes; text without digits is written as it is.
Icons
An icon sits before the label of its row. Pass an svg element, such as a lucide icon, to take the icon size of the kit. The icon is decoration and hidden from assistive technology, so the label must name the row on its own.
Second line
A description adds a quieter second line under the label, such as the path under a page title. It is set in 13 px text in the secondary text color, which stays readable on the bar in both themes, and its row and bar grow to hold it while the value stays on the first line. Like the label, it stays on one line: a text that is too long ends in an ellipsis, and its title attribute keeps the full text, which the browser shows on hover.
Heading
Pass heading to name the two columns in a row above the list: its label stands over the labels and its value over the values, and a Separator runs between the heading and the rows. The heading is text that screen readers read before the list.
Changing data
When data changes, the list glides to it. Each bar moves to its new length and each value rolls. A row that is new grows its bar out of nothing, a row that is gone shrinks away and leaves, and the rows that stay move to their new places. Rows are told by their id, so give every row one that is unique in the list and stays the same.
Right-to-left
In right-to-left text the rows mirror: each bar starts on the right, the icon and the label sit on the right, and the values line up on the left. Set dir="rtl" on the page or on a container. Numbers still read from left to right.
API reference
| Prop | Type | Default | Description |
|---|---|---|---|
Bar | readonly BarListItem[] | required | The rows, in the order they are shown. Sort the data to rank it. |
Bar | string | required | Accessible name of the list. |
Bar | BarListHeading | unset | Names the two columns in a heading row above the rows, over a separator. |
Bar | (value: number) => string | Intl.NumberFormat(locale) | Writes the value at the end of each row. Text with digits rolls to its new value when it changes. |
Bar | string | en-US | Locale of the number format when formatValue is not given. |
Bar | string | lightest brand shade | A CSS color or token for the bars. |
Bar | string | No data | Shown in place of the rows when data is empty. |
Bar | string | unset | Additional classes for the list, or with a heading for the frame that holds the heading and the list. |
Bar | string | required | Stable key of the row, unique in the list. Its bar glides by it when the data changes. |
Bar | string | required | Text of the row, written over its bar. A label that does not fit on one line ends in an ellipsis, and its title attribute keeps the full text. |
Bar | string | unset | A quieter second line under the label, such as a path. It ends in an ellipsis when it does not fit, with the full text in its title attribute. |
Bar | number | required | Sets the length of the bar next to the largest value and is written at the end of the row. A value that is not a finite number counts as 0. |
Bar | ReactNode | unset | Shown before the label as decoration, hidden from assistive technology. An svg element takes the icon size of the kit. |
Bar | string | required | Name of the column of labels, such as Top pages, at the start of the heading row. |
Bar | string | required | Name of the column of values, such as Visitors, at the end of the heading row. |
BarListProps, BarListItem and BarListHeading export these contracts. The list
renders a ul with one li per row; with a heading it renders a div that
holds the heading row, the separator and the ul. It takes no native props or
ref beyond className.
Usage notes
Use a bar list for a short ranked list whose values should be seen next to the largest. When values can be negative or must be read against an axis, use a Bar Chart. For many rows or several values per row, use a Table.
Each bar is as long as its value is large next to the largest value, which fills the track. Any value above zero keeps at least 2% of the track, so a very small value is still a short bar and not a hairline. A value that is zero or negative has no bar, a negative value is still written as it is, and a value that is not a finite number counts as 0. All values share one column as wide as the widest, so every bar has the same track.
The rows are not interactive: they take no click, hover or focus, and they are not links. When a row must open or select something, use a Table, a List Box or a Resource List.
The bars take the lightest shade of the brand color. Each label is written over its bar, so a custom color should stay light enough to keep the labels readable. A label or a second line that does not fit on one line ends in an ellipsis, so every row keeps its height and the values stay in their column; the title attribute keeps the full text, and screen readers read it in full.
The list is named by label and is not a focus stop. Screen readers read each row’s label and value once; a rolling value is not announced while it changes. A row that is leaving is hidden from assistive technology.
The list renders completely on the server: each bar is a share of the track and needs no measuring. New data animates with the Motion tokens: bars and values with --motion-duration-value, rows that come, go or move with --motion-duration-expand, all with --motion-ease-standard. Under reduced motion new data shows at once: the system setting, html with data-motion-reduce="true" or SiteplaneMotionProvider preset="reduced".