React SDK

The React SDK (@streakdev/react) wraps the Web SDK with a provider, hooks, and UI components so you can render streak data without wiring low-level API calls.

Installation

npm install @streakdev/react @streakdev/web

@streakdev/react depends on @streakdev/web, so install both when bundling for React.

Quick Start

'use client';

import { StreakProvider, useStreak } from '@streakdev/react';

function StreakSummary() {
  const { streak, week, trigger, isLoading } = useStreak();

  if (isLoading) return <div>Loading streak…</div>;

  return (
    <div>
      <p>Current streak: {streak?.current ?? 0}</p>
      <button onClick={trigger}>Check in</button>
      <p>Last 7 days: {week.filter((day) => day.isCheckedIn).length}</p>
    </div>
  );
}

export default function StreakPage() {
  return (
    <StreakProvider projectId="proj_123" event="visit" userId="user_456">
      <StreakSummary />
    </StreakProvider>
  );
}

Provider Props

projectId (required) — Your project ID from the dashboard.
event — Widget event key (visit by default).
kind — Legacy alias for event.
userId or userHash — Provide a stable identity; userId will be hashed for you.
apiBase — Override the API base URL (defaults to production).
theme — Optional theme override for the returned widget state.

UI Components

The SDK ships with ready-made components you can drop into dashboards or onboarding flows:

import {
  StreakCounter,
  StreakCalendar,
  StreakMilestone,
} from '@streakdev/react';

export function StreakPanel() {
  return (
    <div>
      <StreakCounter size="lg" />
      <StreakCalendar view="week" />
      <StreakMilestone />
    </div>
  );
}

If you prefer the hosted widget UI, render the web component wrapper:

import { StreakWidget } from '@streakdev/react';

<StreakWidget projectId="proj_123" event="visit" position="bottom-right" />

When to use the Web SDK directly

Use @streakdev/web directly when you need server-side actions (like aliasUser with an admin token) or you want to wire events without React state.