Skip to Content

Gift Voucher

Present hospitality gift vouchers and packages with the existing ProductGrid cards and caller-provided purchase destinations.

GiftVoucherSection adapts ProductGridSection for vouchers, values, and stay or dining arrangements. Each option is a presentation card; checkout, voucher issuance, and payment remain application responsibilities.

Beta API maturity: Beta.

Installation

import { GiftVoucherSection, type GiftVoucherOption } from "@puzzle-ui/pieces";

Variant previews

Grid, featured, and category variants reuse the existing ProductGrid layout. Purchase links are supplied by the application; cards without a destination remain informational.

grid - Browse voucher values and arrangements.

390 × 844

featured - Emphasize one supplied gift option.

390 × 844

category - Group vouchers by their supplied category.

390 × 844

API

PropTypeRequiredDefault
vouchersreadonly GiftVoucherOption[]Yes—
variantProductGridVariantNo"grid"
localestringNo"en-US"
purchaseLabelReactNodeNo"View gift voucher"
emptyStateReactNodeNo—
Shared section propsMarketingSectionBasePropsNo—

GiftVoucherOption

FieldTypeRequiredDescription
idstringYesStable option identifier.
namestringYesVoucher or package name.
priceCommerceMoneyYesCaller-supplied amount and currency.
descriptionReactNodeNoDescription of the value or arrangement.
imageCommerceImageNoOptional image and meaningful alternative text.
compareAtPriceCommerceMoneyNoOptional caller-supplied comparison price.
labelsreadonly ProductGridLabel[]NoOptional labels provided by the application.
ratingCommerceRatingNoOptional supplied rating; no rating is calculated.
arrangementReactNodeNoOptional package or experience label.
categorystringNoSupplied category for the ProductGrid category layout.
collectionstringNoSupplied grouping for the ProductGrid collection layout.
purchaseHrefstringNoDestination owned by the application or its purchase provider.
purchaseActionReactNodeNoAlternative caller-owned action.
purchaseLabelReactNodeNoPer-option override for the default link label.
featuredbooleanNoMarks an option for the featured variant.

Each denomination or arrangement should be a separate GiftVoucherOption. Use an externally owned destination or action when purchase behavior is available; Pieces does not provide checkout.

Usage

const vouchers: GiftVoucherOption[] = [
  {
    id: "weekend",
    name: "A weekend for two",
    description: "Two nights with breakfast.",
    price: { amount: 260, currency: "EUR" },
    arrangement: "Two nights with breakfast",
    purchaseHref: "https://example.test/vouchers/weekend",
  },
];

<GiftVoucherSection title="Give a slower weekend" vouchers={vouchers} locale="en-GB" />;

Responsive behavior

All variants use ProductGrid's fluid layouts and content-driven cards. Images are optional, names and descriptions wrap, and long amounts use the existing commerce price display.

Accessibility

The component uses ProductGrid's semantic cards and named links. Provide descriptive purchase labels and meaningful image alternatives. A custom purchaseAction should also have an accessible name.

Theme support

Product cards and actions inherit ProductGrid and Puzzle UI semantic tokens, including scoped themes.

Customization

Use shared section props, className, the purchaseAction slot, and optional images. Labels, price values, destinations, and checkout behavior are supplied by the application.

Composition

Pair a voucher section with Service Options or an existing menu, accommodation, or CTA section. See the Boutique B&B and Restaurant Experience references.

TypeScript example

GiftVoucherOption and GiftVoucherSection are package-root exports. CommerceMoney and CommerceImage are shared existing Pieces types.

Framework compatibility

The section is router-independent and server-renderable. Purchase navigation, checkout, voucher administration, and payment are outside Pieces. See Next.js and TanStack Start integration.