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-badgeUsage
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
| Prop | Type | Default | Description |
|---|---|---|---|
milestone | UserMilestone | Required | Milestone 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
}Power in-app personalization with Trophy
Trophy is the 1:1 customer engagement platform for consumer web and mobile apps: in-app streaks, milestones, points and leaderboards, plus AI lifecycle agents that personalize every message.
Get Started