## Installation ```bash npx shadcn@latest add https://ui.cravejs.com/registry/promo-code-input.json ``` ## Usage ```tsx import { PromoCodeInput } from "@/components/restaurant/checkout/promo-code-input" export function PromoCodeExample() { const [appliedCode, setAppliedCode] = useState(null) return ( { const validated = await validatePromoCode(code) setAppliedCode(validated) }} onRemove={() => setAppliedCode(null)} appliedCode={appliedCode} /> ) } ``` ## Variants The Promo Code Input component supports different display styles: ### Default The default variant with input field and apply button. ```tsx ``` ### Inline An inline variant for compact layouts. ```tsx ``` ### Auto-Apply Auto-validates and applies codes as user types. ```tsx ``` ## Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `onSubmit` | `(code: string) => Promise` | - | **Required.** Callback to validate and apply code | | `onRemove` | `() => void` | - | **Required.** Callback when removing applied code | | `appliedCode` | `PromoCode \| null` | - | Currently applied promo code | | `isValidating` | `boolean` | `false` | Whether validation is in progress | | `placeholder` | `string` | `"Enter promo code"` | Input placeholder text | | `maxLength` | `number` | `50` | Maximum code length | | `autoApply` | `boolean` | `false` | Auto-apply codes on input | | `showSuggestions` | `boolean` | `false` | Show available promo suggestions | | `availableCodes` | `string[]` | `[]` | List of available codes to suggest | | `error` | `string` | - | Error message to display | | `variant` | `"default" \| "inline" \| "auto-apply"` | `"default"` | Visual variant | | `debounceMs` | `number` | `300` | Debounce delay for auto-apply | | `disabled` | `boolean` | `false` | Disable input | | `className` | `string` | - | Additional CSS classes | ## Examples ### With Applied Discount ```tsx const appliedPromo = { id: "promo_123", code: "SAVE20", type: "percentage", value: 20, description: "20% off your order", discount: 8.40 } ``` ### With Validation States ```tsx { if (code === "EXPIRED") { throw new Error("This promo code has expired") } if (code === "MINIMUM") { throw new Error("Minimum order of $25 required") } // Apply valid code await applyPromoCode(code) }} onRemove={handleRemove} /> ``` ### With Suggestions ```tsx { // Auto-fill selected code setPromoInput(code) }} /> ``` ### First-Time Customer Promo ```tsx const firstTimePromo = { code: "FIRSTORDER", type: "percentage", value: 15, description: "15% off your first order", isFirstTimeOnly: true } { if (!isFirstTimeCustomer && code === "FIRSTORDER") { throw new Error("This code is for first-time customers only") } await applyPromoCode(code) }} appliedCode={appliedPromo} onRemove={handleRemove} /> ``` ### With Order Minimum ```tsx { const promo = await validatePromoCode(code) if (promo.minOrderValue && orderTotal < promo.minOrderValue) { throw new Error(`Minimum order of $${promo.minOrderValue} required`) } setAppliedPromo(promo) }} onRemove={handleRemove} orderTotal={orderTotal} /> ``` ## Features - **Real-time Validation**: Instant code verification - **Auto-Apply**: Optional automatic code application - **Discount Preview**: Show savings before applying - **Error Handling**: Clear validation messages - **Suggestions**: Display available promo codes - **Applied State**: Visual confirmation of active promos - **Removal Option**: Easy code removal - **Loading States**: Show validation progress ## Promo Code Types ```tsx type PromoType = | "percentage" // Percentage discount | "fixed" // Fixed amount off | "free-shipping" // Free delivery | "bogo" // Buy one get one | "item-discount" // Specific item discount interface PromoCode { id: string code: string type: PromoType value: number description: string discount: number expiresAt?: Date minOrderValue?: number maxDiscount?: number usageCount: number maxUsage?: number isFirstTimeOnly?: boolean applicableItems?: string[] } ``` ## Validation Logic ### Server-Side Validation ```tsx async function validatePromoCode(code: string, order: Order) { // Check if code exists const promo = await getPromoByCode(code) if (!promo) { throw new Error("Invalid promo code") } // Check expiration if (promo.expiresAt && new Date() > promo.expiresAt) { throw new Error("This promo code has expired") } // Check usage limits if (promo.maxUsage && promo.usageCount >= promo.maxUsage) { throw new Error("This promo code is no longer available") } // Check minimum order if (promo.minOrderValue && order.subtotal < promo.minOrderValue) { throw new Error(`Minimum order of $${promo.minOrderValue} required`) } // Calculate discount const discount = calculateDiscount(promo, order) return { ...promo, discount } } ``` ### Discount Calculation ```tsx function calculateDiscount(promo: PromoCode, order: Order) { switch (promo.type) { case "percentage": const percentOff = order.subtotal * (promo.value / 100) return promo.maxDiscount ? Math.min(percentOff, promo.maxDiscount) : percentOff case "fixed": return Math.min(promo.value, order.subtotal) case "free-shipping": return order.deliveryFee case "bogo": // Calculate based on eligible items return calculateBogoDiscount(promo, order.items) default: return 0 } } ``` ## Accessibility The Promo Code Input follows accessibility best practices: - Proper label association with input - Clear error announcements - Keyboard navigation support - Loading state announcements - Success/error feedback for screen readers ## Styling The component uses Tailwind CSS classes and can be customized through: - CSS custom properties for brand colors - The `className` prop for wrapper styling - Success/error state colors - Custom loading animations ## Related Components - [Order Summary](/docs/components/order/order-summary) - Display promo discounts - [Checkout Form](/docs/components/checkout/checkout-form) - Complete checkout flow - [Payment Method Selector](/docs/components/checkout/payment-method-selector) - Payment options - [Cart](/docs/components/cart/cart) - Shopping cart with totals