Loyalty and Promo

Code

<LoyaltyCard name="Sara" balance={1840} tiers={tiers} memberCode="NSQ-4821" rewards={rewards} onRedeem={async (r) => api.redeem(r.id)} /><PromoCodeField applied={applied} currency="USD" onApply={async (code) => api.applyPromo(code)} onRemove={clear} />

Gamification · beta

Live examples and controls: Loyalty and Promo in the lab.

InstallCopy Anchor Link

npx shadcn@latest add https://docs.nasaqui.com/r/loyalty-promo.json

Everything for a returning customer: a card with points, tier progress, points about to expire, a member QR and rewards to redeem; the points ledger; a promo-code box for checkout; an admin list of promo codes; and the visit history with totals. Money is integer minor units and promo rules run in a pure function you can also use on your server.

When to useCopy Anchor Link

• Restaurants, salons, clinics and shops with points, tiers and discount codes.

When not to useCopy Anchor Link

• Game-style XP and badges: use gamification.

ImportCopy Anchor Link

import { LoyaltyCard, PromoCodeField, PromoCodeManager, PointsHistory, VisitHistory } from "@fadymondy/nasaq/web";

Quick startCopy Anchor Link

<LoyaltyCard name="Sara" balance={1840} tiers={tiers} memberCode="NSQ-4821" rewards={rewards} onRedeem={async (r) => api.redeem(r.id)} />
<PromoCodeField applied={applied} currency="USD" onApply={async (code) => api.applyPromo(code)} onRemove={clear} />

AnatomyCopy Anchor Link

LoyaltyCard         data-slot="loyalty-card"        name, tier, balance, progress to next tier, expiry note, QR, rewards
PointsHistory       data-slot="points-history"      signed entries with a kind label and the balance after
PromoCodeField      data-slot="promo-code-field"    input and Apply, or the applied code with its saving
PromoCodeManager    data-slot="promo-code-manager"  DataTable, create and edit dialog
VisitHistory        data-slot="visit-history"       stat cards and a DataTable

APICopy Anchor Link

Read the exported prop types in loyalty-promo.tsx for the exact fields. In short:

• LoyaltyCard: name, balance, optional lifetimePoints, tiers, lots (points with expiry), expiryWarningDays, memberCode, rewards, onRedeem, loading, labels.
• PointsHistory: entries (kind is earn, redeem, expire or adjust, with signed points), loading, labels.
• PromoCodeField: currency, optional applied, onApply(code) (resolve { error } to show why), onRemove, labels.
• PromoCodeManager: promos, currency, onSave(input, id?), optional onSetActive, onDelete, loading, labels. Percent values are basis points, fixed values are minor units. Row actions also open on context-click.
• VisitHistory: visits, currency, optional rowActions, loading, labels.

Pure helpers: loyaltyTier, pointsEarned, pointsValue, maxRedeemablePoints, expiringPoints, spendablePoints, evaluatePromo, normalizePromoCode, isPromoCodeFormat, promoLive.

Async callbacks return Promise<void | { error?: string }>.

ExamplesCopy Anchor Link

ArabicCopy Anchor Link

<NasaqProvider locale="ar"><LoyaltyCard name="سارة" balance={1840} /></NasaqProvider>

AccessibilityCopy Anchor Link

• The tier progress bar has a label; expiry notices use role="status".
• Ledger direction is a sign and a label, not colour alone.

RTL & i18nCopy Anchor Link

Built-in English and Arabic, and a labels prop to override. Codes, member numbers and signed points stay left to right.

Styling & tokensCopy Anchor Link

Card, surface, border and status tokens only. Target the data-slot values above and extend with className. No raw hex.

Do / Don'tCopy Anchor Link

• Do check promo rules again on your server.
• Do send points as whole numbers.
• Don't compute discounts in floats.

RelatedCopy Anchor Link

• gamification, qr-code, data-table

LabCopy Anchor Link

Storybook: Components / CRM / Loyalty and Promo.