@astrocal/react

React SDK for Astrocal — Provider, hooks, API client, and embeddable booking widget for React apps.

Installation

npm install @astrocal/react
# or
pnpm add @astrocal/react

For the widget component, also install the optional peer dependency:

npm install @astrocal/widget

Quick Start

Provider Setup

Wrap your app (or a subtree) with AstrocalProvider to make the API client available via hooks:

import { AstrocalProvider } from "@astrocal/react";

function App() {
  return (
    <AstrocalProvider apiKey="sk_live_...">
      <MySchedulingPage />
    </AstrocalProvider>
  );
}

Using the Hook

Access the typed API client anywhere inside the provider:

import { useAstrocal } from "@astrocal/react";

function EventTypesList() {
  const astrocal = useAstrocal();
  const [eventTypes, setEventTypes] = useState([]);

  useEffect(() => {
    astrocal.eventTypes.list().then(({ data }) => setEventTypes(data));
  }, [astrocal]);

  return (
    <ul>
      {eventTypes.map((et) => (
        <li key={et.id}>
          {et.title} — {et.duration_minutes}min
        </li>
      ))}
    </ul>
  );
}

Standalone Client

Use the API client without React context:

import { AstrocalApiClient } from "@astrocal/react";

const client = new AstrocalApiClient({ apiKey: "sk_live_..." });

const { data: eventTypes } = await client.eventTypes.list();
const { slots } = await client.availability.query({
  event_type_id: eventTypes[0].id,
  start: "2026-03-01",
  end: "2026-03-07",
  timezone: "America/New_York",
});

Widget Component

The AstrocalWidget component wraps @astrocal/widget for seamless React integration.

Inline Mode

Renders the booking calendar directly in your page:

import { AstrocalWidget } from "@astrocal/react";

function BookingPage() {
  return (
    <AstrocalWidget
      eventTypeId="evt_abc123"
      timezone="America/New_York"
      colorScheme="light"
      onBookingCreated={(booking) => {
        console.log("Booked!", booking.id);
      }}
    />
  );
}

Popup Mode

Wraps a trigger element that opens the widget as a modal on click:

import { AstrocalWidget } from "@astrocal/react";

function BookButton() {
  return (
    <AstrocalWidget eventTypeId="evt_abc123" mode="popup">
      <button>Book a Meeting</button>
    </AstrocalWidget>
  );
}

Widget Props

Prop	Type	Default	Description
eventTypeId	string	—	Event type UUID (required)
mode	"inline" | "popup"	"inline"	Render mode
apiUrl	string	"https://api.astrocal.dev"	API base URL
timezone	string	auto-detect	IANA timezone
theme	ThemeConfig	—	CSS custom property overrides
colorScheme	"light" | "dark" | "auto"	"auto"	Color scheme
demo	boolean	false	Demo mode (mock data)
onBookingCreated	(booking) => void	—	Booking success callback
onError	(error) => void	—	Error callback
onClose	() => void	—	Popup close callback
className	string	—	Container CSS class
style	CSSProperties	—	Container inline styles

API Client Methods

Event Types

client.eventTypes.list(); // GET /v1/event-types
client.eventTypes.get(id); // GET /v1/event-types/:id
client.eventTypes.create(input); // POST /v1/event-types
client.eventTypes.update(id, input); // PATCH /v1/event-types/:id
client.eventTypes.delete(id); // DELETE /v1/event-types/:id

Bookings

client.bookings.list(params?)               // GET /v1/bookings
client.bookings.get(id)                     // GET /v1/bookings/:id
client.bookings.cancel(id, reason?)         // POST /v1/bookings/:id/cancel
client.bookings.reschedule(id, input)       // POST /v1/bookings/:id/reschedule

Availability

client.availability.query(params); // GET /v1/availability

Webhooks

client.webhooks.list()                      // GET /v1/webhooks
client.webhooks.get(id)                     // GET /v1/webhooks/:id
client.webhooks.create(input)               // POST /v1/webhooks
client.webhooks.update(id, input)           // PATCH /v1/webhooks/:id
client.webhooks.delete(id)                 // DELETE /v1/webhooks/:id
client.webhooks.listDeliveries(id, params?) // GET /v1/webhooks/:id/deliveries
client.webhooks.retryDelivery(whId, delId)  // POST /v1/webhooks/:id/deliveries/:id/retry

Usage

client.usage.get()                          // GET /v1/usage
client.usage.summary(period?)               // GET /v1/usage/summary

API Keys

client.apiKeys.list(); // GET /v1/api-keys
client.apiKeys.create(input); // POST /v1/api-keys
client.apiKeys.revoke(id); // DELETE /v1/api-keys/:id

Error Handling

All API errors throw AstrocalError:

import { AstrocalError } from "@astrocal/react";

try {
  await client.eventTypes.get("invalid_id");
} catch (err) {
  if (err instanceof AstrocalError) {
    console.log(err.status); // 404
    console.log(err.code); // "not_found"
    console.log(err.message); // "Event type not found"
  }
}

Next.js

Works with both App Router and Pages Router. For App Router, the provider and widget include "use client" directives automatically.

// app/layout.tsx
import { AstrocalProvider } from "@astrocal/react";

export default function RootLayout({ children }) {
  return (
    <AstrocalProvider apiKey={process.env.NEXT_PUBLIC_ASTROCAL_KEY!}>{children}</AstrocalProvider>
  );
}

TypeScript

All types are exported for use in your application:

import type {
  EventType,
  Booking,
  AvailabilitySlot,
  PaginatedResponse,
  AstrocalClient,
} from "@astrocal/react";

License

MIT