Performance Group picker

PerformanceGroupPicker is the complete buyer seating step for a fixed run of two to eight performances that share one published seating chart. It is available in @seatlayer/js 0.64.0 and later.

It is not a season-ticket, subscription, pass, or buyer-selectable date bundle. The buyer purchases every performance shown by the picker. Your application still owns the offer, checkout, payment, commercial order, ticket delivery, and support.

Choose the selection mode

Both modes create one all-or-nothing group hold. The browser never makes a separate hold for each Event.

Before you render

Your trusted backend must create the Performance Group, activate it, and mint a short-lived bsg_… buyer-access session for the exact browser origin. See the Performance Groups API for that server-side setup.

Return only { token, expiresAt } to the browser. Do not put the token in a URL, persistent browser storage, analytics, or logs.

Same seat for every performance

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

const picker = new PerformanceGroupPicker({
  container: "#seat-picker",
  performanceGroup: "pg_opening_weekend",
  buyerAccessTokenProvider: async () => {
    const response = await fetch("/api/seatlayer/group-access", {
      method: "POST",
      credentials: "same-origin",
      cache: "no-store",
    });
    if (!response.ok) throw new Error("Unable to open seat selection");
    return response.json(); // { token: "bsg_…", expiresAt }
  },
  onCheckout: (handoff) => {
    // This starts your checkout. It does not book inventory yet.
    startCheckout({
      performanceGroup: handoff.performanceGroup.key,
      holdId: handoff.holdId,
      operationId: handoff.operationId,
    });
  },
  onError: (error) => reportSeatSelectionError(error),
});

await picker.render();

The picker presents the complete date list, one shared chart, an accessible selection summary, and one Hold seats for all performances action. When the hold completes, the primary action becomes Continue to checkout.

Different seats on each date

Use per_performance only when your offer permits different seats. The picker reuses one chart and shows dated tabs; it requires the configured party size on every performance before the hold action becomes available.

const picker = new PerformanceGroupPicker({
  container: "#seat-picker",
  performanceGroup: "pg_three-night-run",
  selectionMode: "per_performance",
  numberOfPlacesToSelect: 2,
  buyerAccessTokenProvider: getGroupBuyerAccess,
  onCheckout: (handoff) => {
    beginCheckout({
      holdId: handoff.holdId,
      operationId: handoff.operationId,
    });
  },
});

await picker.render();

For example, a two-person purchase must have two seats selected on each tab. The buyer cannot hold two seats on Friday and one on Saturday.

Constructor options

event, custom transport, Best Available, runtime pricing overrides, and hosted checkout are intentionally unavailable. Passing a group through SeatPicker or calling one Event’s hold route would make the purchase unsafe.

Checkout handoff

onHold and onCheckout receive this group-specific object:

interface PerformanceGroupCheckoutHandoff {
  operationId: string;
  holdId: string;
  expiresAt: number;
  performanceGroup: PerformanceGroupDescriptor;
  selectionMode: "same_seat" | "per_performance";
  seatLabels: string[];
  allocations?: Array<{
    eventKey: string;
    seatLabels: string[];
  }>;
}

Treat seatLabels and allocations as buyer display data only. Send the opaque holdId and operationId to your backend; it must inspect the group hold before calculating a charge or booking inventory.

The handoff deliberately never includes child Event hold IDs, authoritative prices, payment data, or ticket information.

Hold, recovery, and release

Call picker.destroy() when the host route unmounts. The picker clears its timers, chart instance, and polling connection. It never books inventory; booking belongs to your server.

Continue with the end-to-end integration guide and group hold inspection and booking.