Koala UI

Bar List

Pro

A ranked list of horizontal bars, one row per category: top pages, referrers, countries. The name sits on the bar, the value beside it, so nothing hides behind a hover.

Top pages

Views · last 30 days

Installation#

# One-time setup (tokens + lib helpers)npx koalaui-cli@latest init# Activate your Pro license (once per machine)npx koalaui-cli@latest login <key># Add this component (its dependencies come along)npx koalaui-cli@latest add chart

Usage#

BarList ships in the Chart folder and takes one prop that matters: data, a name and a value per row. It ranks the rows for you (largest first), sizes each bar against the largest, and prints the value beside every bar, so there is no tooltip and no axis to read. Give a row an href or an icon and it picks them up.

This example is part of Koala UI Pro

The preview is yours to explore. Its code comes with a Pro license, paid once and used in every project.

Get the code

Have a license? Unlock it here

Bar List or Ranking#

BarList is the lightweight list primitive: one component, one prop, no surface of its own, so it drops into a card, a popover or a sidebar. Ranking is the full leaderboard card, composed from parts, with a header, position chips, avatars, a headline figure and a vertical bars layout. Reach for a bar list when the bars are the content, and for Ranking when the list is a widget of its own.

Highlight#

A bar list is one series, so every bar wears one hue. When the story is one row, highlight turns it into an emphasis chart: the matching row keeps color and the rest go neutral gray. Pass a name, a key or a predicate. With onValueChange every row becomes a button; here picking a row moves the highlight.

Sign-ups by channel

Partner referrals

Folding the tail#

A long tail buries the leaders. maxItems keeps the first rows named and folds the rest into one neutral row, labelled by otherLabel, that always sits last whatever the sort. A single leftover row is shown as is: folding one row into “Other” would hide a name to save nothing. size="sm" tightens the rows for a dense card, and showShare adds each row’s percentage of the total.

Sessions by country

Top 5

  • United States18,24037%
  • Germany7,31015%
  • United Kingdom6,42013%
  • Spain4,98010%
  • France4,4109%
  • Other countries8,45017%

Accessibility#

The list is a semantic <ul> named by label, and each row reads as its name followed by its value (and share), the same text a sighted reader sees: the bars are decoration and hidden from assistive tech. Text never wears the data colour, so the name over the bar clears contrast in every theme. Rows with an href are links and rows with onValueChange are buttons, each with a 40px hit area and a visible focus ring. The bars grow in from the baseline once on mount, and hold still under prefers-reduced-motion.

API reference#

BarList

A semantic <ul>, one <li> per row. Forwards all native <ul> props except color and onSelect; className is merged last.

PropTypeDefaultDescription
data*BarListItem[]-One entry per row: { name, value, href?, icon?, key? }. A row with an href renders as a link.
sortOrder"descending" | "ascending" | "none""descending"Row order. none keeps the order of data. The folded "Other" row always comes last.
color"chart-1" | "chart-2" | ... | "chart-8""chart-1"The one hue every bar wears: a bar list is a single series. The fill is a light wash of it, so the name on top stays legible in every theme.
highlightstring | ((item: BarListItem) => boolean)-Emphasis: rows that match (by name or key, or by your predicate) keep color and every other row goes neutral.
valueFormatter(value: number) => string-Formats the value beside each bar; defaults to en-US grouping with up to two decimals.
maxItemsnumber-Rows to show before the tail folds into one neutral "Other" row. A single leftover row is shown as is rather than folded.
otherLabelstring"Other"The name of the folded row.
showSharebooleanfalseAdds a "% of total" column after the value; a sliver that would round to 0 reads <1%.
size"sm" | "md""md"md: 24px bars on 40px rows. sm: 20px bars on 32px rows with smaller type, for a dense card.
onValueChange(item: BarListItem) => void-Makes each row a button (or fires alongside an href link). Interactive rows are at least 40px tall, with a hover wash and a focus ring.
labelstring-Accessible name of the list, for example "Top pages by views".
Data attributeDescription
data-highlightedOn each bar-list-item that matches highlight.
data-otherOn the folded "Other" row.

FAQ#

Bar List is a single component that draws ranked bars and nothing else, so it fits inside any surface. Ranking is a composed leaderboard card with a header, position chips, media and a vertical bars layout. Use Bar List when you need the bars, Ranking when you need the whole card.