Performance Group picker

PerformanceGroupPicker is the complete buyer seating step for a run of two to eight performances that share one published seating chart. It is available in @seatlayer/js 0.64.0 and later. Try the buyer flow first in the multi-performance seat selection demo.

Use this page for picker configuration and behavior. Read the end-to-end Performance Group integration for provisioning, checkout, booking, and fulfilment, or the Performance Groups API for exact trusted operations.

It is not a season-ticket, subscription, pass, or renewable season membership. The organizer chooses whether every date is required or partial seats may be sold only on their available dates. Your application still owns the offer, checkout, payment, commercial order, ticket delivery, and support.

Use the separate Fixed Renewable Season integration when the offer needs an immutable 2–20-Event Plan, incumbent Seat Rights, and renewal offers rather than one Performance Group purchase.

Choose the inclusion policy

The flexible flow loads one chart and one per-performance availability projection. Selecting or clearing a partial seat re-collapses those cached availability planes locally; it does not load a chart for each date.

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.

For a flexible_dates group, a two-tone partial seat can be opened to see its available and unavailable dates. Select for 2 available dates updates the persistent date summary, selects the seat, and submits one atomic hold for only those two performances. Clearing the selection restores the full date view.

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";
  performanceKeys: string[];
  seatLabels: string[];
  allocations?: Array<{
    eventKey: string;
    seatLabels: string[];
  }>;
}

performanceKeys is the chronological set actually held. It contains every member for a fixed group and the selected available dates for a flexible group. Treat it, 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.