Booking Widget React block for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Booking Widget is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import BookingWidget from @/components/blocks/booking-widget.

import { BookingWidget, type Booking, type BookingSlotContext } from "@/components/blocks/booking-widget"

const services = [
  { id: "cut", name: "Haircut", duration: 45, price: 55, location: "120 Mercer St, New York", locationType: "in-person" as const },
  { id: "color", name: "Color and gloss", duration: 90, price: 140, location: "120 Mercer St, New York", locationType: "in-person" as const },
]

const staff = [
  { id: "emma", name: "Emma Carter", role: "Senior stylist" },
  { id: "liam", name: "Liam Brooks", role: "Colorist", services: ["color"] },
]

async function getTimeSlots(day: Date, { service, staff, timeZone }: BookingSlotContext) {
  const params = new URLSearchParams({ day: day.toDateString(), service: service.id, staff: staff?.id ?? "any", timeZone })
  const res = await fetch(`/api/availability?${params}`)
  return (await res.json()) as string[]
}

export function BookAppointment() {
  const book = async (booking: Booking) => {
    await fetch("/api/bookings", { method: "POST", body: JSON.stringify(booking) })
  }
  return <BookingWidget services={services} staff={staff} getTimeSlots={getTimeSlots} onBook={book} location="Salon" locationType="in-person" />
}

Props

• servicesdefault "DEFAULT_BOOKING_SERVICES"
  BookingService[]

  What can be booked: { id, name, duration (minutes), price?, description?, location?, locationType?, icon?, disabled? }. With one service and no staff the service step is skipped.

• staffdefault "[]"
  BookingStaff[]

  Optional team members: { id, name, role?, avatar?, services? (ids they offer), disabled? }. Adds a who choice under the services; people who do not offer the picked service are hidden.

• hostdefault "DEFAULT_BOOKING_HOST"
  BookingHost

  The person the summary shows while no team member is picked: { name, role?, avatar? }.

• defaultServicedefault ""
  string

  The service id picked at first. Empty: the first enabled service.

• defaultStaffdefault ""
  string

  The team member id picked at first. Empty: "any" when anyStaff is on.

• anyStaffdefault true
  boolean

  Offers Anyone available as the first team choice; getTimeSlots then gets staff: null.

• getTimeSlots
  (day: Date, context: BookingSlotContext) => (string | DateTimeSlot)[] | Promise<(string | DateTimeSlot)[]>

  The free times of a day as "HH:mm" wall times in context.timeZone (or { time, disabled, label }). Gets the service, the team member (null for anyone) and the zone. A promise shows skeleton slots. Pass a stable function. Without it every slot from startTime to endTime is free.

• startTimedefault "09:00"
  string

  The first slot of a day when there is no getTimeSlots.

• endTimedefault "17:00"
  string

  When the day ends without getTimeSlots; the last slot still finishes by then.

• minuteStepdefault 30
  number

  Minutes between slots without getTimeSlots.

• disabledDaysdefault "DEFAULT_BOOKING_DISABLED_DAYS"
  DateMatcher or DateMatcher[] (DateMatcher: Date, Date[], { from, to }, { before }, { after }, { dayOfWeek } or (date) => boolean)

  Days that cannot be booked, as calendar matchers. Weekends by default; past days are always off.

• bookingWindowdefault 60
  number

  How many days ahead can be booked. 0 means no limit.

• defaultValuedefault "null"
  Date | null

  The start picked at first, e.g. the booking being moved. The details step opens with it filled in.

• defaultDetails
  Partial<BookingDetails>

  Prefilled name, email, phone (E.164) and notes, for a signed-in visitor.

• defaultDaydefault ""
  string

  The day the calendar opens on, as "YYYY-MM-DD", with its times listed before one is picked. Empty: no day until the visitor picks one.

• timeZone
  string

  The IANA zone the times are shown in, controlled. Pair it with onTimeZoneChange.

• defaultTimeZonedefault ""
  string

  The starting zone while uncontrolled. Empty: the visitor's device zone.

• onTimeZoneChange
  (zone: string) => void

  Fires when the visitor switches the zone in the picker footer.

• timeZonesdefault "["America/New_York", "America/Chicago", "America/Denver", "America/Los_Angeles", "Europe/London", "Europe/Berlin", "Asia/Tokyo"]"
  string[]

  The zones the switch offers (the current one is always included). [] shows the zone as plain text.

• hourCycledefault "auto"
  "auto" | "h12" | "h23"

  12 or 24 hour times; auto follows the locale.

• step
  "service" | "time" | "details" | "confirmation"

  The current step, controlled. A step that is not reachable yet (details without a time) falls back to the first missing one.

• defaultStepdefault "service"
  "service" | "time" | "details" | "confirmation"

  The starting step while uncontrolled.

• onStepChange
  (step: BookingStep) => void

  Fires on Continue, Back, a step click and after booking.

• layoutdefault "split"
  "split" | "stacked"

  split: the summary column beside the steps from 768px. stacked: the summary as a header row at every width, in a narrower card. Phones always stack.

• showPhonedefault true
  boolean

  Shows the phone field (with a country picker) in the details step.

• requirePhonedefault false
  boolean

  Makes the phone required. Optional phones are still checked when filled in.

• showNotesdefault true
  boolean

  Shows the optional notes field.

• defaultCountrydefault "US"
  string

  The phone field's starting country, as an ISO code ("US", "GB").

• locationdefault "Video call"
  string

  Where the meeting happens, for every service that has no location of its own.

• locationTypedefault "video"
  "video" | "phone" | "in-person"

  The icon next to the location.

• currencydefault "USD"
  string

  The ISO currency of the prices. A price of 0 shows the free label.

• localedefault ""
  string

  Formats dates, times and prices. Empty: the UIProvider locale, then the browser's.

• onBook
  (booking: Booking) => void | Promise<unknown>

  Called by Confirm booking with { service, staff, start, end, timeZone, details, bookedAt, previous? }. A promise keeps the button loading; a rejection shows the bookFailed message. Default: a pretend 900ms request.

• rescheduleHref
  string | ((booking: Booking) => string)

  Turns Reschedule into a link (your reschedule page). Without it Reschedule goes back to the times here.

• icsFileNamedefault "booking.ics"
  string

  The file name of the Add to calendar download.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  Paints the main button, the selected cards, the steps, the picked day and time.

• colordefault ""
  string

  Any CSS color; replaces the tone everywhere. Leave empty to use the tone.

• radiusdefault "lg"
  "none" | "sm" | "md" | "lg"

  The card's corners: 0, 12, 16 or 24px.

• now
  Date | number

  What now means for past days and the booking window. Default: the clock.

• labels
  Partial<BookingWidgetLabels>

  Every string (DEFAULT_BOOKING_WIDGET_LABELS holds the English defaults): step names and headings, timeDescription(days), field labels and placeholders, buttons, the confirmation, the duration formatter and the error messages.

• classNames
  Partial<Record<"summary" | "header" | "host" | "main" | "steps" | "body" | "title" | "services" | "staff" | "picker" | "fields" | "error" | "actions" | "confirmation" | "recap", string>>

  Extra classes for the inner parts.

• className
  string

  Extra classes for the card, merged last (max-w-[960px] for split, max-w-xl for stacked).

Parts

FAQ

Used in

More React form components