GitHub165

Milestone Grid

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.

Early Bird
First Steps
Task Master

Installation

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

Usage

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

Early Bird
First Steps
Task Master
<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

Early Bird
First Steps
Task Master
Marathon
API Explorer
Early Bird
First Steps
Task Master
Marathon
API Explorer
Early Bird
First Steps
Task Master
Marathon
API Explorer
// 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 large

Gap Sizes

Early Bird
First Steps
Task Master
Marathon
API Explorer
Early Bird
First Steps
Task Master
Marathon
API Explorer
Early Bird
First Steps
Task Master
Marathon
API Explorer
<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

Consistency I
3% of usersDaily Legend
12% of usersPower User
Consistency II
<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

PropTypeDefaultDescription
milestonesUserMilestone[]RequiredArray of milestones to display
columns2 | 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
}