A React library for integrating Tebuto appointment booking into your website.
## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Widget Configuration](#widget-configuration)
- [Props Reference](#props-reference)
- [Theme Configuration](#theme-configuration)
- [Building Custom Booking UIs](#building-custom-booking-uis)
- [TebutoProvider](#tebutoprovider)
- [useBookingFlow Hook](#usebookingflow-hook)
- [Individual Hooks](#individual-hooks)
- [useTherapist](#usetherapist)
- [useAvailableSlots](#useavailableslots)
- [useClaimSlot](#useclaimslot)
- [useBookAppointment](#usebookappointment)
- [Custom Booking Example](#custom-booking-example)
- [API Types](#api-types)
- [License](#license)
## Features
- **Drop-in Widget** - Embed the Tebuto booking widget with a single component
- **Custom Booking UIs** - Build your own booking interface with powerful React hooks
- **Full TypeScript Support** - Complete type definitions for all APIs
- **Theming** - Customize colors, fonts, and styles to match your brand
- **React 19 Compatible** - Built for the latest React version
## Installation
```bash
# npm
npm install @tebuto/react-booking-widget
# pnpm
pnpm add @tebuto/react-booking-widget
# yarn
yarn add @tebuto/react-booking-widget
```
**Requirements:** React 19.0.0 or higher
## Quick Start
The simplest way to add Tebuto booking to your site:
```tsx
import { TebutoBookingWidget } from "@tebuto/react-booking-widget";
function BookingPage() {
return ;
}
```
> **Note:** You can obtain the therapist UUID from the [appointment settings](https://app.tebuto.de/einstellungen/termine). In the embedding section, click on the HTML button and use the value from the `data-therapist-uuid` attribute.
## Widget Configuration
### Props Reference
| Prop | Type | Required | Default | Description |
| ------------------ | ------------------- | -------- | --------------- | ------------------------------------------- |
| `therapistUUID` | `string` | Yes | - | Unique identifier for the therapist |
| `backgroundColor` | `string` | No | `transparent` | Background color (hex, rgb, etc.) |
| `border` | `boolean` | No | `true` | Show border around the widget |
| `categories` | `number[]` | No | `[]` | Filter appointments by category IDs |
| `includeSubusers` | `boolean` | No | `false` | Include subuser appointments |
| `showQuickFilters` | `boolean` | No | `false` | Show quick filter buttons for time slots |
| `inheritFont` | `boolean` | No | `false` | Use parent page font instead of widget font |
| `theme` | `TebutoWidgetTheme` | No | - | Theme customization object |
| `noScriptText` | `string` | No | Default message | Text shown when JavaScript is disabled |
### Theme Configuration
Customize the widget appearance with the `theme` prop:
```tsx
import { TebutoBookingWidget } from "@tebuto/react-booking-widget";
function BookingPage() {
return (
);
}
```
| Theme Property | Type | Description |
| ----------------- | --------- | ------------------------------------------- |
| `primaryColor` | `string` | Primary brand color for buttons, highlights |
| `backgroundColor` | `string` | Main widget background |
| `textPrimary` | `string` | Primary text color |
| `textSecondary` | `string` | Secondary/muted text color |
| `borderColor` | `string` | Border color |
| `fontFamily` | `string` | Font family for the widget |
| `inheritFont` | `boolean` | Inherit font from parent page |
## Building Custom Booking UIs
For complete control over your booking interface, use the provided hooks to build a custom implementation.
### TebutoProvider
Wrap your booking components with `TebutoProvider` to share configuration:
```tsx
import { TebutoProvider } from "@tebuto/react-booking-widget";
function App() {
return (
);
}
```
| Prop | Type | Required | Description |
| ----------------- | ---------- | -------- | -------------------- |
| `therapistUUID` | `string` | Yes | Therapist identifier |
| `apiBaseUrl` | `string` | No | Custom API base URL |
| `categories` | `number[]` | No | Category filter |
| `includeSubusers` | `boolean` | No | Include subusers |
### useBookingFlow Hook
The `useBookingFlow` hook provides complete booking flow orchestration:
```tsx
import { TebutoProvider, useBookingFlow } from "@tebuto/react-booking-widget";
function BookingUI() {
const {
step,
goToStep,
therapist,
slots,
selectedDate,
selectDate,
selectedDateSlots,
selectedSlot,
selectSlot,
selectedLocation,
setLocation,
submitBooking,
booking,
reset,
isLoading,
error,
} = useBookingFlow({
onBookingComplete: (booking) => console.log("Booked!", booking),
onError: (error) => console.error("Error:", error),
});
switch (step) {
case "loading":
return ;
case "date-selection":
return (
);
case "time-selection":
return ;
case "booking-form":
return ;
case "confirmation":
return (
);
case "error":
return ;
}
}
function App() {
return (
);
}
```
### Individual Hooks
For fine-grained control, use the individual hooks:
#### useTherapist
Fetch therapist information:
```tsx
const { data, isLoading, error, refetch } = useTherapist();
// data: { name, firstName, lastName, address, showWatermark }
```
#### useAvailableSlots
Fetch and manage available time slots:
```tsx
const {
slots, // All available slots
slotsByDate, // Slots grouped by date
availableDates, // Array of dates with availability
getSlotsForDate, // Get slots for a specific date
isLoading,
error,
refetch,
} = useAvailableSlots({ categories: [1, 2] });
```
#### useClaimSlot
Claim (reserve) a time slot before booking:
```tsx
const {
claim, // Claim a slot
unclaim, // Release claimed slot
claimData, // Claim response data
isLoading,
error,
} = useClaimSlot();
// Claim a slot
const response = await claim(selectedSlot);
// response: { isAvailable, requirePhoneNumber, requireAddress }
```
#### useBookAppointment
Complete the booking:
```tsx
const {
book, // Submit booking
booking, // Booking response
downloadCalendar, // Download ICS file
reset, // Reset state
isLoading,
error,
} = useBookAppointment();
// Book appointment
const result = await book({
slot: selectedSlot,
client: {
firstName: "Max",
lastName: "Mustermann",
email: "max@example.com",
phone: "+49123456789", // optional
notes: "First appointment", // optional
},
locationSelection: "onsite", // 'virtual' | 'onsite' | 'not-fixed'
});
```
### Custom Booking Example
The library includes a full example implementation:
```tsx
import { CustomBookingExample } from "@tebuto/react-booking-widget";
function BookingPage() {
return ;
}
```
## API Types
All types are exported for TypeScript users:
```tsx
import type {
// Configuration
TebutoBookingWidgetConfiguration,
TebutoWidgetTheme,
// API Data
Therapist,
TimeSlot,
EnrichedTimeSlot,
ClaimResponse,
BookingRequest,
BookingResponse,
ClientInfo,
// Utilities
AppointmentLocation, // 'virtual' | 'onsite' | 'not-fixed'
Address,
SlotsByDate,
AsyncState,
} from "@tebuto/react-booking-widget";
```
## License
[MIT](LICENSE)
