GitHub165

Milestone Badge

Open source React milestone badge component with locked/unlocked states, progress rings and rarity support. Use to celebrate user progress in badges and collections. Built on shadcn/ui + Tailwind.

The Milestone Badge is the atomic unit of milestone UI—a compact tile that celebrates user progress, with locked and unlocked states, progress, and rarity built in. Compose with Milestone Card and Milestone Grid when you need to show milestones at scale.

Consistency I

Installation

npx shadcn@latest add https://ui.trophy.so/milestone-badge

Usage

import { MilestoneBadge } from "@/components/ui/milestone-badge"
<MilestoneBadge
  milestone={{
    id: "1",
    name: "Consistency I",
    trigger: "streak",
    achievedAt: "2024-01-01T00:00:00Z",
    progress: 28,
  }}
/>

Examples

Basic Usage

Consistency I
<MilestoneBadge
  milestone={{
    id: "1",
    name: "Consistency I",
    trigger: "streak",
    achievedAt: "2024-01-01T00:00:00Z",
    progress: 28,
  }}
/>

Badge Sizes

Early Bird
Early Bird
Early Bird
Early Bird
<MilestoneBadge
  milestone={{
    id: "1",
    name: "Consistency I",
    trigger: "streak",
    achievedAt: "2024-01-01T00:00:00Z",
    progress: 28,
  }}
  badgeSize="sm"
/>
<MilestoneBadge
  milestone={{
    id: "1",
    name: "Consistency I",
    trigger: "streak",
    achievedAt: "2024-01-01T00:00:00Z",
    progress: 28,
  }}
  badgeSize="default"
/>
<MilestoneBadge
  milestone={{
    id: "1",
    name: "Consistency I",
    trigger: "streak",
    achievedAt: "2024-01-01T00:00:00Z",
    progress: 28,
  }}
  badgeSize="lg"
/>
<MilestoneBadge
  milestone={{
    id: "1",
    name: "Consistency I",
    trigger: "streak",
    achievedAt: "2024-01-01T00:00:00Z",
    progress: 28,
  }}
  badgeSize="xl"
/>

Locked State

When milestone.achievedAt is null, the badge is shown in a locked state.

Consistency I
Perfectionist
<MilestoneBadge
  milestone={{
    id: "badge-1",
    name: "Consistency I",
    trigger: "streak",
    achievedAt: "2024-01-01T00:00:00Z",
  }}
/>
<MilestoneBadge
  milestone={{
    id: "badge-locked-1",
    name: "Perfectionist",
    trigger: "metric",
    achievedAt: null,
  }}
/>

Series Progress

Consistency I
Consistency II
Consistency III
Consistency IV
<MilestoneBadge
  milestone={{
    id: "series-1",
    name: "Consistency I",
    trigger: "streak",
    achievedAt: "2024-01-01T00:00:00Z",
    progress: 28,
  }}
/>

Rarity

3% of usersDaily Legend
12% of usersPower User
41% of usersFinisher
78% of usersFirst Win
<MilestoneBadge
  milestone={{
    id: "rare-1",
    name: "Daily Legend",
    trigger: "streak",
    achievedAt: "2024-01-01T00:00:00Z",
    rarity: 3,
  }}
/>

Clickable Milestone

Consistency I
<MilestoneBadge
  milestone={{
    id: "1",
    name: "Consistency I",
    trigger: "streak",
    achievedAt: "2024-01-01T00:00:00Z",
    progress: 28,
  }}
  onMilestoneClick={(milestone) => {
    openDetailModal(milestone)
  }}
/>

With Trophy

Use the Trophy SDK to fetch a user's milestones server-side. Milestones are served by Trophy's achievements API:

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

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

const response = await trophy.users.achievements("user-id");

Then pass the response into MilestoneBadge props in your UI layer:

const milestone = response[0]

<MilestoneBadge milestone={milestone} />

API Reference

PropTypeDefaultDescription
milestoneUserMilestoneRequiredMilestone data for this badge
badgeSize"sm" | "default" | "lg" | "xl""default"Badge size
onMilestoneClick(milestone) => void-Click handler

Types

interface Milestone {
  id: string
  name: string
  trigger: "metric" | "api" | "streak"
  badgeUrl?: string | null
  progress?: number // optional series progress from 0 to 100, unlocked only
  rarity?: number // optional rarity from 1 to 100 shown as "X% of users"
}

interface UserMilestone extends Milestone {
  achievedAt: string | null // null = locked
}