SeatingChart reference | SeatLayer Developer Docs

Headless map options, callbacks, methods, live holds, GA, groups, floors, and error behavior.

SeatingChart mounts the live map canvas without SeatLayer’s cart/tray chrome. Your application owns totals, tier/GA controls, the checkout button, countdown, and buyer messages.

browser/chart.jsjs

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

const chart = new SeatingChart({
  container: "#chart",
  event: "ev_9f3a",
  onSelectionChange: renderCart,
  onError: reportPickerError,
});

await chart.render();

Constructor options and callbacks

Option	Type	Notes
`container`	`string \| HTMLElement`	Required, definite dimensions
`event`	`string`	Required event key
`apiBase`	`string`	Defaults to production API
`publicKey`	`string`	Reserved and currently not sent
`maxSelection`	`number`	Default `10`
`locale` / `messages`	`string` / overrides	Localized on-map copy
`currency`	`string`	Display fallback
`colorblindSafe`	`boolean`	Accessible palette and hollow booked state
`initialView`	`RendererViewMode`	Use `flat`; perspective modes deprecated
`seatTooltip`	`boolean`	Built-in hover tooltip, default `true`
`onSeatHover`	`(details \| null) => void`	Build a custom hover surface
`onSelectionChange`	`(seats) => void`	Manual, group, or tier change
`onHint`	`(message \| null) => void`	Non-blocking localized advice
`onHold`	`(hold) => void`	Any successful hold
`onHoldRestored`	`(hold) => void`	`resumeHold()` succeeds
`onHoldExpired`	`() => void`	Server expiry reached
`onGAClick`	`(area) => void`	Host should request quantity and call `holdGA()`
`onDeckTap`	`(floorId) => void`	Synchronize custom floor controls
`onError`	`(error) => void`	Public async methods report failures here

Selection and hold methods

Method	Signature/behavior
`getMode()`	`"live" \| "test" \| null`; null before render
`getSelection()`	Current `SelectedSeat[]`
`hold({ ttlMs? })`	Hold current selection; `null` on failure/conflict
`resumeHold(holdId)`	Restore without extending
`extendHold(ttlMs?)`	Extend active hold within server limits
`getCurrentHold()`	Current `HoldResult \| null`
`getGAAreas()`	Live GA capacity records
`holdGA(areaId, qty, { tierId?, ttlMs? })`	Quantity hold
`bestAvailable(qty, categoryKey?, options?)`	Adjacent group hold
`setSeatTier(seatId, tierId)`	Change selected tier; null resets
`release()`	Release the full hold
`releaseLabels(labels)`	Partially release listed labels

hold(), resumeHold(), holdGA(), and bestAvailable() catch public transport errors, call onError, and resolve null. Do not wait for an exception to render buyer recovery.

View and lifecycle methods

Method	Behavior
`render()`	Fetch, mount, seed live state; idempotent after success
`getFloors()` / `setFloor(id)`	Custom multi-floor navigation
`setColorblindSafe(on)`	Runtime accessible palette
`setViewMode(mode)` / `getViewMode()`	2D renderer compatibility
`zoomIn()` / `zoomOut()` / `zoomToFit()`	Host map controls
`destroy()`	Socket/listener/timer/DOM cleanup

The full 3D buyer experience belongs to SeatPicker; SeatingChart.initialView does not enable that venue view.

Core result types

interface HoldResult {
  holdId: string;
  expiresAt: number;
  seats?: SelectedSeat[];
  items?: HoldLineItem[];
}

interface BestAvailableResult extends HoldResult {
  labels: string[];
  zoneId?: string;
}

interface GAAreaAvailability {
  id: string;
  label: string;
  capacity: number;
  available: number;
  categoryKey: string;
  price: number;
  currency: string;
  displayLabel?: string;
  displayType?: string;
  tiers?: Array<{ id: string; name: string; price: number }>;
}

HoldLineItem.unitPrice, currency, tier, and quantity come from SeatLayer, but your server still re-inspects the hold before payment.

Build the custom cart safely

Render selection

Derive immediate UI from onSelectionChange; keep stable ids separate from buyer labels.

Create the hold

Call the appropriate hold method when the buyer continues. Disable duplicate submissions while it runs.

Start a visible timer

Count down from server expiresAt, not a locally invented duration.

Hand off only holdId

Your backend inspects authoritative items, runs payment/order logic, and books.

Recover intentionally

Clear stale selection/cart on expiry, show adjacency-specific errors, and reuse bookingRef for uncertain server retries.

Integration checklist

The host container has a stable width and height.
Every callback updates host state idempotently.
null async results have explicit buyer copy.
GA, tier, best-available, and partial release paths are tested if used.
Hold time is based on expiresAt.
Server checkout ignores browser prices.
destroy() runs during unmount/navigation.
Keyboard, touch, zoom, and colorblind-safe behavior pass.

Continue with SeatPicker, groups and GA, or best available.