@tempered/hydrogen-drops

Product drop components and hooks for Shopify Hydrogen storefronts. Supports FCFS, raffle, timed, open edition, and exclusive drop models.

Installation

npm install @tempered/hydrogen-drops

Quick Start

import {
  DropProvider,
  DropCountdown,
  DropRegistrationForm,
  DropInventoryBadge,
  useDropStatus,
} from '@tempered/hydrogen-drops';

function App() {
  return (
    <DropProvider
      config={{
        apiUrl: 'https://dropforge.temperedtools.xyz',
        apiKey: 'df_live_...',
        shopDomain: 'my-store.myshopify.com',
      }}
    >
      <DropPage dropId="clx1234567890abcdefghij" />
    </DropProvider>
  );
}

function DropPage({ dropId }: { dropId: string }) {
  const { drop, isLoading } = useDropStatus({ dropId });

  if (isLoading) return <p>Loading...</p>;
  if (!drop) return <p>Drop not found</p>;

  return (
    <div>
      <h1>{drop.title}</h1>
      <DropCountdown dropId={dropId} />
      <DropInventoryBadge dropId={dropId} />
      <DropRegistrationForm dropId={dropId} />
    </div>
  );
}

Components

DropProvider

Wraps your app with DropForge configuration context.

| Prop | Type | Required | Description | |------|------|----------|-------------| | config | DropForgeConfig | Yes | API URL, key, and shop domain |

DropCountdown

Real-time countdown timer synced with server clock.

| Prop | Type | Default | Description | |------|------|---------|-------------| | dropId | string | Required | Drop identifier | | onExpired | () => void | - | Callback when countdown reaches zero | | expiredText | string | "Drop has started!" | Text shown when expired | | showLabel | boolean | true | Show context label | | renderCountdown | function | - | Custom render function |

DropRegistrationForm

Registration form with email validation and error handling.

| Prop | Type | Default | Description | |------|------|---------|-------------| | dropId | string | Required | Drop identifier | | buttonText | string | "Register" | Submit button text | | showNameField | boolean | false | Show name input | | showPhoneField | boolean | false | Show phone input | | onSuccess | (id: string) => void | - | Success callback | | onError | (error: string) => void | - | Error callback |

DropQueueStatus

Virtual queue display for FCFS drops.

| Prop | Type | Default | Description | |------|------|---------|-------------| | dropId | string | Required | Drop identifier | | sessionId | string | Required | Session identifier | | onAdmitted | () => void | - | Called when user is admitted | | pollInterval | number | 5000 | Queue poll interval (ms) |

DropInventoryBadge

Inventory availability display.

| Prop | Type | Default | Description | |------|------|---------|-------------| | dropId | string | Required | Drop identifier | | soldOutText | string | "Sold Out" | Sold out label | | showRemaining | boolean | true | Show remaining count |

DropAccessGate

Access verification gate for exclusive drops.

| Prop | Type | Default | Description | |------|------|---------|-------------| | dropId | string | Required | Drop identifier | | children | ReactNode | Required | Content shown after verification | | useAccessCode | boolean | true | Verify by access code | | useEmail | boolean | false | Verify by email |

Hooks

| Hook | Purpose | |------|---------| | useDropStatus | Fetch and poll drop status | | useDropCountdown | Server-synced countdown timer | | useDropRegistration | Registration form state management | | useDropQueue | Virtual queue join and position polling | | useDropInventory | Real-time inventory tracking |

All hooks require a parent DropProvider. All accept a dropId parameter.

API Functions

For custom integrations, use the API client functions directly:

import { fetchDropStatus, submitRegistration, trackAnalyticsEvent } from '@tempered/hydrogen-drops';

Requirements

• React 18 or 19
• DropForge Shopify app installed with API key
• Node 18+

License

MIT