# Booking

A booking component for Bijection.

- Package: @bijectionhq/booking
- Category: Database & Backend
- Status: Preview
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/booking/tree/238dc6eee0e202e9bb1a20800cac2f49bd1ed727
- Upstream: https://github.com/Finchmedia/booking-component/tree/71eb30ad228d5654f668cdd3c1ae0869b08326b4
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/booking

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/booking.git
cd booking
git checkout 238dc6eee0e202e9bb1a20800cac2f49bd1ed727
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Upstream package documentation

Recorded 2026-10-23. This describes @mrfinch/booking; check the Bijection adaptation separately.

A Convex component for booking rooms, people and equipment. It manages timezone-aware availability, prevents conflicting bookings and reserves several resources atomically. It supports equipment pools, confirmation, cancellation, rescheduling and token-based booking management. Use the backend API for custom interfaces or the included React Booker for single-resource booking flows.

### Use cases

- Prevent overlapping bookings for meeting rooms, studios, and other exclusive resources.
- Manage equipment rental pools with quantity-based availability for interchangeable items.
- Coordinate appointments that require several resources, such as a staff member, room, and equipment, in one atomic booking.
- Add a public booking page with date selection, available time slots, and contact capture using the included React Booker.
- Let customers cancel or reschedule through token-based management links, with optional email notifications through Resend.

### How it works

Register the component in `convex/convex.config.ts` with `app.use(booking)`, then expose booking operations through your own Convex functions. Browser clients call these host functions, which check authorization and your booking policies before delegating to `components.booking.*`. The component keeps booking records and inventory in its own tables and uses transactional checks to prevent conflicting reservations.

Configure resources and schedules with weekly hours, date overrides and IANA timezones, then link resources to the event types that define how they can be booked. Inventory is tracked on a 15-minute grid. Equipment pools and bookings that need several resources use the multi-resource API, which reserves every requested resource atomically.

Bookings, moves and confirmations check one set of rules: the event type and its resources exist, are active, are linked to each other and belong to the event type's organization. Expected failures throw `ConvexError({ code, message })` with documented codes, so your host functions can map them to their own messages. Read-only maintenance audits list stored data that needs attention after an upgrade.

For the React UI, wrap your page in `BookingProvider` with your host's public API and render `<Booker />`. It handles date, duration and slot selection, contact details and confirmation for one exclusive resource, and shows booking errors itself. `onBookingComplete` receives the booking, including its UID, so you can link to your booking management pages.

The backend supports confirmation, cancellation and atomic rescheduling. Token-based management links let customers cancel or move their bookings. Your host controls booking policies and the expiry of provisional bookings, and optional Resend integration adds email notifications.


### Upstream README

Booking and availability for Convex apps. Reserve rooms, people or equipment;
combine resources into a booking; and track quantities for interchangeable items.
Use the React Booker or build your own interface.

[Quick Start](https://convexbooking.dev/docs/getting-started) ·
[API Reference](https://convexbooking.dev/docs/api) ·
[Live Demo](https://convexbooking.dev/book)

Upgrading from 0.4.x? Read the [upgrade guide](https://convexbooking.dev/docs/upgrading)
and the 0.5.0 notes in the
[CHANGELOG](https://github.com/Finchmedia/booking-component/blob/main/CHANGELOG.md).
The 0.4.x README and docs stay available at the
[v0.4.3 tag](https://github.com/Finchmedia/booking-component/tree/v0.4.3).

## Install

Start with an existing [Convex app](https://docs.convex.dev/get-started).
The package requires Convex 1.46 or newer and `convex-helpers` (the component's
paginated queries use its paginator). Use Node 24 LTS for development.

```sh
npm install @mrfinch/booking convex@^1.46.0 convex-helpers@^0.1.124
```

Register the component, then run `npx convex dev`:

```ts
// convex/convex.config.ts
import { defineApp } from "convex/server";
import booking from "@mrfinch/booking/convex.config";

const app = defineApp();
app.use(booking);
export default app;
```

The component registers the [Resend component](https://www.convex.dev/components/resend)
as its own child for optional email; it comes with the package. Email stays off
until your host functions pass `resendOptions` with an API key, so apps without
email need no Resend setup.

For the optional React UI, also install its peer dependencies. Keep your existing
React 18 or 19 installation and use the matching React DOM version.

```sh
npm install react-hook-form@^7.88.0 @hookform/resolvers@^5.9.1 lucide-react@^1.47.0
```

The package includes Zod 4. Backend-only apps can skip these UI peers.

## Your first booking page

Follow the [Quick Start](https://convexbooking.dev/docs/getting-started) to add the
complete public gateway, its rate-limit table, providers and styling. Run the
[setup seed](https://convexbooking.dev/docs/guides#basic-booking-flow) to create and
link a resource, schedule and event type.

With that setup in place, render the Booker beneath your Convex and
`ConvexQueryCacheProvider` providers:

```tsx
// app/book/page.tsx
"use client";
import { Booker, BookingProvider } from "@mrfinch/booking/react";
import { api } from "@/convex/_generated/api";

export default function BookingPage() {
  return (
    <BookingProvider publicApi={api.public}>
      <Booker eventTypeId="quick-meeting" resourceId="meeting-room" title="Book a Meeting" />
    </BookingProvider>
  );
}
```

The Booker handles date, duration and slot selection, contact details and
confirmation for one exclusive resource. Use `onBookingComplete(booking)` to
connect your management pages to the returned booking UID and secret token.