SeatPicker reference

SeatPicker is the complete buyer experience: live map, confirmation, tier/GA controls, selection tray, hold countdown, best available, 2D/3D, view from seat, mobile bottom sheet, sold-out/closed states, and checkout handoff. For how it sits beside the server and mobile packages, see the seat map API overview.

import { SeatPicker } from "@seatlayer/js";

const picker = new SeatPicker({
  container: "#picker",
  event: "ev_9f3a",
  publicKey: "pk_test_…",
  onCheckout: (_hold, _seats, handoff) => {
    startCheckout({ holdId: handoff.holdId });
  },
});

await picker.render();

For a public Platform event, publicKey creates one direct, origin-bound, Public-sale-only bootstrap. The response carries chart geometry and compact inventory status together; its short-lived bearer stays in memory. Login, presale, partner, and channel inventory instead use buyerAccessTokenProvider or buyerAccessToken from your authenticated backend. Either explicit buyer credential takes precedence over publicKey.

Choose the surface

For a buyer purchasing a fixed multi-performance run, use PerformanceGroupPicker instead. Do not pass an Event array to SeatPicker or create several event holds in the browser.

Constructor options

Callbacks

Use the third onCheckout argument for new integrations:

interface CheckoutHandoff {
  holdId: string;
  expiresAt: number;
  currency: string;
  lineItems: CheckoutLineItem[];
  total: number;
}

interface CheckoutLineItem {
  label: string;
  displayLabel?: string;
  displayType?: string;
  objectId: string;
  objectType: "seat" | "booth" | "ga" | "table";
  categoryKey: string;
  tierId: string | null;
  unitPrice: number;
  currency: string;
  quantity: number;
}

The browser handoff is excellent display context, but payment still uses a fresh server hold inspection.

Scoped channel prices need no browser configuration

When buyerAccessTokenProvider returns a session scoped to a priced sales channel, SeatPicker receives only that session’s compact price projection and uses it for seats, tables, booths, GA quantities, ticket tiers, totals, and the checkout handoff. You do not pass a channel id or duplicate the channel price book in browser options.

The hold endpoint resolves the same channel price independently and freezes it with channelPricingVersion. Continue to treat the inspected hold as the checkout authority. setPricing() remains a host-side presentation override; it cannot replace or weaken the server’s channel price.

Public methods

For a fixed-size purchase flow, set numberOfPlacesToSelect. For guided buyer selection, add one or more local rules:

selectionValidators: [
  { type: "minimumSelectedPlaces", minimum: 2 },
  { type: "consecutiveSeats" },
  { type: "noOrphanSeats" },
]

consecutiveSeats requires one uninterrupted run in the same row and ticket category. noOrphanSeats prevents a choice from newly stranding one free seat between unavailable neighbours. The built-in CTA stays disabled and shows localized guidance until every rule is satisfied. onSelectionValidityChange exposes { isValid, count, required, remaining, seats, violations } for custom host chrome. The full picker counts seated places, grouped-table guest quantities, held lines, and pending GA quantities together.

Modal mode

const picker = await SeatPicker.open({
  event: "ev_9f3a",
  onCheckout: (_hold, _seats, handoff) => {
    startCheckout({ holdId: handoff.holdId });
  },
  onClose: () => restoreHostUI(),
});

picker.close();

The modal traps focus, closes through Escape/scrim/close button, restores scroll and prior focus, and fires onClose.

Holds and restore

The picker persists the current hold id in sessionStorage by default. On a return visit it verifies that hold against the same event before showing it as owned.

Set restoreHold: false when your router/cart owns persistence, then supply initialHoldId or call resumeHold(). Clear host cart state when onHoldChange(null, …) fires.

The built-in countdown offers an extension in the final minute and resets on confirmed extension. Server limits and renewal caps remain authoritative.

Buyer 3D and analytics

enable3D controls whether the Map/3D affordance is offered. The 3D module is lazy-loaded only after use and falls back to the complete 2D experience when WebGL2 is unavailable.

Use setBuyerView("venue3d", { flyToSeatId }) for a guided tour and onAnalytics to forward Preview journey events to your own system.

With the built-in transport and apiBase: "https://api.seatlayer.io", the picker separately sends one anonymous operational load timing after a successful render. Custom transports, other API origins, and localhost stay silent unless operationalTelemetry: true; false always opts out. The request goes only to the configured apiBase, omits credentials and referrer, and never includes an access token. It is not routed through onAnalytics.

See 3D buyer view and buyer analytics.

Responsive behavior

Layout responds to the picker container, not only the viewport:

• wide containers show a side panel and docked details;
• narrow containers use a bottom sheet and touch-first map controls; and
• fullscreen uses the native API or a platform fallback.

Give the container a definite height. Test the actual embed width, mobile browser chrome, keyboard, reduced motion, and colorblind-safe mode.

Lifecycle checklist

• Construct once per mounted host view.
• Await render() and expose failures through onError.
• Send only holdId to the booking server boundary.
• Clear host state when the hold disappears.
• Use stable order ids for booking retries.
• Call destroy() during application unmount.
• Test inline/modal, narrow/wide, 2D/no-WebGL, expiry, and conflict paths.

Continue with holds and checkout, customization, or the SeatingChart reference.