# BarList

A ranked list, with the bar behind the name rather than beside it.

- Group: Data
- Import: `import { BarList } from '@misoto22/design/charts'`
- Page: https://ui.misoto22.com/components/bar-list/
- Related: bar-chart, table

## When to reach for it

Top referrers, slowest endpoints, biggest accounts. A horizontal BarChart spends a third of its width on an axis repeating labels the rows could simply contain.

## Accessibility

- A real <table> with two columns and one row per thing, because that is what a ranked list is. The bar is a background on the name cell, so it is never a second element a screen reader has to walk past.
- limit sums the tail into an “Other” row rather than dropping it — a top five that silently discards the other forty misstates the whole, and the reader has no way to tell.
- Pin max to compare two lists side by side: on independent scales the leading row of each fills its track, and two very different numbers look identical.

## BarList

A ranked list, with the bar behind the name rather than beside it. The answer to "top referrers", "slowest endpoints", "biggest accounts" — and a better one than a horizontal bar chart, which spends a third of its width on a category axis repeating labels the rows could simply contain. Reading a name off a y-axis and matching it to a bar is two steps; reading it off the bar is none. It is a `<table>`, because that is what it is: two columns, a header, and one row per thing. The bar is a background on the name cell, so it never becomes a second element a screen reader has to walk past. Reach for `<BarChart orientation="horizontal">` instead when the categories are few and fixed and the axis is doing real work — a scale a reader needs to read values off, rather than a ranking they need to skim.

### Props

- `label` (required) — `string`. What the list ranks. Required: it names the table for a screen reader.
- `showLabel` — `boolean` default `false`. Prints the label above the list instead of hiding it from sight.
- `items` (required) — `BarListItem[]`.
- `limit` — `number`. Keeps the top N and folds the rest into one "Other" row.
- `formatValue` — `(value: number) => string` default `defaultTick`. Formats each value. Defaults to the same compact form the axes use.
- `max` — `number`. The scale's ceiling. Derived from the largest row when omitted. Pin it to compare two lists side by side — on independent scales the leading row of each fills its track, and two very different numbers look identical.
- `sort` — `boolean` default `true`. Sorts descending before rendering.
- `className` — `string`.

## Example — default

```tsx
'use client'

import { BarList } from '@misoto22/design/charts'

const referrers = [
  { name: 'google.com', value: 42_100 },
  { name: 'github.com', value: 18_800 },
  { name: 'news.ycombinator.com', value: 9_400 },
  { name: 'x.com', value: 6_120 },
  { name: 'reddit.com', value: 3_280 },
  { name: 'lobste.rs', value: 1_940 },
  { name: 'bsky.app', value: 1_100 },
  { name: 'linkedin.com', value: 640 },
]

export function Example() {
  // The bar sits BEHIND the name rather than beside it, which is what a
  // horizontal bar chart cannot do: reading a name off a y-axis and matching
  // it to a bar is two steps, and reading it off the bar is none.
  return <BarList label="Top referrers" showLabel items={referrers} />
}
```

## Example — limit

```tsx
'use client'

import { BarList } from '@misoto22/design/charts'

const referrers = [
  { name: 'google.com', value: 42_100, href: 'https://google.com' },
  { name: 'github.com', value: 18_800, href: 'https://github.com' },
  { name: 'news.ycombinator.com', value: 9_400, href: 'https://news.ycombinator.com' },
  { name: 'x.com', value: 6_120 },
  { name: 'reddit.com', value: 3_280 },
  { name: 'lobste.rs', value: 1_940 },
  { name: 'bsky.app', value: 1_100 },
  { name: 'linkedin.com', value: 640 },
]

export function Example() {
  // The tail is SUMMED into "Other" rather than dropped. A top three that
  // silently discards the other five misstates the whole, and the reader has
  // no way to tell it happened.
  return <BarList label="Top referrers" showLabel items={referrers} limit={3} />
}
```