@cosmocart/bookings-widget

Drop-in React booking widget for Cosmo Bookings. Renders a slot picker, customer info form, and confirmation step against the Cosmo API. Works in any React 18/19 app — Vite, Next.js (App or Pages router), Remix, etc.

Install

npm install @cosmocart/bookings-widget
# or pnpm / yarn / bun

Use

import { BookingWidget } from '@cosmocart/bookings-widget';
import '@cosmocart/bookings-widget/styles.css';

export default function BookingPage() {
  return (
    <BookingWidget
      apiBaseUrl="https://api.cosmo-bookings.com"
      pkKey="pk_live_..." // get from your Cosmo dashboard
      serviceId="..."
      ownerId="..." // optional, enables realtime slot updates
      title="Book your appointment"
    />
  );
}

The widget is a 'use client' component and is safe to drop directly into a Next.js Server Component file.

Theming

All colors and the corner radius are exposed as CSS variables. Override any of them on a parent element to re-skin without touching JS:

.my-booking-page {
  --cosmo-bg: #1a1a1a;
  --cosmo-fg: #f5efe7;
  --cosmo-accent: #d1bfaa;
  --cosmo-accent-fg: #1a1a1a;
  --cosmo-border: rgba(209, 191, 170, 0.18);
  --cosmo-radius: 12px;
}

The full token list lives in src/styles.css.

What's in the box

• BookingWidget — the full pre-styled widget.
• useAvailability(...) — headless React hook if you want your own slot picker UI.
• connectRealtime(...) — low-level Socket.IO subscription helper.
• CosmoApiClient / CosmoApiError — typed REST client; error.isSlotTaken() for the 409 SLOT_TAKEN race outcome.

Realtime + race UX

The widget subscribes to a WebSocket gateway and removes a slot from the picker the instant another customer books it. If a slow client still submits a taken slot, the API returns 409 SLOT_TAKEN; the widget shows "Oops — that slot was just taken" and refetches.

License

AGPL-3.0. You can install + use this widget on your site freely. If you fork it and run a modified version as part of a hosted service, the AGPL requires you to publish your modifications under the same license.