# Bar list

A React component in [Beamline](https://beamline.io/)'s [Dashboard](https://beamline.io/components/dashboard) category. Live demo: https://beamline.io/components/bar-list

Ranked horizontal bars with label inside and value at the end — top pages, sources, customers.

## Use it for

- Ranking up to ~10 items by one measure.

## Not for

- Values over time → [bar-chart](https://beamline.io/components/bar-chart).
- Parts of a whole that must sum → [category-bar](https://beamline.io/components/category-bar) or [pie-chart](https://beamline.io/components/pie-chart).

## Anatomy

- value label (column heading)
- row: label line (icon, label truncated with its full text as title, value, share) over a 6 px meter bar

## Variants

- **tone**: accent, neutral
- **sort**: desc, asc, none

## States

- interactive (link/button rows, hover tint)
- unmeasured row (full hatched bar, “Not measured” in ink-3 where the value goes)
- empty
- loading (`loading`: `limit` rows, or 5, drawn to the real rows' shape under the real header, so the list keeps its height when the items arrive)

## Keyboard

- Rows are links or buttons when href/onSelect is set.

## Motion

Bars grow from zero once (duration-considered, stagger-item per row) and glide to a new width; CSS on foundation tokens, so the scope speed and reduced motion reach it. When the value changes, the change itself stays in view for a moment (_shared/delta-ghost): what was lost sits as a pale ghost under the fill, holds about 0.7 s and drains toward the new end; what was gained arrives lit and cools over about 1.3 s. The ghost spans the real before and after, never an in-between value; a run of changes the same way extends one ghost. Reduced motion: the ghost is shown still for 1.1 s, then removed.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `{ label, value\|null, icon?, href? }[]` | — |  |
| `format` | `(v) => string` | — |  |
| `share` | `boolean` | — |  |
| `limit` | `number` | — |  |
| `onSelect` | `(item) => void` | — |  |
| `style / ref` | `CSSProperties / native Ref` | — | native HTMLDivElement |
| `classNames` | `BarListClassNames` | — |  |
| `loading` | `boolean` | `false` | rows drawn to the real rows' shape (limit, or 5) while the items load, so the list keeps its height |

## Dependencies

`motion`

## Import

```tsx
import { BarList } from "@/components/bar-list/bar-list";
```

## Get it

Bar list is part of Beamline: 190 React components and screens your coding agent (Claude Code, Codex, Cursor or any MCP client) installs into your app through Beamline's MCP server, as a ready-built package or as plain React source you can change. $49 one payment (regular $200), no subscription, a year of updates, one licence for your whole team. [Get Beamline](https://beamline.io/checkout?pack=complete) · [Connect your agent](https://beamline.io/connect)

## More in Dashboard

- [App shell](https://beamline.io/components/app-shell): The frame for every app screen: collapsible sidebar with grouped navigation, top bar and page.
- [Category bar](https://beamline.io/components/category-bar): One bar split into labelled ranges with an optional marker that names its range.
- [Insight cards](https://beamline.io/components/insight-cards): Findings from an agent, one per page: the sentence, the series it is about with their change, a chart to scrub that names each point, and a follow-up…
- [Metric card](https://beamline.io/components/metric-card): A KPI: label, a value that rolls to each new number, the change with arrow, sign and tone, a trend line and context; unmeasured values are hatched, never…
- [Tracker](https://beamline.io/components/tracker): A row of status blocks for uptime, job runs or daily checks, with tooltips and a legend.