Render a seat map

The smallest useful Seats integration is two steps: drop a <div> container into your page and call SeatBuilder.render with your public key, the event key, and the container id.

1. Add a container

Reserve a sized region of the page for the chart. The SDK fills the container — give it explicit width and height (or constrain it with flex / grid) so Konva can compute the canvas viewport.

<div id="seats-container" style="width: 800px; height: 600px;"></div>

2. Call render

import SeatBuilder from '@seatbuilder/sdk';

const chart = SeatBuilder.render({
  publicKey: 'pk_live_xxx',
  eventKey: 'evt_xxx',
  container: 'seats-container',
  apiUrl: 'https://seatbuilder.org',
  maxSelectedObjects: 4,
  onObjectSelected: ({ objectLabel, holdToken }) => {
    console.log('Selected', objectLabel, 'with hold', holdToken);
  },
});

Every option except publicKey, eventKey, and container has a sensible default. apiUrl defaults to the same origin as the page in a typical SSR / proxy setup, but most integrations set it explicitly to the SeatBuilder API host (https://seatbuilder.org).

What you get

The rendered chart is interactive out of the box:

• Free seats highlight on hover.
• Click on a free seat fires onObjectSelected with the seat label and a short-lived holdToken. Stash the token — you'll need it to promote the hold to a booking server-side.
• Held / booked seats are not selectable and visually dim.
• maxSelectedObjects caps the buyer's selection; the SDK rejects clicks beyond the cap and fires onSelectionInvalid (no built-in toast — render your own feedback from that callback). Pass a bare number for a single total cap across all categories, or { total?, perCategory? } to cap the total and individual categories — see Category-aware caps below.

The full e-commerce variant — adding-to-cart, confirming at checkout, recovering from expired holds — is documented in Hold seats and confirm at checkout.

Callbacks reference

onObjectSelected fires once per seat. To track the whole selection, listen for onSelectionValid — it fires on every change and hands you the complete array of currently-held labels.

const chart = SeatBuilder.render({
  publicKey: 'pk_live_xxx',
  eventKey: 'evt_xxx',
  container: 'seats-container',
  apiUrl: 'https://seatbuilder.org',
  maxSelectedObjects: 4,
  onSelectionValid: ({ selectedObjectLabels }) => {
    // The complete current selection, e.g. ['A-12', 'A-13'].
    console.log('Selected so far:', selectedObjectLabels);
  },
  onSelectionInvalid: ({ reason, categoryKey }) => {
    if (reason === 'hold_expired') promptReselect();
    if (reason === 'max_selected' && categoryKey) {
      // A per-category cap fired — tell the buyer which one.
      console.log('Reached the limit for category', categoryKey);
    }
  },
});

Category-aware caps

maxSelectedObjects accepts either a bare number (a single total cap) or an object with total and/or perCategory. The perCategory keys match the category.key values from your chart. When both total and perCategory are set, both are enforced. A general-admission area counts its quantity as N toward both caps (a hold of 50 counts as 50).

const chart = SeatBuilder.render({
  publicKey: 'pk_live_xxx',
  eventKey: 'evt_xxx',
  container: 'seats-container',
  apiUrl: 'https://seatbuilder.org',
  // At most 6 seats total, with no more than 2 in the `vip` category.
  maxSelectedObjects: { total: 6, perCategory: { vip: 2 } },
  onSelectionInvalid: ({ reason, categoryKey }) => {
    if (reason === 'max_selected') {
      console.log(
        categoryKey
          ? `Limit reached for category ${categoryKey}`
          : 'Total seat limit reached',
      );
    }
  },
});

When a per-category cap is the one that blocks the click, onSelectionInvalid carries categoryKey; when the total cap blocks it, categoryKey is omitted.

Configuration reference

Instance API

SeatBuilder.render() returns a ChartInstance for imperative control: