Responsive React milestone grid for displaying collections of badges with progress and rarity across breakpoints. Ideal milestone UI design for galleries and showcases in consumer apps. Open source, built on shadcn/ui + Tailwind.
Milestone Grid lays out badge collections in a scannable surface—balanced columns, spacing rhythm, and built-in rarity or completion metadata for trophy rooms and showcase-style milestone pages.
Installation
npx shadcn@latest add https://ui.trophy.so/milestone-gridUsage
import { MilestoneGrid } from "@/components/ui/milestone-grid"<MilestoneGrid
milestones={[
{
id: "1",
name: "Early Bird",
trigger: "api",
achievedAt: "2024-01-01T00:00:00Z",
},
{
id: "2",
name: "First Steps",
trigger: "streak",
achievedAt: "2024-01-03T00:00:00Z",
},
{
id: "3",
name: "Task Master",
trigger: "metric",
achievedAt: "2024-01-02T00:00:00Z",
},
]}
/>Examples
Basic Usage
<MilestoneGrid
milestones={[
{
id: "1",
name: "Early Bird",
trigger: "api",
achievedAt: "2024-01-01T00:00:00Z",
},
{
id: "2",
name: "First Steps",
trigger: "streak",
achievedAt: "2024-01-03T00:00:00Z",
},
{
id: "3",
name: "Task Master",
trigger: "metric",
achievedAt: "2024-01-02T00:00:00Z",
},
]}
/>Column Layouts
// Fixed columns
<MilestoneGrid
milestones={[
{ id: "1", name: "Early Bird", trigger: "api", achievedAt: "2024-01-01T00:00:00Z" },
{ id: "2", name: "First Steps", trigger: "streak", achievedAt: "2024-01-03T00:00:00Z" },
{ id: "3", name: "Task Master", trigger: "metric", achievedAt: "2024-01-02T00:00:00Z" },
]}
columns={2}
/>
<MilestoneGrid
milestones={[
{ id: "1", name: "Early Bird", trigger: "api", achievedAt: "2024-01-01T00:00:00Z" },
{ id: "2", name: "First Steps", trigger: "streak", achievedAt: "2024-01-03T00:00:00Z" },
{ id: "3", name: "Task Master", trigger: "metric", achievedAt: "2024-01-02T00:00:00Z" },
]}
columns={3}
/>
<MilestoneGrid
milestones={[
{ id: "1", name: "Early Bird", trigger: "api", achievedAt: "2024-01-01T00:00:00Z" },
{ id: "2", name: "First Steps", trigger: "streak", achievedAt: "2024-01-03T00:00:00Z" },
{ id: "3", name: "Task Master", trigger: "metric", achievedAt: "2024-01-02T00:00:00Z" },
]}
columns={4}
/>
// Auto-responsive (default)
<MilestoneGrid
milestones={[
{ id: "1", name: "Early Bird", trigger: "api", achievedAt: "2024-01-01T00:00:00Z" },
{ id: "2", name: "First Steps", trigger: "streak", achievedAt: "2024-01-03T00:00:00Z" },
{ id: "3", name: "Task Master", trigger: "metric", achievedAt: "2024-01-02T00:00:00Z" },
]}
columns="auto"
/>
// 2 cols mobile → 3 cols tablet → 4 cols desktop → 5 cols largeGap Sizes
<MilestoneGrid
milestones={[
{ id: "1", name: "Early Bird", trigger: "api", achievedAt: "2024-01-01T00:00:00Z" },
{ id: "2", name: "First Steps", trigger: "streak", achievedAt: "2024-01-03T00:00:00Z" },
{ id: "3", name: "Task Master", trigger: "metric", achievedAt: "2024-01-02T00:00:00Z" },
]}
gap="sm"
/>
<MilestoneGrid
milestones={[
{ id: "1", name: "Early Bird", trigger: "api", achievedAt: "2024-01-01T00:00:00Z" },
{ id: "2", name: "First Steps", trigger: "streak", achievedAt: "2024-01-03T00:00:00Z" },
{ id: "3", name: "Task Master", trigger: "metric", achievedAt: "2024-01-02T00:00:00Z" },
]}
gap="default"
/>
<MilestoneGrid
milestones={[
{ id: "1", name: "Early Bird", trigger: "api", achievedAt: "2024-01-01T00:00:00Z" },
{ id: "2", name: "First Steps", trigger: "streak", achievedAt: "2024-01-03T00:00:00Z" },
{ id: "3", name: "Task Master", trigger: "metric", achievedAt: "2024-01-02T00:00:00Z" },
]}
gap="lg"
/>MilestoneGrid composes the MilestoneBadge component internally. For visual badge options such as size, progress, rarity, and click handling, see Milestone Badge. Locked badges are determined by achievedAt === null on each item.
Complete Example
<MilestoneGrid
milestones={[
{
id: "complete-1",
name: "Consistency I",
trigger: "streak",
achievedAt: "2024-01-01T00:00:00Z",
progress: 28,
},
{
id: "complete-2",
name: "Daily Legend",
trigger: "streak",
achievedAt: "2024-01-01T00:00:00Z",
rarity: 3,
},
{
id: "complete-3",
name: "Power User",
trigger: "metric",
achievedAt: "2024-01-01T00:00:00Z",
rarity: 12,
},
{
id: "complete-4",
name: "Consistency II",
trigger: "streak",
achievedAt: "2024-01-01T00:00:00Z",
progress: 62,
},
]}
columns={4}
onMilestoneClick={handleClick}
/>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 MilestoneGrid props in your UI layer:
<MilestoneGrid milestones={response} />API Reference
MilestoneGrid
| Prop | Type | Default | Description |
|---|---|---|---|
milestones | UserMilestone[] | Required | Array of milestones to display |
columns | 2 | 3 | 4 | "auto" | "auto" | Number of grid columns |
gap | "sm" | "default" | "lg" | "default" | Gap between grid items |
badgeSize | "sm" | "default" | "lg" | "default" | Size of milestone badges |
onMilestoneClick | (milestone) => void | - | Click handler for milestones |
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
}