For the complete documentation index, see llms.txt.

React Components

@vennio/react — Drop-in React components for booking and scheduling UIs.

Installation

npm install @vennio/react

VennioProvider

Wrap your app (or the subtree that uses Vennio components) with VennioProvider:

import { VennioProvider } from '@vennio/react'

function App() {
  return (
    <VennioProvider
      publishableKey="vennio_pk_live_YOUR_KEY"
      baseUrl="https://api.vennio.app"
    >
      <YourApp />
    </VennioProvider>
  )
}

BookingCalendar

A complete booking calendar component that queries availability and handles booking creation:

import { BookingCalendar } from '@vennio/react'

function SchedulingPage() {
  return (
    <BookingCalendar
      shortCode="your-shortcode"
      onBooked={(booking) => {
        console.log('Booking confirmed:', booking.id)
      }}
      onError={(err) => console.error(err)}
    />
  )
}

BookingCalendar props

Prop	Type	Required	Description
shortCode	string	Yes	The Venn Link shortcode to book
baseUrl	string	No	Override the API base URL
apiKey	string	No	Publishable API key (if not using provider)
onBooked	(booking: Booking) => void	No	Called when booking is confirmed
onCheckout	(url: string) => void	No	Called when a Stripe Checkout URL is produced
onError	(error: Error) => void	No	Called on error
successUrl	string	No	Redirect URL after successful checkout
cancelUrl	string	No	Redirect URL after cancelled checkout
className	string	No	Additional CSS class names
primaryColor	string	No	Primary accent colour (CSS value)

The Booking object passed to onBooked contains:

• booking.id — booking identifier (e.g. "booking_xyz789")
• booking.status — "confirmed"
• booking.start_time / booking.end_time — ISO 8601 strings
• booking.customer_email, booking.customer_name

TimeSlotPicker

A presentational component that renders available time slots as a grid. Does not fetch data — pair it with useSlots to supply slots.

import { TimeSlotPicker } from '@vennio/react'

<TimeSlotPicker
  slots={slots}
  selectedSlot={selected}
  onSelect={setSelected}
  loading={loading}
  emptyMessage="No times available"
/>

TimeSlotPicker props

Prop	Type	Description
slots	Slot[]	Array of slot objects to display
selectedSlot	Slot | null	Currently selected slot
onSelect	(slot: Slot) => void	Called when a slot is clicked
primaryColor	string	Accent colour for the selected state
className	string	Additional CSS class names
loading	boolean	Shows a loading skeleton when true
emptyMessage	string	Message shown when slots is empty

Slots are grouped by date and rendered as a grid. For a composition example, see the Availability Picker guide.

BookingForm

A customer details form component for collecting name, email, and any custom fields before submitting a booking:

import { BookingForm } from '@vennio/react'

<BookingForm
  slot={selectedSlot}
  shortCode="your-shortcode"
  onBooked={(booking) => console.log(booking)}
/>

BookingConfirmation

A post-booking confirmation display component. Pass it the Booking object returned after a successful booking:

import { BookingConfirmation } from '@vennio/react'

<BookingConfirmation booking={booking} />

useVennio hook

A combined data hook that fetches slots and creates bookings for a given Venn Link. Must be used inside a VennioProvider tree.

import { useVennio } from '@vennio/react'

function BookingActions({ shortCode }) {
  const { loading, error, getSlots, book } = useVennio({ shortCode })
  // getSlots() → Promise<Slot[]>
  // book(slot, customer) → Promise<BookingResponse>
}

Return	Type	Description
loading	boolean	True while a request is in flight
error	string | null	Error message from the last failed request
getSlots	() => Promise<Slot[]>	Fetch available slots for the shortcode
book	(slot: Slot, customer: Customer) => Promise<BookingResponse>	Submit a booking

To read context values (apiKey, baseUrl), use useVennioContext instead.

useSlots hook

Fetch available slots for a Venn Link. Calls GET /v1/venn-links/:shortCode/availability.

import { useSlots } from '@vennio/react'

function AvailabilitySection() {
  const { slots, loading, error, refetch } = useSlots({
    shortCode: 'your-shortcode',
  })
  // ...
}

useSlots options

Option	Type	Default	Description
shortCode	string	—	Required. The Venn Link shortcode
baseUrl	string	From provider	Override the API base URL
apiKey	string	From provider	Override the API key
autoFetch	boolean	true	Fetch on mount automatically

useSlots return value

Key	Type	Description
slots	Slot[]	Available slots
loading	boolean	True while fetching
error	string | null	Error message if fetch failed
refetch	() => void	Manually trigger a new fetch

Composition pattern

Compose useSlots and TimeSlotPicker for a fully custom slot picker:

import { TimeSlotPicker, useSlots } from '@vennio/react'
import { useState } from 'react'

export function AvailabilityPicker({ shortCode }) {
  const { slots, loading, error } = useSlots({ shortCode })
  const [selected, setSelected] = useState(null)
  return (
    <TimeSlotPicker
      slots={slots} selectedSlot={selected} onSelect={setSelected}
      loading={loading} emptyMessage={error || 'No times available'}
    />
  )
}

For the full guide including gotchas, see the Availability Picker guide.