Ranked list

A ranking as a list: position, name, value and a thin in-row bar, with an optional change indicator and highlighted rows.

Use when: A top-N list where the names matter as much as the values: league tables, best and worst performers, leaderboards with a movement column. It keeps long names readable and works in a narrow column.
Avoid when: Precise visual comparison of many values or more than about 15 rows (use bar chart); several measures per entity (use data table or comparison table); rank changing over time (use bump chart).

Preview

11% of commuting trips in Paris are made by bicycle

Share of commuting trips made by bicycle, selected European cities, with change since 2019

Rank 1CopenhagenDenmark49%Up +4%
Rank 2AmsterdamNetherlands35%Up +1%
Rank 3UtrechtNetherlands34%Up +2%
Rank 4MünsterGermany31%No change 0%
Rank 5AntwerpBelgium26%Up +5%
Rank 6MalmöSweden25%Down −1%
Rank 7BordeauxFrance13%Up +6%
Rank 8ParisFrance11%Up +7%

Source: City mobility surveys · Illustrative data

import { RankedList } from "insightcharts";

const data = [
  { city: "Copenhagen", country: "Denmark", share: 49, change: 0.04 },
  { city: "Amsterdam", country: "Netherlands", share: 35, change: 0.01 },
  { city: "Utrecht", country: "Netherlands", share: 34, change: 0.02 },
  { city: "Münster", country: "Germany", share: 31, change: 0 },
  { city: "Antwerp", country: "Belgium", share: 26, change: 0.05 },
  { city: "Malmö", country: "Sweden", share: 25, change: -0.01 },
  { city: "Bordeaux", country: "France", share: 13, change: 0.06 },
  { city: "Paris", country: "France", share: 11, change: 0.07 },
];

export function Example() {
  return (
    <RankedList
      title="11% of commuting trips in Paris are made by bicycle"
      subtitle="Share of commuting trips made by bicycle, selected European cities, with change since 2019"
      data={data}
      name="city"
      detail="country"
      value="share"
      format={"{value}%"}
      change="change"
      highlight="Paris"
      source="City mobility surveys"
      note="Illustrative data"
    />
  );
}

{
  "type": "ranked-list",
  "title": "11% of commuting trips in Paris are made by bicycle",
  "subtitle": "Share of commuting trips made by bicycle, selected European cities, with change since 2019",
  "data": [
    { "city": "Copenhagen", "country": "Denmark", "share": 49, "change": 0.04 },
    { "city": "Amsterdam", "country": "Netherlands", "share": 35, "change": 0.01 },
    { "city": "Utrecht", "country": "Netherlands", "share": 34, "change": 0.02 },
    { "city": "Münster", "country": "Germany", "share": 31, "change": 0 },
    { "city": "Antwerp", "country": "Belgium", "share": 26, "change": 0.05 },
    { "city": "Malmö", "country": "Sweden", "share": 25, "change": -0.01 },
    { "city": "Bordeaux", "country": "France", "share": 13, "change": 0.06 },
    { "city": "Paris", "country": "France", "share": 11, "change": 0.07 }
  ],
  "name": "city",
  "detail": "country",
  "value": "share",
  "format": "{value}%",
  "change": "change",
  "highlight": "Paris",
  "source": "City mobility surveys",
  "note": "Illustrative data"
}

Render with import { Insight } from "insightcharts" and <Insight spec={spec} />. Nested specs resolve by name; nothing else to import.

Composition

Built from

The pieces ranked list renders or expects in its slots.

Atoms

Delta

An inline change indicator: direction arrow, signed value and an optional baseline label.

Used in

1 template uses ranked list.

Templates

A recurring report. It has a masthead with the report name and period, a headline that states the main change, a KPI grid with changes and sparklines, a ranked list beside one or two trend charts, an optional comparison table, short notes and a source note.

Installation

$ pnpm dlx shadcn@latest add @insightcharts/ranked-list

The CLI copies the source into your project and needs the @insightcharts registry in components.json; see installation. With the package, import it by name:

import { RankedList } from "insightcharts";

Examples

Top five, no highlight

49% of commuting trips in Copenhagen are made by bicycle

Rank 1Copenhagen49%
Rank 2Amsterdam35%
Rank 3Utrecht34%
Rank 4Münster31%
Rank 5Antwerp26%

import { RankedList } from "insightcharts";

const data = [
  { city: "Copenhagen", country: "Denmark", share: 49, change: 0.04 },
  { city: "Amsterdam", country: "Netherlands", share: 35, change: 0.01 },
  { city: "Utrecht", country: "Netherlands", share: 34, change: 0.02 },
  { city: "Münster", country: "Germany", share: 31, change: 0 },
  { city: "Antwerp", country: "Belgium", share: 26, change: 0.05 },
  { city: "Malmö", country: "Sweden", share: 25, change: -0.01 },
  { city: "Bordeaux", country: "France", share: 13, change: 0.06 },
  { city: "Paris", country: "France", share: 11, change: 0.07 },
];

export function Example() {
  return (
    <RankedList
      data={data}
      name="city"
      value="share"
      format={"{value}%"}
      limit={5}
      title="49% of commuting trips in Copenhagen are made by bicycle"
    />
  );
}

{
  "type": "ranked-list",
  "data": [
    { "city": "Copenhagen", "country": "Denmark", "share": 49, "change": 0.04 },
    { "city": "Amsterdam", "country": "Netherlands", "share": 35, "change": 0.01 },
    { "city": "Utrecht", "country": "Netherlands", "share": 34, "change": 0.02 },
    { "city": "Münster", "country": "Germany", "share": 31, "change": 0 },
    { "city": "Antwerp", "country": "Belgium", "share": 26, "change": 0.05 },
    { "city": "Malmö", "country": "Sweden", "share": 25, "change": -0.01 },
    { "city": "Bordeaux", "country": "France", "share": 13, "change": 0.06 },
    { "city": "Paris", "country": "France", "share": 11, "change": 0.07 }
  ],
  "name": "city",
  "value": "share",
  "format": "{value}%",
  "limit": 5,
  "title": "49% of commuting trips in Copenhagen are made by bicycle"
}

Render with import { Insight } from "insightcharts" and <Insight spec={spec} />. Nested specs resolve by name; nothing else to import.

Places moved, long names, no bar

Three of the top five hospitals are in the Netherlands

Rank 1Erasmus University Medical Center Rotterdam94.1Up +2
Rank 2Karolinska University Hospital93.6Down −1
Rank 3Amsterdam University Medical Centers92.8No change 0
Rank 4Charité – Universitätsmedizin Berlin91.9Down −1
Rank 5University Medical Center Utrecht90.4Up +3

Illustrative data

import { RankedList } from "insightcharts";

const data = [
  { name: "Erasmus University Medical Center Rotterdam", score: 94.1, moved: 2 },
  { name: "Karolinska University Hospital", score: 93.6, moved: -1 },
  { name: "Amsterdam University Medical Centers", score: 92.8, moved: 0 },
  { name: "Charité – Universitätsmedizin Berlin", score: 91.9, moved: -1 },
  { name: "University Medical Center Utrecht", score: 90.4, moved: 3 },
];

export function Example() {
  return (
    <RankedList
      title="Three of the top five hospitals are in the Netherlands"
      data={data}
      name="name"
      value="score"
      change="moved"
      changeFormat="signed"
      bar={false}
      note="Illustrative data"
    />
  );
}

{
  "type": "ranked-list",
  "title": "Three of the top five hospitals are in the Netherlands",
  "data": [
    { "name": "Erasmus University Medical Center Rotterdam", "score": 94.1, "moved": 2 },
    { "name": "Karolinska University Hospital", "score": 93.6, "moved": -1 },
    { "name": "Amsterdam University Medical Centers", "score": 92.8, "moved": 0 },
    { "name": "Charité – Universitätsmedizin Berlin", "score": 91.9, "moved": -1 },
    { "name": "University Medical Center Utrecht", "score": 90.4, "moved": 3 }
  ],
  "name": "name",
  "value": "score",
  "change": "moved",
  "changeFormat": "signed",
  "bar": false,
  "note": "Illustrative data"
}

Render with import { Insight } from "insightcharts" and <Insight spec={spec} />. Nested specs resolve by name; nothing else to import.

Props

Prop	Type	Default	Description
data	DataInput		One row per entity. Omit inside `<InsightData>`.
transform	Transform \| Transform[]		Applied before ranking.
namerequired	string		Field naming each entity.
valuerequired	string		Field with the value that ranks them. Bars start at zero.
change	string		Field with a change shown at the end of each row: a number (0.12 is +12%) or a string.
changeFormat	FormatSpec	signed percent	Format for numeric changes, e.g. `"signed"` for places moved.
upIsGood	boolean	true	Whether a positive change is good news.
detail	string		Field with a short secondary line under each name.
sort	"desc" \| "asc" \| "none"	"desc"	Order by value; `none` keeps the data order.
limit	number		Show only the first N rows after sorting.
highlight	string \| string[]		Entity names to emphasise. The other bars are drawn in grey.
bar	boolean	true	Draw the in-row bar.
max	number		Value at which a bar is full. Default: the largest value shown.
format	FormatSpec	"auto"	Number format for the values.
title	string		The main fact with its number, or a plain label.
subtitle	string		Measure, population and period.
source	string		Shown under the list as "Source: ...".
note	string		Method note or caveat.
theme	ThemeInput		Theme override.
mode	"auto" \| "system" \| "light" \| "dark"	"auto"	Colour mode.