GitHub

Points Awards

React points activity feed with dated events, totals, and trigger types for gamification timelines. Useful for XP and currency ledgers in dashboards. Built on shadcn/ui + Tailwind. Open source.

Points Awards surfaces what changed in a gamification ledger—grants, spends, bonuses, and campaign events in a readable timeline. Use when gamification UI needs transparency where trust grows when users see exactly how points moved.

May 8, 2026

20,176+13

May 7, 2026

20,163+15

May 7, 2026

20,148+12

May 6, 2026

20,136+20

May 5, 2026

20,116+8

May 4, 2026

20,108+10

Installation

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

Usage

Import the component:

import { PointsAwards } from "@/components/ui/points-awards"
<PointsAwards
  awards={[
    {
      id: "0040fe51-6bce-4b44-b0ad-bddc4e123534",
      awarded: 10,
      date: "2021-01-01T00:00:00Z",
      total: 100,
      trigger: {
        id: "0040fe51-6bce-4b44-b0ad-bddc4e123534",
        type: "metric",
        points: 10,
        metricName: "words written",
        metricThreshold: 1000,
      },
    },
  ]}
/>

Examples

Basic Usage

May 8, 2026

20,176+13

May 7, 2026

20,163+15

May 7, 2026

20,148+12

May 6, 2026

20,136+20

May 5, 2026

20,116+8

May 4, 2026

20,108+10

<PointsAwards
  awards={[
    {
      id: "1",
      awarded: 13,
      date: "2026-05-08T18:22:00.000Z",
      total: 20176,
      trigger: {
        id: "t-1",
        type: "metric",
        points: 13,
        metricName: "words written",
        metricThreshold: 1000,
      },
    },
    {
      id: "2",
      awarded: 15,
      date: "2026-05-07T12:00:00.000Z",
      total: 20163,
      trigger: {
        id: "t-2",
        type: "achievement",
        points: 15,
        achievementName: "Week warrior",
      },
    },
    {
      id: "3",
      awarded: 12,
      date: "2026-05-07T09:15:00.000Z",
      total: 20148,
      trigger: {
        id: "t-3",
        type: "streak",
        points: 12,
        streakLengthThreshold: 14,
      },
    },
  ]}
/>

With Trophy

Use the Trophy SDK to fetch the user's points data 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");

Pass the response into PointsAwards props in your UI layer:

const awards = response.awards ?? []

<PointsAwards awards={awards} />

Icon tooltips use trigger.metricName (and optional metricThreshold) for metric awards; achievementName, streak thresholds, trigger.type or custom types to cover other types of awards.

API Reference

Props

PropTypeDefaultDescription
awardsPointsAward[]RequiredEvents that awarded points
formatTotalPoints(value: number) => string-Optional formatter for each row's cumulative total
formatAwardedPoints(value: number) => string-Optional formatter for each row's awarded delta
formatDate(isoDate: string) => string-Optional formatter for each row's date (ISO string)

Types

interface PointsAwardTrigger {
  id: string
  type: string
  points: number
  metricName?: string | null
  metricThreshold?: number | null
  achievementName?: string | null
  streakLengthThreshold?: number | null
  timeUnit?: "hour" | "day"
  timeInterval?: number | null
}

interface PointsAward {
  id: string
  awarded: number
  date: string
  total: number
  trigger: PointsAwardTrigger
}
Raise an issue Contribute