React components for building loyalty program interfaces with Loyalteez
npm install @loyalteez/react-components@loyalteez/react-components provides drop-in React components for building loyalty program interfaces. Launch polished loyalty experiences in hours instead of weeks.
bash
npm install @loyalteez/react-components
or
pnpm add @loyalteez/react-components
or
yarn add @loyalteez/react-components
`
Quick Start
`tsx
import {
BalanceDisplay,
TierBadge,
StreakCounter,
ToastProvider,
useToast
} from '@loyalteez/react-components';
import '@loyalteez/react-components/styles.css';
function App() {
return (
);
}
function MyLoyaltyWidget() {
const { reward } = useToast();
return (
);
}
`
Components
$3
| Component | Description |
|-----------|-------------|
| BalanceDisplay | Display LTZ balance with animated counter and dollar value |
| ProgressBar | Generic progress indicator with gradient/glow variants |
| TierBadge | Bronze/Silver/Gold/Platinum/Diamond tier badges with glow effects |
| Badge | Pre-styled badges: Featured, Sponsored, Premium, SoldOut, etc. |
$3
| Component | Description |
|-----------|-------------|
| PerkCard | Full perk card with image, badges, supply, price, actions |
| PerkCard.Root | Composable root for custom layouts |
| PerkCard.Image | Perk image with overlay badges |
| PerkCard.Content | Content container |
| PerkCard.Title | Perk title |
| PerkCard.Brand | Brand name and logo |
| PerkCard.Supply | Supply progress indicator |
| PerkCard.Price | LTZ price display |
| PerkCard.Actions | Claim/purchase buttons |
| SupplyProgress | Supply bar with urgency indicators |
$3
| Component | Description |
|-----------|-------------|
| StreakCounter | Daily/weekly streak with animated flame, milestones |
| Leaderboard | Top earners with medals, rank changes, current user highlight |
| ChallengeCard | Active challenges with timer, progress, rewards |
$3
| Component | Description |
|-----------|-------------|
| ToastProvider | Toast notification system context |
| useToast | Hook for showing reward/success/error toasts |
| ClaimModal | Transaction flow modal (idle→processing→success/error) |
| ConfettiExplosion | Canvas-based confetti celebration |
| useConfetti | Hook for imperative confetti control |
$3
| Component | Description |
|-----------|-------------|
| EmptyState | Flexible empty state with presets (noPerks, noFavorites, etc.) |
| Skeleton | Loading skeletons for cards, lists, balance displays |
| Tooltip | Smart-positioned tooltips with arrow |
| FilterBar | Filter dropdowns, search, sort, view toggle |
$3
| Effect | Description |
|--------|-------------|
| GlowEffect | Pulsing, breathing, heartbeat, flicker, rainbow glows |
| ShimmerEffect | Metallic, holographic, gold, frost, fire, neon, diamond shimmers |
| ParticleEffect | Coins, stars, embers, sparkles, confetti, snow, hearts |
| ShakeEffect | Horizontal, vertical, rotational, impact, vibrate, earthquake |
| CountEffect | Simple, slot machine, flip, cascade, scramble, typewriter |
| ToneProvider | Theme system with 10 presets (arcade, casino, cyberpunk, etc.) |
Examples
$3
`tsx
bestStreak={21}
showFlame
showMilestones
breakWarning={{ hoursRemaining: 4, show: true }}
/>
`
$3
`tsx
currentUserId="user123"
showMedals
showRankChange
showAvatars
/>
`
$3
`tsx
id: '1',
title: 'Daily Login',
description: 'Log in 7 days in a row',
progress: 5,
goal: 7,
status: 'active',
difficulty: 'medium',
reward: { amount: 500 },
endTime: '2024-12-31T23:59:59Z'
}}
onClaim={handleClaim}
/>
`
$3
`tsx
function RewardButton() {
const { reward, success, error } = useToast();
const handleClaim = async () => {
try {
await claimReward();
reward({ amount: 500, description: 'Daily bonus claimed!' });
} catch (e) {
error({ title: 'Claim failed', description: e.message });
}
};
return ;
}
`
$3
`tsx
onClose={() => setIsOpen(false)}
item={{ id: '1', title: 'Coffee Reward', cost: 500 }}
state={claimState} // 'idle' | 'confirming' | 'processing' | 'success' | 'error'
userBalance={1000}
onConfirm={handleClaim}
transactionHash={txHash}
explorerUrlTemplate="https://explorer.soneium.org/tx/{hash}"
/>
`
$3
`tsx
function Celebration() {
const { fire, props } = useConfetti();
return (
<>
);
}
`
$3
`tsx
`
Theming
$3
`css
:root {
/ Brand Colors /
--ltz-cyan: 0 224 255;
--ltz-purple: 108 51 234;
--ltz-pink: 255 63 164;
--ltz-green: 166 255 0;
/ Backgrounds /
--ltz-bg-primary: 10 12 28;
--ltz-bg-secondary: 26 29 46;
/ Text /
--ltz-text-primary: 255 255 255;
--ltz-text-secondary: 140 140 153;
/ Radius /
--ltz-radius: 0.75rem;
}
`
$3
`js
// tailwind.config.js
import { loyalteezPreset } from '@loyalteez/react-components/tailwind';
export default {
presets: [loyalteezPreset],
// ...
};
`
Framer Motion (Optional)
For enhanced animations, import from /motion:
`tsx
import {
BalanceDisplayMotion,
StreakCounterMotion,
LeaderboardMotion,
ChallengeCardMotion,
AnimatedList,
AnimatedItem
} from '@loyalteez/react-components/motion';
// Physics-based balance counter
// Animated flame with intensity levels
// Staggered entry animations for leaderboards
// Animated progress bars and timers
// Stagger animate any list
{items.map(item =>
`
$3
| Component | Features |
|-----------|----------|
| BalanceDisplayMotion | Spring-based number transitions |
| StreakCounterMotion | Physics-based flame, smooth count updates |
| LeaderboardMotion | Staggered entries, layout animations, rank changes |
| ChallengeCardMotion | Animated progress, pulsing timers, spring physics |
| AnimatedList | Generic stagger wrapper with presets (fade, slide, scale, spring, bounce) |
| AnimatedItem | Individual animated item control |
Requires framer-motion as a peer dependency:
`bash
pnpm add framer-motion
`
Effects Module 🎮
The Effects module provides game-like visual feedback for any UI element.
$3
`tsx
import { GlowEffect, PulseGlow, LegendaryGlow, RainbowGlow } from '@loyalteez/react-components';
// Pulsing cyan glow
Content
// Heartbeat gold glow for rewards
Premium
// Legendary rainbow glow
`
$3
`tsx
import { ShimmerEffect, HolographicShimmer, GoldShimmer } from '@loyalteez/react-components';
// Holographic on hover
New
// Auto gold shimmer for rewards
`
$3
`tsx
import { ParticleEffect, CoinBurst, StarBurst, EmberEffect } from '@loyalteez/react-components';
// Coin collect on reward
// Continuous ember particles
// Custom particle configuration
shape="star"
motion="burst"
colors={['#FFD700', '#FFA500', '#FF6B35']}
count={50}
intensity="intense"
/>
`
$3
`tsx
import { ShakeEffect, ErrorShake, ImpactShake, useShake } from '@loyalteez/react-components';
// Error shake on validation failure
// Impact shake on achievement unlock
// Imperative shake hook
function Component() {
const { shake, props } = useShake({ pattern: 'earthquake' });
return (
);
}
`
$3
`tsx
import { CountEffect, SlotCounter, ScrambleCounter, useCountUp } from '@loyalteez/react-components';
// Slot machine reveal
// Scramble then settle
// Imperative count hook
function PointsDisplay() {
const { countTo, props } = useCountUp();
return (
<>
);
}
`
$3
`tsx
import { ToneProvider, useTone, TONES } from '@loyalteez/react-components';
// Wrap your app with a tone
// Available tones:
// - default (Loyalteez signature)
// - arcade (bright, bouncy, retro)
// - casino (gold, luxury, high-stakes)
// - cyberpunk (neon, glitch, dark)
// - minimal (clean, subtle, professional)
// - playful (rounded, colorful, fun)
// - competitive (sports/esports energy)
// - fantasy (RPG, magical, mystical)
// - scifi (futuristic, tech, sleek)
// - retro (80s/90s nostalgia)
// Access current tone
function Component() {
const { tone, toneId, setTone } = useTone();
return ;
}
`
$3
`tsx
import { EFFECT_PRESETS } from '@loyalteez/react-components';
// Pre-configured effect combos:
// - coinCollect, levelUp, milestone, streak
// - success, error, warning
// - common, rare, epic, legendary, mythic
// Use with components:
`
Utilities
`ts
import {
formatLTZ, // 1500000 → "1,500,000"
formatCompact, // 1500000 → "1.5M"
formatLTZAsDollars, // 5000 → "$5.00"
cn // Tailwind class merge utility
} from '@loyalteez/react-components';
`
Documentation
- Storybook — Interactive component playground
- Full Documentation — API reference and guides
Development
`bash
Install dependencies
pnpm install
Start Storybook
pnpm dev
Run tests
pnpm test
Build library
pnpm build
Type check
pnpm typecheck
Lint
pnpm lint
``