@riposte.co/scheduler

Overview

@riposte.co/scheduler bundles the <riposte-scheduler> custom element plus its type definitions, so importing the package automatically registers the component and exposes the RiposteSchedulerElement class for direct use.

The element is attribute-driven: changing experience-slug, api-base-url, or api-key forces a re-initialization, while updates to presentation attributes (locale, duration, copy overrides) trigger a lightweight re-render.

Installation

npm install @riposte.co/scheduler

Import the package once near your app shell (or lazily in a route/component) to ensure the browser registers the custom element before you render it.

Render the widget

import '@riposte.co/scheduler'

export function SchedulerWidget() {
  return (
    <riposte-scheduler
      api-base-url="/api"
      experience-slug="demo-onboarding"
      duration-minutes="30"
      timezone="America/Los_Angeles"
      data-text-headline="Pick a time with our team"
    />
  )
}

• api-base-url is trimmed automatically and prepended to every fetch the component makes.
• experience-slug selects the server-side scheduler experience to load.
• api-key is optional; when present it’s injected into x-api-key headers for all requests.
• duration-minutes, timezone, locale, and the full set of data-text-* attributes are observed so you can tweak runtime behavior without reloading the page.

Element attributes

Attribute	Required	Description
api-base-url	✅	Base URL or path segment that fronts the Riposte server (/api, https://riposte.yourcompany.com). The element trims trailing slashes before issuing requests.
experience-slug	✅	Scheduler experience identifier defined in the admin portal; determines routing rules, booking form, and theming defaults.
api-key	Optional	Injected as an x-api-key header on every request. Useful when your proxy enforces API keys instead of session cookies.
duration-minutes	Optional	Overrides the duration configured on the experience so you can expose preset buttons (15/30/45). Defaults to 30 minutes.
timezone	Optional	Forces the widget to render availability in a fixed timezone instead of auto-detecting the visitor’s locale.
locale	Optional	BCP-47 locale tag (for example en-US, fr-FR) that controls date formatting and copy selection.
data-default-account-ids	Optional	JSON array of host account IDs to seed into the experience when it first loads (mirrors the portal’s “Default hosts” toggle).
data-text-*	Optional	Copy overrides for any UI string. Transform the key to kebab-case: data-text-headline, data-text-success-body, data-text-weekday-saturday, etc.
data-custom-styles	Optional	Raw CSS string appended after the base styles. Great for quick tweaks without bundling a stylesheet.

All attributes are reactive. Changing any value while the component is mounted triggers either a re-initialization (api-base-url, experience-slug, api-key) or a light re-render (everything else).

Copy overrides

Every headline, label, and helper string maps to a data-text-* attribute. Common keys:

• data-text-headline / data-text-subheadline
• data-text-success-headline / data-text-success-body
• data-text-availability-heading, data-text-availability-subheading
• data-text-weekday-{sunday|monday|...}
• data-text-details-flexible-title, data-text-details-flexible-description

Less common strings (such as button labels) follow the same pattern—open the admin portal’s embed tab to inspect the generated snippet, or refer to the scheduler guide for a full list. For dynamic experiments, update the attributes in React/Next state and the component will re-render immediately.

Theming hooks

There are three ways to make the scheduler match your product:

1. Experience UI theme – Set colors, fonts, and layout defaults in the admin portal (ui.theme, ui.layout, ui.copy). These ship with the experience payload so every embed sees the same baseline without extra code.
2. CSS custom properties – The component exposes brand tokens on :host that you can override globally or per-instance:

riposte-scheduler {
  --riposte-scheduler-primary: #0f172a;
  --riposte-scheduler-accent: #f97316;
  --riposte-scheduler-background: #fefce8;
  --riposte-scheduler-text: #0a0a0a;
  --riposte-scheduler-surface: #ffffff;
  --riposte-scheduler-border-radius: 20px;
  --riposte-scheduler-font-family: 'Inter', sans-serif;
}

3. Inline styles – Pass data-custom-styles with a CSS string to inject rules after the base stylesheet. This is handy when you need quick one-off adjustments without editing your global CSS.

Network flow

The widget automatically orchestrates the three scheduler API calls:

1. Experience bootstrap – GET {api-base-url}/scheduler/experiences/{slug} loads metadata, UI defaults, and callback configuration.
2. Availability pagination – For each month the user browses, the element POSTs a range payload (start, end, timezone, duration) to /scheduler/experiences/{slug}/availability, reusing any metadata you injected on the DOM node.
3. Booking submission – Confirmations POST to /scheduler/experiences/{slug}/bookings with the selected slot, guest info, custom form responses, and per-slot metadata so your callback knows which host claimed the meeting.

All requests share the same base URL, include cookies by default, and send headers from api-key plus any you add at your proxy layer via forwardHeaders.

Copy & theming

• Every string in the UI maps to a data-text-* attribute; the element builds this list at runtime so you can override headline, successBody, weekday labels, and more without shipping a new bundle.
• Theme values (color, typography, radius) translate into CSS custom properties under the :host, giving you predictable hooks for global styles or scoped overrides.
• Set data-custom-styles with a string of CSS to append after the base styles if you need deeper control; toggling this attribute triggers a re-render just like the copy overrides.

TypeScript support

The package ships .d.ts files alongside the compiled JavaScript, so you can import RiposteSchedulerElement or the scheduler interfaces for advanced integrations (for example, registering the element manually or extending it with your own logic).