React & Next.js

@seatbuilder/sdk/react ships a <SeatBuilderChart> component that wraps SeatBuilder.render() for you — no manual useEffect/container-ref plumbing required.

1. Install

npm install @seatbuilder/sdk

Requires React ≥ 18. konva and zod are installed automatically as dependencies of @seatbuilder/sdk.

2. Basic component

'use client';
import { useRef } from 'react';
import { SeatBuilderChart } from '@seatbuilder/sdk/react';
import type { ChartInstance } from '@seatbuilder/sdk';

export function SeatMap({ eventKey }: { eventKey: string }) {
  const chart = useRef<ChartInstance | null>(null);
  return (
    <SeatBuilderChart
      ref={chart}
      publicKey="pk_live_..."
      eventKey={eventKey}
      apiUrl="https://seatbuilder.org"
      onObjectSelected={(e) => console.log('held', e.objectLabel)}
      style={{ height: 600 }}
    />
  );
}

• Safe to render from a Server Component tree; the chart mounts on the client.
• Changing an on* callback, onReady, className or style never re-mounts the chart; changing a config prop (anything else, e.g. eventKey) destroys it and renders a new one.
• Give the component a height (style or className) — a 0-height container renders nothing.

3. Next.js App Router

SeatBuilderChart only touches the DOM inside a useEffect, so it server-renders safely as long as the 'use client' boundary is on the child component, not the page. You do not need dynamic(() => import(...), { ssr: false }).

// app/events/[eventKey]/page.tsx
import { SeatMap } from './seat-map';

export default async function EventPage({
  params,
}: {
  params: Promise<{ eventKey: string }>;
}) {
  const { eventKey } = await params;
  return (
    <main>
      <h1>Pick your seats</h1>
      <SeatMap eventKey={eventKey} />
    </main>
  );
}

// app/events/[eventKey]/seat-map.tsx
'use client';
import { useRef } from 'react';
import { SeatBuilderChart } from '@seatbuilder/sdk/react';
import type { ChartInstance } from '@seatbuilder/sdk';

export function SeatMap({ eventKey }: { eventKey: string }) {
  const chart = useRef<ChartInstance | null>(null);
  return (
    <SeatBuilderChart
      ref={chart}
      publicKey="pk_live_..."
      eventKey={eventKey}
      apiUrl="https://seatbuilder.org"
      style={{ height: 600 }}
    />
  );
}

4. Props reference

SeatBuilderChartProps is SdkConfig minus container (the component manages its own container <div>), plus onReady, className, and style.

5. Re-mount rules and the ref API

• Callback props (onObjectSelected, onSelectionValid, etc.) are read through a ref — changing them never re-mounts the chart.
• onReady, className, style never re-mount the chart either.
• Config props (everything else: eventKey, apiUrl, maxSelectedObjects, ...) are compared structurally; changing a config prop destroys the current chart and renders a new one.

Attach a ref to read the imperative ChartInstance. ref.current is null until the chart mounts (after the first client render/effect), so read it in event handlers or use onReady rather than during render:

Do not call destroy() yourself — unmounting <SeatBuilderChart> already calls it for you in its cleanup effect.

6. Checkout hand-off

Read the hold token off the ref when the buyer submits checkout, and POST it to your backend to promote the holds to a booking:

async function handleCheckout() {
  const holdToken = chart.current?.holdToken;
  if (!holdToken) return;
  await fetch('/api/checkout', {
    method: 'POST',
    body: JSON.stringify({ holdToken }),
  });
}

See Hold seats and confirm at checkout for the full server-side extend/book flow.