# Loyalty and Promo > A loyalty card with tiers and expiring points, a points ledger, promo-code entry and management, and a customer visit history. Source: https://docs.nasaqui.com/components/loyalty-promo ## Install ```bash 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 use - Restaurants, salons, clinics and shops with points, tiers and discount codes. ## When not to use - Game-style XP and badges: use `gamification`. ## Import ```tsx import { LoyaltyCard, PromoCodeField, PromoCodeManager, PointsHistory, VisitHistory } from "@fadymondy/nasaq/web"; ``` ## Quick start ```tsx api.redeem(r.id)} /> api.applyPromo(code)} onRemove={clear} /> ``` ## Anatomy ``` 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 ``` ## API 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`. ## Examples ### Arabic ```tsx ``` ## Accessibility | Key | Action | | --- | --- | | Tab | Move through the code field, buttons and rows. | | Enter | Apply the code or submit the dialog. | | Shift+F10 or Menu | Open a row's actions. | - The tier progress bar has a label; expiry notices use `role="status"`. - Ledger direction is a sign and a label, not colour alone. ## RTL & i18n Built-in English and Arabic, and a `labels` prop to override. Codes, member numbers and signed points stay left to right. ## Styling & tokens Card, surface, border and status tokens only. Target the `data-slot` values above and extend with `className`. No raw hex. ## Do / Don't - Do check promo rules again on your server. - Do send points as whole numbers. - Don't compute discounts in floats. ## Related - `gamification`, `qr-code`, `data-table` ## Lab Storybook: Components / CRM / Loyalty and Promo. ## Code ### React ```tsx api.redeem(r.id)} /> api.applyPromo(code)} onRemove={clear} /> ``` ### shadcn ```tsx api.redeem(r.id)} /> api.applyPromo(code)} onRemove={clear} /> ``` ### Vue ```vue ``` ### Blade ```blade @php $tiers = [ ['id' => 'bronze', 'name' => 'Bronze', 'minPoints' => 0], ['id' => 'silver', 'name' => 'Silver', 'minPoints' => 1000], ['id' => 'gold', 'name' => 'Gold', 'minPoints' => 3000], ]; $rewards = [ ['id' => 'r1', 'title' => 'Free coffee', 'cost' => 500], ['id' => 'r2', 'title' => '10 off your next order', 'cost' => 1500], ]; $entries = [ ['id' => 'e1', 'date' => '2026-09-20T10:00:00', 'kind' => 'earn', 'points' => 120, 'note' => 'Order #1042', 'balanceAfter' => 1840], ['id' => 'e2', 'date' => '2026-09-10T10:00:00', 'kind' => 'redeem', 'points' => -500, 'note' => 'Free coffee', 'balanceAfter' => 1720], ]; $visits = [ ['id' => 'v1', 'date' => '2026-09-20T10:00:00', 'place' => 'Downtown', 'spend' => 4500, 'points' => 45, 'status' => 'completed'], ['id' => 'v2', 'date' => '2026-09-12T15:30:00', 'place' => 'Mall', 'spend' => 0, 'points' => 0, 'status' => 'no-show'], ]; $promos = [ ['id' => 'p1', 'code' => 'WELCOME10', 'type' => 'percent', 'value' => 1000, 'used' => 3, 'active' => true], ['id' => 'p2', 'code' => 'FLAT5', 'type' => 'fixed', 'value' => 500, 'used' => 0, 'active' => false], ]; $rules = [['code' => 'WELCOME10', 'type' => 'percent', 'value' => 1000]]; @endphp
``` ### HTML + Alpine ```html

Sara

Silver

Points balance 1,840 points

1,160 points to Gold

NSQ-4821

Rewards

Free coffee Common

500 points

10 off your next order Common

1,500 points

Points activity

  • Order #1042 Earned
    +120 Balance 1,840
  • Free coffee Redeemed
    −500 Balance 1,720

Visits

Visits
1
Total spend
$45.00
Average visit
$45.00
Last visit
Actions

Promo codes

No promo codes

Create a code to run an offer.

Code
Discount
Valid
Used
Status
Actions

سارة

رصيد النقاط 1,840 نقطة

```