@astrocal/widget

@astrocal/widget

Embeddable booking widget for Astrocal — drop-in scheduling UI for any website or app.

Installation

npm install @astrocal/widget

Quick Start (ESM)

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
open({
  eventTypeId: "your-event-type-id",
  mode: "inline",
  target: "#booking-container",
});

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

CDN Usage (Script Tag)

For non-npm users, load the widget via a script tag:

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

Or use auto-initialization with data attributes:

<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>

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.

WidgetConfig

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

ThemeConfig

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 (e.g., Next.js, Nuxt). The autoInit() function is guarded and will not run on the server. However, open() and destroy() require a browser environment and will throw a clear error if called without a DOM. close() is a silent no-op on the server.

// Safe — no error on import
import { open } from "@astrocal/widget";

// Only call in browser context
if (typeof window !== "undefined") {
  open({ eventTypeId: "..." });
}

Documentation

Full documentation at docs.astrocal.dev.

License

MIT