@astrocal/widget

@astrocal/widget

Add scheduling to any website in under 60 seconds. The official embeddable booking widget from Astrocal — the API-first scheduling platform built for developers.

Drop in a script tag or install from npm. Your visitors book meetings directly on your site — no redirects, no iframes, no Calendly branding.

Get started free | Widget Documentation | Live Demo

Why Astrocal's Widget?

• Shadow DOM isolation — Widget styles never leak into or clash with your site's CSS. Zero conflicts, guaranteed.
• Fully themeable — Match your brand with CSS custom properties. Override colors, fonts, border radius, and more.
• Popup or inline — Open as a modal overlay, or embed directly into any container on your page.
• Whitelabel ready — Remove Astrocal branding on paid plans. It's your booking experience.
• Mobile-first — Responsive from 320px up. Looks great on every screen size.
• SSR safe — Works with Next.js, Nuxt, Astro, and any SSR framework. No hydration errors.
• Light, dark, and auto — Respects prefers-color-scheme or set it explicitly.

Quick Start (Script Tag)

No build step required. Load from CDN and go:

<script src="https://cdn.astrocal.dev/widget/latest/astrocal.js"></script>
<script>
  Astrocal.open({
    eventTypeId: "your-event-type-id",
    mode: "popup",
  });
</script>

Or use data attributes for zero-JavaScript setup:

<script src="https://cdn.astrocal.dev/widget/latest/astrocal.js"></script>
<div data-astrocal-event-type-id="your-event-type-id" data-astrocal-mode="inline"></div>

Quick Start (npm)

npm install @astrocal/widget

import { open } from "@astrocal/widget";

open({
  eventTypeId: "your-event-type-id",
  mode: "popup",
});

Inline Mode

Mount the widget into a specific DOM element:

import { open, destroy } from "@astrocal/widget";

// Mount into a container
open({
  eventTypeId: "your-event-type-id",
  mode: "inline",
  target: "#booking-container",
});

// Clean up when done
destroy("#booking-container");

API

open(config: WidgetConfig): void

Opens the booking widget in inline or popup mode.

close(): void

Closes the popup widget if open. No-op if no popup is active.

destroy(target: string | HTMLElement): void

Destroys an inline widget mounted on a target element. Removes the Shadow DOM and cleans up all resources. No-op if no widget is mounted on the target.

autoInit(): void

Scans the DOM for elements with data-astrocal-* attributes and mounts widgets automatically.

Configuration

Property	Type	Default	Description
eventTypeId	string	required	Event type UUID to display
apiUrl	string	"https://api.astrocal.dev"	API base URL
mode	"inline" | "popup"	"popup"	Render mode
target	string | HTMLElement	---	DOM element or CSS selector (inline mode)
timezone	string	auto-detected	IANA timezone override
theme	ThemeConfig	---	CSS custom property overrides
colorScheme	"light" | "dark" | "auto"	"auto"	Color scheme
demo	boolean	false	Enable demo mode (mock data, no API calls)
onBookingCreated	(booking: BookingResult) => void	---	Booking success callback
onError	(error: WidgetError) => void	---	Error callback
onClose	() => void	---	Popup close callback

Theming

Customize the widget to match your brand:

open({
  eventTypeId: "your-event-type-id",
  theme: {
    primaryColor: "#6366f1",
    primaryHoverColor: "#4f46e5",
    backgroundColor: "#ffffff",
    textColor: "#1f2937",
    borderRadius: "12px",
    fontFamily: "Inter, sans-serif",
  },
});

Property	CSS Custom Property	Description
primaryColor	--astrocal-primary	Primary action color
primaryHoverColor	--astrocal-primary-hover	Primary hover color
headingColor	--astrocal-heading	Heading text color
backgroundColor	--astrocal-bg	Widget background
textColor	--astrocal-text	Body text color
borderColor	--astrocal-border	Border color
borderFocusColor	--astrocal-border-focus	Focused border color
borderRadius	--astrocal-radius	Border radius
fontFamily	--astrocal-font	Font family

SSR / Server-Side Rendering

The package is safe to import in Node.js environments like Next.js, Nuxt, or Astro. The autoInit() function is guarded and won't run on the server. open() and destroy() require a browser and will throw a clear error if called without a DOM. close() is a silent no-op on the server.

import { open } from "@astrocal/widget";

if (typeof window !== "undefined") {
  open({ eventTypeId: "..." });
}

Part of the Astrocal Platform

This widget is one of several ways to integrate Astrocal scheduling into your product:

• React SDK (@astrocal/react) — Typed hooks, provider, and widget wrapper for React apps
• MCP Server (@astrocal/mcp-server) — Let AI agents book meetings via the Model Context Protocol
• REST API — Full scheduling API with OpenAPI 3.1 spec
• Webhooks — Real-time notifications for booking lifecycle events
• Dashboard — Manage event types, bookings, team members, and billing

Create a free account to get your event type ID and start embedding.

Links

• Astrocal Website
• Widget Guide
• Documentation
• Dashboard
• Pricing
• GitHub
• Issues

License

MIT