Skip to content

React quickstart (Vite)

A React website, built with Vite, where customers pick a service and a free time and book an appointment, all in the browser with the Booking SDK.

Tutorial5 min read

In about 15 minutes you build a small React website where customers of Northwilds Oslo choose a service, pick a free time in their own time zone and book it. Everything runs in the visitor's browser, so each visitor has their own rate limits.

Tested with: Vite 8.3, React 19.3, TypeScript 7.0, @bifrost-orbit-booking/sdk 0.1.0, Node.js 24, against a local Booking Orbit.

Note

The SDK is not on npm yet. Until it is, step 2 fails; the code shows the calls to make with the public booking API.

Before you start

You need:

  • A Booking Orbit location with at least one service and someone who takes it, such as northwilds-oslo. Its short name is the last part of its booking page address.
  • Your website allowed: under the location's Settings › Your website, add http://localhost:5173 to Other websites while you build, and your real website's address before you go live. See Allowed websites.
  • Node.js 20 or later.

1Create the project

Shell
npm create vite@latest northwilds-booking -- --template react-ts --no-interactivecd northwilds-bookingrm src/App.cssrm -r src/assets

2Install the SDK

Shell
npm install @bifrost-orbit-booking/sdk

3Add the settings

.env.localShell
VITE_BOOKING_URL=https://app.bifrostorbit.com/bookingVITE_BOOKING_LOCATION=northwilds-oslo

Neither is a secret: the booking API needs no key. Tell TypeScript about them:

src/vite-env.d.tsTypeScript
/// <reference types="vite/client" />interface ImportMetaEnv {  readonly VITE_BOOKING_URL: string;  readonly VITE_BOOKING_LOCATION: string;}

4Create the client

One client books one location. The helpers show times in the visitor's own time zone.

src/booking.tsTypeScript
import { createBookingClient } from "@bifrost-orbit-booking/sdk";export const booking = createBookingClient({  baseUrl: import.meta.env.VITE_BOOKING_URL,  location: import.meta.env.VITE_BOOKING_LOCATION,  locale: "en",});export const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;export const timeOf = (iso: string) => new Intl.DateTimeFormat("en-GB", { timeZone, hour: "2-digit", minute: "2-digit" }).format(new Date(iso));export const dayOf = (date: string) => new Intl.DateTimeFormat("en-GB", { timeZone: "UTC", weekday: "long", day: "numeric", month: "long" }).format(new Date(`${date}T12:00:00Z`));export const dateOf = (iso: string) => new Intl.DateTimeFormat("en-GB", { timeZone, weekday: "long", day: "numeric", month: "long" }).format(new Date(iso));

dayOf takes a day such as 2026-11-12 from the free times, which are already grouped in the visitor's time zone. dateOf and timeOf take a time.

5Build the booking screen

Replace src/App.tsx:

src/App.tsxTypeScript
import { useEffect, useState, type FormEvent } from "react";import { BookingError, isTimeTaken, type BookingAppointment, type BookingHold, type BookingService, type BookingSlots } from "@bifrost-orbit-booking/sdk";import { booking, dateOf, dayOf, timeOf, timeZone } from "./booking";export default function App() {  const [services, setServices] = useState<BookingService[]>([]);  const [service, setService] = useState<BookingService | null>(null);  const [slots, setSlots] = useState<BookingSlots | null>(null);  const [hold, setHold] = useState<BookingHold | null>(null);  const [startsAt, setStartsAt] = useState<string | null>(null);  const [booked, setBooked] = useState<BookingAppointment | null>(null);  const [error, setError] = useState<string | null>(null);  useEffect(() => {    booking.services().then(setServices, (failure: Error) => setError(failure.message));  }, []);  async function choose(next: BookingService) {    setService(next);    setSlots(null);    setSlots(await booking.slots({ service: next.id, timeZone, days: 7 }));  }  async function pick(time: string) {    setError(null);    try {      setHold(await booking.hold({ service: service!.id, startsAt: time }));      setStartsAt(time);    } catch (failure) {      setError((failure as Error).message);      if (isTimeTaken(failure)) await choose(service!);    }  }  async function book(event: FormEvent<HTMLFormElement>) {    event.preventDefault();    const form = new FormData(event.currentTarget);    try {      const { appointment } = await booking.book({        service: service!.id,        startsAt: startsAt!,        holdToken: hold!.token,        name: String(form.get("name")),        email: String(form.get("email")),        timeZone,      });      setBooked(appointment);    } catch (failure) {      setError(failure instanceof BookingError ? failure.message : "Something went wrong. Try again.");      if (isTimeTaken(failure)) {        setHold(null);        await choose(service!);      }    }  }  if (booked) {    return (      <main>        <h1>You're booked</h1>        <p>{booked.service.name} with {booked.staff ?? "our team"}, {dateOf(booked.startsAt)} at {timeOf(booked.startsAt)}.</p>        <p>Your reference is {booked.reference}. We've sent the details to {booked.attendee?.email}.</p>        <p><a href={booked.manageUrl}>Change or cancel</a></p>      </main>    );  }  return (    <main>      <h1>Book at Northwilds Oslo</h1>      {error && <p role="alert">{error}</p>}      <ul>        {services.map((entry) => (          <li key={entry.id}>            <button type="button" onClick={() => void choose(entry)} aria-pressed={service?.id === entry.id}>              {entry.name}, {entry.durationMinutes} minutes            </button>          </li>        ))}      </ul>      {slots && !hold && (        <section>          <h2>Pick a time</h2>          {slots.days.filter((day) => day.slots.length > 0).map((day) => (            <div key={day.date}>              <h3>{dayOf(day.date)}</h3>              {day.slots.map((slot) => (                <button key={slot.startsAt} type="button" onClick={() => void pick(slot.startsAt)}>                  {timeOf(slot.startsAt)}                </button>              ))}            </div>          ))}          {slots.days.every((day) => day.slots.length === 0) && <p>No free times this week{slots.next ? `. The next is ${dateOf(slots.next.startsAt)}.` : "."}</p>}        </section>      )}      {hold && startsAt && (        <form onSubmit={(event) => void book(event)}>          <h2>{service!.name} at {timeOf(startsAt)}</h2>          <p>We're holding this time for you for 10 minutes.</p>          <label>Name <input name="name" required autoComplete="name" /></label>          <label>Email <input name="email" type="email" required autoComplete="email" /></label>          <button type="submit">Book</button>        </form>      )}    </main>  );}

What happens:

  1. services() lists the services on the booking page.
  2. slots() asks for seven days of free times in the visitor's time zone.
  3. hold() keeps the chosen time for 10 minutes while the visitor types. If someone else took it a moment ago, the free times load again.
  4. book() books with the hold's token. Booking Orbit emails the confirmation and the reminders, and manageUrl is the visitor's page to change or cancel.

6Run it

Shell
npm run dev

Open http://localhost:5173, choose a service, pick a time and book. The booking appears under Calendar in Booking Orbit. Cancel it with the Change or cancel link when you're done.

If the free times load but booking fails with "This website isn't allowed to book here", the address in your browser isn't among the allowed websites yet.

Make it yours

  • Ask what the location asks: location() says whether a phone number and notes are required, optional or hidden. service(id) returns the form's questions; send the answers as answers, keyed by question id. See Booking in the public booking API.
  • Let customers choose a person: staff(service) lists the people, and slots({ service, staff }) their own times.
  • Paid services: The SDK doesn't take payments. For a service paid online when it's booked, hold() and book() throw BookingPaymentRequiredError. Check with isPaymentRequired(error) and send the customer to error.bookingUrl, the booking page with the time already chosen, or open the widget.
  • Paused locations: Catch BookingPausedError and say that online booking is unavailable for now.

Was this page helpful?

Read next