GitHub

Points Levels Timeline

Vertical React timeline for level progression. Supports sub-levels, thresholds, and level progress for gamification roadmaps. Complements Points Levels List. Built on shadcn/ui + Tailwind. Open source.

Points Levels Timeline tells a gamification leveling story top to bottom—which tiers users passed, current progress, and XP to the next level—built for progression-heavy gamification products. Use Points Levels List when you need a more compact view of level progression.

Bronze

75 - 149 XP

Silver

150 - 274 XP

Gold

275+ XP

Installation

npx shadcn@latest add https://ui.trophy.so/points-levels-timeline

Usage

Import the component:

import { PointsLevelsTimeline } from "@/components/ui/points-levels-timeline"

Examples

Basic Usage

Bronze

75 - 149 XP

Silver

150 - 274 XP

Gold

275+ XP

<PointsLevelsTimeline
  levels={[
    { id: "bronze", name: "Bronze", points: 75 },
    { id: "silver", name: "Silver", points: 150 },
    { id: "gold", name: "Gold", points: 275 },
  ]}
/>

With Sub-levels

Bronze

Bronze III 75 - 99 XP

Bronze II 100 - 124 XP

Bronze I 125 - 149 XP

75 - 149 XP

Silver

Silver III 150 - 189 XP

Silver II 190 - 229 XP

Silver I 230+ XP

150+ XP

<PointsLevelsTimeline
  levels={[
    {
      id: "bronze",
      name: "Bronze",
      points: 75,
      subLevels: [
        { name: "Bronze III", points: 75 },
        { name: "Bronze II", points: 100 },
        { name: "Bronze I", points: 125 },
      ],
    },
    {
      id: "silver",
      name: "Silver",
      points: 150,
      subLevels: [
        { name: "Silver III", points: 150 },
        { name: "Silver II", points: 190 },
        { name: "Silver I", points: 230 },
      ],
    },
  ]}
/>

Progress Tracking

Bronze

Current

Bronze III 75 - 99 XP

Bronze II 100 - 124 XP

Bronze I 125 - 149 XP

75 - 149 XP

Silver

Silver III 150 - 189 XP

Silver II 190 - 229 XP

Silver I 230 - 274 XP

150 - 274 XP

Gold

275+ XP

<PointsLevelsTimeline
  currentPoints={136}
  levels={[
    {
      id: "bronze",
      name: "Bronze",
      points: 75,
      subLevels: [
        { name: "Bronze III", points: 75 },
        { name: "Bronze II", points: 100 },
        { name: "Bronze I", points: 125 },
      ],
    },
    {
      id: "silver",
      name: "Silver",
      points: 150,
      subLevels: [
        { name: "Silver III", points: 150 },
        { name: "Silver II", points: 190 },
        { name: "Silver I", points: 230 },
      ],
    },
    { id: "gold", name: "Gold", points: 275 },
  ]}
/>

With Trophy

Use the Trophy SDK to fetch user progress server-side:

import { TrophyApiClient } from '@trophyso/node';

const trophy = new TrophyApiClient({
  apiKey: 'YOUR_API_KEY'
});

const response = await trophy.users.points("user-id", "points-system-key");

Use the Trophy SDK to fetch points system level definitions server-side:

import { TrophyApiClient } from '@trophyso/node';

const trophy = new TrophyApiClient({
  apiKey: 'YOUR_API_KEY'
});

const response = await trophy.points.levels("points-system-key");

Then aggregate both responses and pass them into PointsLevelsTimeline props in your UI layer. Trophy does not support sub-levels yet.

const currentPoints = userPointsResponse.total

const levels = (pointsLevelsResponse.levels ?? []).map((level) => ({
  ...level,
  subLevels: [],
}))

<PointsLevelsTimeline levels={levels} currentPoints={currentPoints} />

API Reference

Props

PropTypeDefaultDescription
levelsPointsLevelTimeline[]RequiredVertical list of levels
currentPointsnumber-User total used to derive current level and progress
currentLevelLabelstring"Current"Label shown next to the current level
formatPoints(value: number) => string-Optional formatter used when rendering computed ranges

Types

interface PointsSubLevelTimeline {
  name: string
  points: number
}

interface PointsLevelTimeline {
  id: string
  key?: string
  name: string
  description?: string
  badgeUrl?: string | null
  points: number
  subLevels?: PointsSubLevelTimeline[]
}
Raise an issue Contribute