Points Levels List

React levels list with optional progress bar between tiers. Built on shadcn/ui + Tailwind. Open source.

Points Levels List is a vertical level-system UI for gamification progression—current tier, next milestone, and optional progress between thresholds in points- and XP-driven gamification experiences.

0-499

Beginner

500-2,499

Novice

2,500-4,999

Intermediate

5,000-7,499

Professional

7,500-9,999

Expert

10,000-19,999

Master

20,000-49,999

Grand Master

50,000+

Enlightened

Installation

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

Usage

import { PointsLevelsList } from "@/components/ui/points-levels-list"

<PointsLevelsList
  levels={[
    { id: "beginner", points: 0, name: "Beginner", iconType: "beginner" },
    { id: "novice", points: 500, name: "Novice", iconType: "novice" },
    {
      id: "intermediate",
      points: 2500,
      name: "Intermediate",
      iconType: "intermediate",
    },
    {
      id: "professional",
      points: 5000,
      name: "Professional",
      iconType: "professional",
    },
    { id: "expert", points: 7500, name: "Expert", iconType: "expert" },
    { id: "master", points: 10000, name: "Master", iconType: "master" },
    {
      id: "grand-master",
      points: 20000,
      name: "Grand Master",
      iconType: "grand-master",
    },
    {
      id: "enlightened",
      points: 50000,
      name: "Enlightened",
      iconType: "enlightened",
    },
  ]}
/>

Examples

Basic Usage

0-499

Beginner

500-2,499

Novice

2,500-4,999

Intermediate

5,000-7,499

Professional

7,500-9,999

Expert

10,000-19,999

Master

20,000-49,999

Grand Master

50,000+

Enlightened

<PointsLevelsList
  levels={[
    { id: "beginner", points: 0, name: "Beginner", iconType: "beginner" },
    { id: "novice", points: 500, name: "Novice", iconType: "novice" },
    {
      id: "intermediate",
      points: 2500,
      name: "Intermediate",
      iconType: "intermediate",
    },
    {
      id: "professional",
      points: 5000,
      name: "Professional",
      iconType: "professional",
    },
    { id: "expert", points: 7500, name: "Expert", iconType: "expert" },
    { id: "master", points: 10000, name: "Master", iconType: "master" },
    {
      id: "grand-master",
      points: 20000,
      name: "Grand Master",
      iconType: "grand-master",
    },
    {
      id: "enlightened",
      points: 50000,
      name: "Enlightened",
      iconType: "enlightened",
    },
  ]}
/>

Current Level

0-499

Beginner

500-2,499

Novice

2,500-4,999

Intermediate

5,000-7,499

ProfessionalYour current level

7,500-9,999

Expert

10,000-19,999

Master

20,000-49,999

Grand Master

50,000+

Enlightened

<PointsLevelsList
  currentPoints={6200}
  levels={[
    { id: "beginner", points: 0, name: "Beginner", iconType: "beginner" },
    { id: "novice", points: 500, name: "Novice", iconType: "novice" },
    {
      id: "intermediate",
      points: 2500,
      name: "Intermediate",
      iconType: "intermediate",
    },
    {
      id: "professional",
      points: 5000,
      name: "Professional",
      iconType: "professional",
    },
    { id: "expert", points: 7500, name: "Expert", iconType: "expert" },
    { id: "master", points: 10000, name: "Master", iconType: "master" },
    {
      id: "grand-master",
      points: 20000,
      name: "Grand Master",
      iconType: "grand-master",
    },
    {
      id: "enlightened",
      points: 50000,
      name: "Enlightened",
      iconType: "enlightened",
    },
  ]}
/>

With Progress

6,200 points. 1,300 until Expert

0-499

Beginner

500-2,499

Novice

2,500-4,999

Intermediate

5,000-7,499

ProfessionalYour current level

7,500-9,999

Expert

10,000-19,999

Master

20,000-49,999

Grand Master

50,000+

Enlightened

<PointsLevelsList
  currentPoints={6200}
  showProgressBar
  levels={[
    { id: "beginner", points: 0, name: "Beginner", iconType: "beginner" },
    { id: "novice", points: 500, name: "Novice", iconType: "novice" },
    {
      id: "intermediate",
      points: 2500,
      name: "Intermediate",
      iconType: "intermediate",
    },
    {
      id: "professional",
      points: 5000,
      name: "Professional",
      iconType: "professional",
    },
    { id: "expert", points: 7500, name: "Expert", iconType: "expert" },
    { id: "master", points: 10000, name: "Master", iconType: "master" },
    {
      id: "grand-master",
      points: 20000,
      name: "Grand Master",
      iconType: "grand-master",
    },
    {
      id: "enlightened",
      points: 50000,
      name: "Enlightened",
      iconType: "enlightened",
    },
  ]}
/>

With Trophy

Use the Trophy SDK to fetch user progress and system levels 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 PointsLevelsList props in your UI layer. Trophy does not support sub-levels yet.

const currentPoints = userPointsResponse.total

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

<PointsLevelsList
  levels={levels}
  currentPoints={currentPoints}
  showProgressBar
/>

API Reference

Props

Prop	Type	Default	Description
`levels`	`PointsLevelList[]`	Required	Ordered level definitions used to render point tiers and labels
`currentPoints`	`number`	-	User points total used to determine current level and progress
`showProgressBar`	`boolean`	`false`	Shows a progress header toward the next level when `currentPoints` is available
`currentLevelLabel`	`string`	`"Your current level"`	Label shown on the active row
`formatPoints`	`(value: number) => string`	-	Optional formatter for tier and progress values

Types

type PointsLevelListIconType =
  | "beginner"
  | "novice"
  | "intermediate"
  | "professional"
  | "expert"
  | "master"
  | "grand-master"
  | "enlightened"

interface PointsSubLevelList {
  name: string
  points: number
}

interface PointsLevelList {
  id: string
  key?: string
  name: string
  description?: string
  badgeUrl?: string | null
  points: number
  iconType?: PointsLevelListIconType
  subLevels?: PointsSubLevelList[]
}

Points Chart Points Levels Timeline

Raise an issue Contribute

On This Page

Installation Usage Examples Basic Usage Current Level With Progress With Trophy API Reference Props Types

Power Gamification with Trophy

Trophy powers the infrastructure you need to ship reliable gamification features at scale.

Get Started