Ballmac UI home

Bar List

New

A ranked list of bars with the name and number on top of the bar, so both stay readable at any width. Rows can be links or buttons, a long list folds to its top few, and every value is real text.

v1.0.0Updated Oct 25, 2026Ships with a test
What changed

Installation

$ pnpm dlx shadcn@latest add @ballmac/bar-list

Usage

import { BarList } from "@/components/ballmac/bar-list"

The full example is in the Code tab above.

Examples

Rows as filter buttons

Visitors by country

  1. Number 1
  2. Number 2
  3. Number 3
  4. Number 4

Filtering by: France

API reference

PropTypeDefault
items*BarListItem[]—
title

Heading above the list.

string—
format

Formats each value. Defaults to a grouped number.

(value: number) => string(v) => nf.format(v)
limit

Shows only this many items, with a button to show the rest.

number—
sort

Sorts by value, largest first. Defaults to true.

booleantrue
showShare

Shows each item's share of the total as a percent.

booleanfalse
onSelect

Makes rows buttons. Called with the item id.

(id: string) => void—
selected

The id of the selected row, when `onSelect` is used.

string | null—

Also accepts the standard attributes of its root element.

Accessibility

KeyAction
ListAn ordered list; each row also says 'Number n' for screen readers
RowsLinks and buttons are native; buttons have pressed state
FoldA button with aria-expanded
ValuesWritten as text, with the share as a percent if asked, so nothing depends on bar length

Use with AI

items is [{ id, label, value, href?, icon?, hint? }]. Sorted by value unless sort is false. title, format(value), showShare (percent of total), limit (folds the rest behind a Show N more button). href makes a row a link; onSelect(id) with selected makes rows toggle buttons. The bar is decoration behind real text. With the shadcn MCP server set up (guide), ask your agent:

Add the Ballmac UI Bar List (@ballmac/bar-list) to this project with the shadcn MCP, then use it where it fits.

Use it for

  • Top pages, sources, countries, products or errors in an analytics view
  • A leaderboard where the label matters more than the shape

Not for

  • Comparing a few values precisely over time; use chart-bar
  • Part-to-whole with many parts; use treemap or split-bar

Registry JSON: https://ui.ballmac.com/r/bar-list.json

Credits

Free to use in personal and commercial projects.

Ballmac UI Pro

Need the whole screen, not one piece?

150 premium blocks (dashboards, settings, calendars, mail, shops, onboarding), a private shadcn registry and Figma tokens. Blocks that show data come with loading, empty and error states built in.

Not ready? Try three Pro blocks free

Leave your email and the blocks appear right here, ready to copy. Yours to use in any project.