Rank List
A ranking whose rows travel to their new place on springs when the numbers change.
Preview
"use client";
import { useState } from "react";
import { useAutoplay } from "../demo-context";
import { RankList } from "./RankList";
const rounds = [
[420, 380, 310, 260, 190],
[430, 512, 318, 260, 240],
[470, 530, 480, 300, 250],
[520, 540, 490, 560, 260],
[610, 560, 500, 570, 590],
];
const people = ["Ana", "Bruno", "Carla", "Diego", "Elisa"];
export default function Demo() {
const [turn, setTurn] = useState(0);
useAutoplay(() => setTurn((t) => t + 1), 1700);
const values = rounds[turn % rounds.length];
const items = people.map((label, i) => ({ id: label, label, value: values[i] }));
return <RankList label="Sales this month" items={items} />;
}Installation
npx @usefluid/cli add rank-listpnpm dlx @usefluid/cli add rank-listyarn dlx @usefluid/cli add rank-listbunx @usefluid/cli add rank-listInstall the engine.
Terminal npm i @usefluid/motionCopy these files into your project.
components/fluid/rank-list/RankList.tsx "use client"; import { useSpring } from "@usefluid/motion/react"; import { type CSSProperties, useMemo, useRef, useState } from "react"; import { type Ranked, rank, roundLike } from "./rank"; import styles from "./RankList.module.css"; const ROW = 60; const MOVE = { w: 13, z: 0.74 }; const ROLL = { w: 9, z: 1 }; type Props = { label: string; items: Ranked[]; order?: "desc" | "asc"; format?: Intl.NumberFormatOptions; locale?: string; color?: string; }; function Row({ item, place, number }: { item: Ranked; place: number; number: Intl.NumberFormat }) { const row = useRef<HTMLLIElement>(null); const out = useRef<HTMLSpanElement>(null); const [first] = useState(() => number.format(item.value)); useSpring( { y: place }, ({ y }, { y: v }) => { if (!row.current) return; row.current.style.transform = `translateY(${y * ROW}px) scale(${1 + Math.min(0.04, Math.abs(v) * 0.01)})`; row.current.style.zIndex = v < -0.05 ? "2" : "1"; }, MOVE, ); useSpring( { v: item.value }, ({ v }) => { if (out.current) out.current.textContent = number.format(roundLike(v, item.value)); }, ROLL, ); return ( <li ref={row} className={styles.row} data-top={place === 0 ? "" : undefined}> <span className={styles.place} aria-hidden> {place + 1} </span> <span className={styles.name}>{item.label}</span> <span ref={out} className={styles.value} aria-hidden> {first} </span> <span className={styles.hidden}>{number.format(item.value)}</span> </li> ); } export function RankList({ label, items, order = "desc", format, locale, color }: Props) { const key = JSON.stringify(format ?? {}); const number = useMemo(() => new Intl.NumberFormat(locale, JSON.parse(key)), [locale, key]); const ranked = rank(items, order); return ( <figure className={styles.root} style={color ? ({ "--fluid-accent": color, "--fluid-on-accent": "#ffffff" } as CSSProperties) : undefined}> <figcaption className={styles.label}>{label}</figcaption> <ol className={styles.list} style={{ height: ranked.length * ROW }}> {ranked.map((item, place) => ( <Row key={item.id} item={item} place={place} number={number} /> ))} </ol> </figure> ); }components/fluid/rank-list/rank.test.ts import { describe, expect, it } from "vitest"; import { rank, roundLike } from "./rank"; describe("rank", () => { it("orders by value, highest first", () => { const items = [ { id: "a", label: "Ana", value: 3 }, { id: "b", label: "Bia", value: 9 }, { id: "c", label: "Caio", value: 5 }, ]; expect(rank(items).map((i) => i.id)).toEqual(["b", "c", "a"]); }); it("keeps ties in the order they were given, so rows do not swap back and forth", () => { const items = [ { id: "x", label: "Xu", value: 4 }, { id: "y", label: "Yan", value: 4 }, ]; expect(rank(items).map((i) => i.id)).toEqual(["x", "y"]); expect(rank([...items].reverse()).map((i) => i.id)).toEqual(["y", "x"]); }); it("orders lowest first when asked, and does not change the input", () => { const items = [ { id: "a", label: "A", value: 2 }, { id: "b", label: "B", value: 1 }, ]; expect(rank(items, "asc").map((i) => i.id)).toEqual(["b", "a"]); expect(items[0].id).toBe("a"); }); }); describe("roundLike", () => { it("rounds a rolling number to the decimals of where it is going", () => { expect(roundLike(511.344, 540)).toBe(511); expect(roundLike(12.3456, 19.5)).toBe(12.3); expect(roundLike(0.12345, 0.25)).toBe(0.12); }); });components/fluid/rank-list/rank.ts export type Ranked = { id: string; label: string; value: number }; export function rank<T extends Ranked>(items: T[], order: "desc" | "asc" = "desc"): T[] { const sign = order === "desc" ? -1 : 1; return items .map((item, i) => ({ item, i })) .sort((a, b) => sign * (a.item.value - b.item.value) || a.i - b.i) .map(({ item }) => item); } export function roundLike(value: number, target: number): number { const decimals = Number.isFinite(target) ? (String(target).split(".")[1] ?? "").length : 0; return Number(value.toFixed(Math.min(decimals, 6))); }components/fluid/rank-list/RankList.module.css .root { display: grid; gap: 12px; width: min(100%, 380px); margin: 0; padding: 20px; border-radius: 24px; background: var(--fluid-surface); color: var(--fluid-text); font-family: var(--fluid-font); } .label { padding-left: 4px; color: var(--fluid-text-2); font-size: 14px; font-weight: 500; } .list { position: relative; margin: 0; padding: 0; list-style: none; } .row { position: absolute; top: 0; right: 0; left: 0; display: flex; align-items: center; gap: 14px; height: 52px; padding: 0 16px 0 10px; border-radius: 16px; background: color-mix(in srgb, var(--fluid-text) 5%, var(--fluid-surface)); will-change: transform; } .row[data-top] { background: var(--fluid-accent); color: var(--fluid-on-accent); } .place { display: grid; place-items: center; width: 32px; height: 32px; border-radius: 999px; background: color-mix(in srgb, currentColor 10%, transparent); font-size: 13px; font-weight: 600; font-variant-numeric: tabular-nums; } .name { flex: 1; min-width: 0; overflow: hidden; font-size: 15px; font-weight: 500; text-overflow: ellipsis; white-space: nowrap; } .value { font-size: 15px; font-weight: 600; font-variant-numeric: tabular-nums; } .hidden { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }Import the theme once, then point its variables at your own tokens.
layout.tsx import "@usefluid/motion/theme.css";
Usage
import { RankList } from "./RankList";
<RankList label="Sales this month" items={[{ id: "ana", label: "Ana", value: 610 }, { id: "bruno", label: "Bruno", value: 560 }]} />API reference
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | — | The title of the ranking. |
items | { id, label, value }[] | — | The rows. Ids must be stable: they tell which row moves where. |
order | "desc" | "asc" | "desc" | Highest first, or lowest first for times and costs. |
format | Intl.NumberFormatOptions | — | How values are written, as in Intl.NumberFormat. |
locale | string | the browser's | Locale for the values. |
Keyboard and screen readers
An ordered list in the ranked order, so screen readers read the places right. The rolling numbers are hidden from them; they read the final value. With reduced motion rows jump to their place.
Notes
Ties keep the order they were given, so rows never swap back and forth. A row that climbs passes over the others. Every colour comes from the --fluid-* variables, and the piece is yours to change.
How it is made
Each row has a spring for its place, so when the order changes the rows slide past each other instead of jumping, and a row that climbs passes over the rest. The values roll on springs of their own. The list is in ranked order in the page, so screen readers read the places right, and ties keep their order.
For your agent
For your agent
Add Rank List to my project with the Fluid library. Use RankList for the leaderboards and top lists of my dashboard, with stable ids for each row. Read my project first. Use my logo, my colours and my font through the --fluid-* variables. Keep 44px touch targets, visible focus and reduced motion. If I have no SVG logo, ask before making one up.