Ranking
A leaderboard card for the tops of a dashboard: products, customers or countries. Read it as stacked rows or a vertical bar chart, each row carrying a position chip, a value and a relative-share bar.
- 1Trail Runner GTX
- 2Merino Base Tee
- 3Field Watch 38mm
- 4Studio Headphones
- 5Weekender Bag
Try it yourself. This one is live, and its code is right below.
- 1Trail Runner GTX
- 2Merino Base Tee
- 3Field Watch 38mm
- 4Studio Headphones
- 5Weekender Bag
Installation#
Usage#
Ranking is composed from named parts, like Card and Stat. The Ranking root owns the surface and variant; RankingList is a semantic <ol> so assistive tech announces the positions, and each RankingItem lays out a rank, content, and value. For bare ranked bars with no card around them, reach for the lightweight Bar List primitive instead.
The preview is yours to explore. Its code comes with a Pro license, paid once and used in every project.
Have a license? Unlock it here
- 1Footwear
- 2Apparel
- 3Accessories
- 4Audio
Anatomy#
import {
Ranking,
RankingHeader,
RankingTitle,
RankingDescription,
RankingAction,
RankingList,
RankingItem,
RankingRank,
RankingMedia,
RankingContent,
RankingLabel,
RankingMeta,
RankingValue,
RankingBar,
} from "@/components/ui/ranking"
<Ranking>
<RankingHeader>
<div>
<RankingTitle />
<RankingDescription />
</div>
<RankingAction />
</RankingHeader>
<RankingList>
<RankingItem>
<RankingRank />
<RankingMedia />
<RankingContent>
<RankingLabel />
<RankingMeta />
<RankingBar />
</RankingContent>
<RankingValue />
</RankingItem>
</RankingList>
</Ranking>Media and meta#
Give a row a face. RankingMedia is a tinted icon tile for things (products, countries); for people, drop an Avatar in the same slot. RankingMeta adds a muted second line under the label (a category, an order count) and RankingValue holds the figure in tabular-nums so the column stays aligned.
- 1JJordi Espinosa42 orders
- 2MMara Devlin38 orders
- 3LLiang Wei31 orders
- 4PPriya Nair27 orders
Relative bars#
RankingBar draws each row’s share of the leader from a value of 0–100, so the list reads as a chart at a glance. The fill width is a runtime value, so it rides a CSS variable (never a generated class) and animates when the data changes.
- 1Trail Runner GTX
- 2Merino Base Tee
- 3Field Watch 38mm
- 4Studio Headphones
- 5Weekender Bag
Vertical bars#
Set layout="bars" to read the same list as a vertical bar chart: RankingList turns into a row of full-height columns and each RankingBar grows from the bottom to its share. The columns are narrow, so lean on the Tooltip and wrap each RankingItem and surface the full detail on hover instead of squeezing it under the bar.
- 1,284Runner
- 968Tee
- 742Watch
- 511Audio
- 388Bag
Inline bars#
Set layout="inline" for a horizontal bar chart: the name holds a fixed column and a thick bar runs beside it. The bars rest neutral and ink is the hover: the bar under the pointer lights up, and a bar that takes keyboard focus as a tooltip trigger lights in the focus color. Nothing is lit at rest. highlight on a RankingBar pins ink on one bar, for a row that really is selected; it works in the other layouts too.
- Burgers
- Water
- Tobacco
- Beer
- Coconut
Bar tones#
tone sets a bar’s fill: blue, brand, neutral, success, warning, destructive or info, the same names and inks as the Chart’s series, so a Ranking beside a chart can carry its key. Put the leader in the brand and the rest in neutral when the list is about one row, or let a status tone report each row’s health. Set tone on the Ranking to paint every bar at once; a bar’s own tone wins over it, and highlight wins over both. In the inline layout the hovered bar still lights up in ink.
- 1Trail Runner GTX
- 2Merino Base Tee
- 3Field Watch 38mm
- 4Studio Headphones
- 5Weekender Bag
- Valencia
- Lyon
- Rotterdam
- Porto
Headline figure#
When the list breaks down a total, lead with the total. Ranking has no figure part of its own on purpose: the figure is the Stat’s StatValue, which renders outside a Stat, with a StatTrend beside it. Set them between the header and the list, so every card in a dashboard leads with the same figure and the same chip, and the description is free to say what the number counts.
- Spain
- United States
- Germany
- France
- Portugal
Interactive rows#
Pass interactive to a RankingItem for a clickable row: pointer, a hover wash that bleeds to the card edge, and a focus ring. The wash sits close to the rank chip, media tile, and bar track, so those nested surfaces step down to the card surface on hover to keep their definition instead of dissolving into the wash, while the highlighted leader chip holds its primary fill. Wire it with onClick and add a trailing chevron to signal the affordance.
- 1Trail Runner GTX1,284 units
- 2Merino Base Tee968 units
- 3Field Watch 38mm742 units
- 4Studio Headphones511 units
Variants#
default sits on a hairline border with a soft shadow; outline drops the shadow for flat, gridded dashboards; elevated trades the border for a lifted shadow.
- 1Trail Runner GTX
- 2Merino Base Tee
- 3Field Watch 38mm
- 1Trail Runner GTX
- 2Merino Base Tee
- 3Field Watch 38mm
- 1Trail Runner GTX
- 2Merino Base Tee
- 3Field Watch 38mm
API reference#
Ranking
The card root; owns the surface, layout and default bar tone, and shares them with every part through context. Forwards all native <div> props. Every part accepts className, merged last.
| Prop | Type | Default | Description |
|---|---|---|---|
| variant | "default" | "outline" | "elevated" | "default" | default is an edge ring with a soft shadow, outline a full-strength ring with no shadow, elevated the card fill with a lifted shadow. |
| layout | "list" | "bars" | "inline" | "list" | list stacks rows with a bar under the label, bars is a vertical bar chart, inline a horizontal chart with the bar beside a fixed name column. |
| tone | "blue" | "brand" | "neutral" | "success" | "warning" | "destructive" | "info" | - | The hue every RankingBar takes unless it sets its own. Unset, list and bars paint blue and inline rests neutral. |
| asChild | boolean | false | Render the root onto your own child element instead of a div. |
RankingHeader
The top row holding the title block and an action. Forwards all native <div> props.
RankingTitle
The card title. Forwards all native <div> props.
RankingDescription
Muted supporting text under the title. Forwards all native <div> props.
RankingAction
A trailing slot in the header (a menu, a link). Forwards all native <div> props.
RankingList
A semantic <ol>, so assistive tech announces the positions. Forwards all native <ol> props.
RankingItem
One row, an <li>. Forwards all native <li> props.
| Prop | Type | Default | Description |
|---|---|---|---|
| interactive | boolean | false | Adds a pointer, hover wash and focus ring for a clickable row; wire onClick yourself. Nested chips and the bar track step down to the card surface on hover. |
RankingRank
The square, tabular position chip. Forwards all native <span> props.
| Prop | Type | Default | Description |
|---|---|---|---|
| highlight | boolean | false | A filled primary chip for the leader; it keeps the fill through the row's hover wash. |
RankingMedia
A tinted icon tile for non-people rows (products, countries); use an Avatar for people. Renders an aria-hidden <div>.
RankingContent
The flexible middle column holding the label, meta and a list bar. Forwards all native <div> props.
RankingLabel
The row's name, truncated to one line. Forwards all native <div> props.
RankingMeta
A muted, truncated second line under the label. Forwards all native <div> props.
RankingValue
The row's tabular figure. Forwards all native <div> props.
RankingBar
The relative-share bar: a track <div> with a fill whose length rides a CSS variable. Forwards all native <div> props except children.
| Prop | Type | Default | Description |
|---|---|---|---|
| value* | number | - | Share of the leader, 0 to 100 (clamped). Drives the fill and animates on change. |
| tone | "blue" | "brand" | "neutral" | "success" | "warning" | "destructive" | "info" | - | This bar's hue, the Chart's series names. Falls back to the root's tone, then the layout's default. In inline the hovered bar still lights up in ink. |
| highlight | boolean | false | Pins this bar in ink; wins over tone. |
| CSS variable | Description |
|---|---|
| --ranking-bar | The fill's width (or height in bars) as a percentage, set from value. |