`). Props in, transactions out — no DOM back-channels. Add `interactive: { resize: { attr: 'width_pct' } }` for magnetic-snap resizing, or `interactive: false` to opt out of all chrome. **Tip:** Planning to use collaborative editing later? Define custom block **schemas** with `defineBlockSchema()` in a file shared with your Worker and compose the UI half client-side — `buildSchema()` and `schemaHash()` from `@delightstack/editor/schema` are worker-safe. ## Server rendering ```typescript import { renderHTML, renderText } from '@delightstack/editor/render'; // +page.server.ts — no editor code ships to the browser export const load = async () => { const doc = await getDocument(); return { html: renderHTML(doc, { image_url: (id) => imageURL(id) }) }; }; // Search indexing / AI context const plaintext = renderText(doc); ``` Custom blocks render through the same `render` function declared in their spec — pass them with `renderHTML(doc, { blocks: { stat: statRenderer } })`. ## Roadmap Designed and planned, landing in phases: collaborative editing (prosemirror-collab with a Durable Object authority over [`websocket`](/packages/websocket/)), live cursors via [`presence`](/packages/presence/), comments anchored through the step log ([`database`](/packages/database/)), version history / time travel, AI writing suggestions via [`ai`](/packages/ai/), `@` mentions, and layout/column blocks. --- # Images > Cloudflare Container–based image processing — optimized variants, ThumbHash placeholders, EXIF, color extraction, and face-aware crops. `@delightstack/images` is image processing for Cloudflare Workers. Upload an image and get back optimized variants, rich metadata, a ThumbHash placeholder, extracted colors, and everything you need to display images beautifully — powered by **Sharp/libvips** running in a **Cloudflare Container**. ## Features - **Optimized variants** — resize and encode to AVIF, WebP, JPEG, or PNG with quality/fit control. - **Rich metadata** — dimensions, EXIF (orientation, GPS, date), color space, ICC profile. - **ThumbHash placeholders** — ~33-char hash → blurred preview with transparency + aspect ratio. - **Color extraction** — background and accent color in OKLCH for native CSS. - **Face-aware crops** — MediaPipe BlazeFace for smart square avatars. - **Special formats** — SVG sanitization, PDF first-page render, animated GIF/WebP/APNG. - **CDN serving** — a SvelteKit hook with ETag/304 and immutable caching. ## How it works The package has two halves: **worker-side code** (runs in your Worker / Database DO) and a **Docker container** (`ImageProcessorContainer`, runs in Cloudflare Containers with native libraries). The worker stores originals/variants in **R2**; the container does the heavy lifting and returns a `multipart/mixed` response of metadata + binary variants. ```bash pnpm add @delightstack/images ``` | Import | Use | | --- | --- | | `@delightstack/images/worker` | `ImageProcessorContainer` — the Container Durable Object | | `@delightstack/images` | `imageProcessing`, `createImageHandle`, `defineImageTable`, `toImageProps` | Needs an `R2` bucket and the `ImageProcessorContainer` declared in `wrangler.toml`, plus the container `Dockerfile` (shipped in the package) — see [Architecture](/getting-started/architecture/). ## Two modes - **Mode 1 — database-backed (async):** `imageProcessing()` stores the upload, schedules a DO alarm, and returns immediately; the alarm processes and updates the record. Best for user uploads. - **Mode 2 — standalone (sync):** call the processor directly and get variants back in the response. ## CDN hook + display ```typescript // hooks.server.ts — serve variants from R2 with caching import { createImageHandle } from '@delightstack/images'; export const imageHandle = createImageHandle({ getBucket: (event) => event.platform.env.R2, }); ``` ```svelte ``` **Note:** `toImageProps()` feeds the [`Image`](/components/media/image/) component its background color, ThumbHash, and variant URLs for three-tier progressive loading. See the [package README](https://github.com/brianschwabauer/delightstack/tree/main/packages/images) for watermarks, face cropping, and container deployment. --- # Packages Overview > DelightStack's edge-native backend packages for Cloudflare Workers — auth, database, realtime, AI, billing, and images, built on Durable Objects. DelightStack's **backend packages** are for building full-stack apps on **Cloudflare Workers**. Each package is edge-native, built on **Durable Objects**, and designed to work together — but every one of them stands on its own. **Note:** The backend packages are a separate product from the [component library](/getting-started/introduction/). You can use the components without the backend, the backend without the components, or both together. ## The packages - [@delightstack/auth](/packages/auth/) — JWT sessions, Argon2id password hashing, OAuth, magic links, multi-org, invitations, and SvelteKit route guards. - [@delightstack/database](/packages/database/) — Type-safe reactive SQLite on Durable Objects, with full-text + vector search (Orama), Zod validation, and automatic migrations. - [@delightstack/websocket](/packages/websocket/) — Room-scoped realtime with reactive presence, typed events, hibernation, and live database sync. - [@delightstack/presence](/packages/presence/) — Live cursors, online roster, cursor chat, reactions, and field presence — on a swappable transport and identity. - [@delightstack/ai](/packages/ai/) — Chat completions, resumable streaming over WebSocket, and async vector embeddings via Cloudflare AI Gateway. - [@delightstack/stripe](/packages/stripe/) — Stripe billing — products, subscriptions, metered usage, webhooks, and subscription guards. - [@delightstack/images](/packages/images/) — Image processing via Cloudflare Containers — variants, ThumbHash, EXIF, color extraction, and face-aware crops. - [@delightstack/rate-limiter](/packages/rate-limiter/) — Token-bucket rate limiting as a Durable Object, with zero runtime dependencies. ## What they share - **Durable Objects everywhere.** Each package's server lives in a Durable Object, giving you a **single-writer model** — one instance handles all writes for a given key, so there are no race conditions. SQLite provides durable, transactional storage inside the DO. - **Edge-native.** No external database, queue, or cache to provision. Everything runs on Cloudflare's network, close to your users. - **Reactive Svelte 5 clients.** `auth`, `database`, `websocket`, `ai`, and `stripe` ship a client built on Svelte 5 runes (`$state`/`$derived`) with off-thread workers and optimistic updates. - **SvelteKit handles.** Most packages expose a `create*Handle()` that plugs into SvelteKit's `handle` hook, wiring API routes, auth, and CSRF for you. - **`DelightError` for errors.** Every package throws the single `DelightError` class from `@delightstack/utilities` for consistent, serializable error responses. ## Not drop-in libraries — infrastructure Unlike the component library, these packages assume a specific **Cloudflare Workers + Durable Objects topology**: you re-export the DO classes from a Worker, declare them in `wrangler.toml` with migrations, and bind them into your app. The [Architecture](/getting-started/architecture/) page explains that wiring, and the [example app](https://github.com/brianschwabauer/delightstack/tree/main/apps/example-app) is the canonical reference for putting it all together. ## Next steps - [Architecture](/getting-started/architecture/) — Durable Object topology, bindings, and migrations - [Quick Start: Full Stack](/getting-started/quick-start-stack/) — stand up the example app end-to-end - Pick a package from the sidebar to go deep --- # Presence > Real-time presence for Svelte 5 — online roster, live cursors, cursor chat, reactions, and field presence, on a swappable transport and identity. `@delightstack/presence` adds a real-time **presence** layer for Svelte 5 — an online roster, live cursors, cursor chat, reactions, and field/cell presence. It builds on `@delightstack/websocket` and `@delightstack/auth`, but both are **optional**: the core depends only on two small interfaces, so any transport or identity provider can be dropped in. ```svelte

``` **Tip:** The demo above is real — open this page in a second browser tab and your cursor appears in both. The two extra cursors are simulated peers so the demo isn't lonely. ## Features - **Online facepile** — a deduplicated roster of online members (merged across each user's tabs) with status dots, idle dimming, overflow, and hovercards. - **Live cursors** — pointer positions normalized across viewport sizes and spring-smoothed; shown only for peers on the same page. - **Cursor chat** — Figma-style ephemeral messages that ride along your cursor (press `/`). - **Reactions** — fire-and-forget emoji that float up for everyone on the page. - **Field presence** — a colored ring + name badge showing who's editing which field or cell. - **Swappable transport & identity** — the core never imports websocket or auth; the default adapters are optional peers. ## Install ```bash pnpm add @delightstack/presence ``` | Import | Use | | --- | --- | | `@delightstack/presence` | `PresenceClient`, `setPresence`/`getPresence`, `trackCursor`, `fieldPresence` | | `@delightstack/presence/adapters` | `createDelightPresence`, `websocketTransport`, `authIdentity` | | `@delightstack/presence/components` | `PresenceAvatars`, `Cursors`, `Reactions`, `FieldPresence` | | `@delightstack/presence/server` | `createPresenceServer`, `PRESENCE_EPHEMERAL_EVENTS` | ## 1. Add presence to the WebSocket server Compose the presence module into your Durable Object so `presence:*` messages are relayed, new joiners get an instant snapshot, and cursor traffic uses a generous rate bucket. ```typescript import { WebsocketServer } from '@delightstack/websocket/worker'; import { createPresenceServer, PRESENCE_EPHEMERAL_EVENTS } from '@delightstack/presence/server'; export class AppWebsocketServer extends WebsocketServer { constructor(ctx: DurableObjectState, env: Env) { const presence = createPresenceServer(); super( { onMessage: presence.onMessage, onDisconnect: presence.onDisconnect, rate_limit: { ephemeral_events: PRESENCE_EPHEMERAL_EVENTS }, }, ctx, env, ); } } ``` ## 2. Create the client and provide context ```typescript // +layout.ts — alongside your websocket/auth clients import { createDelightPresence } from '@delightstack/presence/adapters'; const presence = createDelightPresence({ ws, auth }); return { auth, ws, presence }; ``` ```svelte {@render children()} ``` ## 3. Drop in the pieces ```svelte

...

``` **Note:** Cursor coordinates are stored relative to the nearest `data-presence-stage` element (or the document root), so they map to the same logical point across different viewport sizes. ## Swappable transport & identity The core depends on two interfaces, so a different stack works by implementing them and constructing `PresenceClient` directly: ```typescript import { PresenceClient } from '@delightstack/presence'; import type { PresenceTransport, PresenceIdentity } from '@delightstack/presence'; const transport: PresenceTransport = { get connected() { return socket.isConnected; }, get sessions() { return socket.members.map((m) => ({ id: m.id })); }, send: (msg) => socket.publish('presence', msg), on: (handler) => socket.subscribe('presence', handler), }; const identity: PresenceIdentity = { get user() { return me ? { id: me.id, name: me.name, image: me.avatar } : null; }, get orgId() { return me?.orgId ?? null; }, }; const presence = new PresenceClient({ transport, identity }); ``` Your transport must relay every `presence:*` message room-wide. With `@delightstack/websocket`, that's exactly what `createPresenceServer` does. ## How it works - **Awareness model.** Each tab owns a small ephemeral state object; changes broadcast with a monotonic clock and merge last-writer-wins. State is never persisted — it clears on disconnect (graceful `presence:remove`, or a TTL backstop). - **Per-tab keys.** A SharedWorker shares one connection across a browser's tabs, so presence is keyed by a per-tab id; cursors filter out your own user by default. - **Joins.** A newcomer sends `presence:request`; the server replies with a snapshot to just that client. - **Rate.** Cursor updates are throttled client-side and use the server's generous ephemeral bucket. **Caution:** Presence is browser-only and SSR-safe (components render nothing on the server). Cursors and reaction layers are `aria-hidden`, and motion respects `prefers-reduced-motion`. --- # Rate Limiter > Token-bucket rate limiting for Cloudflare Workers as a Durable Object, with zero runtime dependencies. `@delightstack/rate-limiter` is a token-bucket rate limiter implemented as a Durable Object. Pick a key (IP, user ID, API key), and the single-instance guarantee handles concurrency for you. Zero runtime dependencies — it only imports `cloudflare:workers`. ## Features - **Token bucket** — a bucket refills at a constant rate up to a max; requests consume tokens and are rejected when empty. - **Per-key buckets** — one DO instance manages many independent buckets (`login`, `api`, `upload`) so you can limit different actions separately. - **Native DO RPC** — `consume()`, `check()`, `getStatus()`, `setOptions()`, `reset()` called directly, no fetch handlers. - **Header-ready status** — `getStatus()` returns `remaining`, `limit`, and `reset_in_ms`. - **In-memory only** — state isn't persisted; limits reset if the DO is evicted (ideal for rate limiting — no storage latency, transient state is fine). ## Install ```bash pnpm add @delightstack/rate-limiter ``` `@delightstack/rate-limiter` exports a single entry: `RateLimiterServer`. ## 1. Re-export and bind the Durable Object ```typescript export { RateLimiterServer } from '@delightstack/rate-limiter'; ``` ```toml # wrangler.toml [[durable_objects.bindings]] name = "LIMITER" class_name = "RateLimiterServer" [[migrations]] tag = "v1" new_sqlite_classes = ["RateLimiterServer"] ``` ## 2. Use it Address one instance **per identity** with `idFromName()` — an IP for per-IP limiting, a user ID for per-user, or a fixed string for a global limit: ```typescript const id = env.LIMITER.idFromName(ip_address); const limiter = env.LIMITER.get(id); // configure the bucket for this key (once) await limiter.setOptions('api', { limit: 100, refill_per_second: 10 }); const allowed = await limiter.consume('api', 1); if (!allowed) { const status = await limiter.getStatus('api'); return new Response('Too Many Requests', { status: 429, headers: { 'X-RateLimit-Limit': String(status.limit), 'X-RateLimit-Remaining': String(status.remaining), 'Retry-After': String(Math.ceil(status.reset_in_ms / 1000)), }, }); } ``` **Note:** The same instance holds separate buckets per `key`, so one limiter can enforce different limits for `login`, `api`, and `upload` at once. See the [package README](https://github.com/brianschwabauer/delightstack/tree/main/packages/rate-limiter). --- # Billing (Stripe) > Stripe billing for Cloudflare Workers and SvelteKit — products, subscriptions, metered usage, webhooks, and subscription guards. `@delightstack/stripe` is Stripe billing for SvelteKit apps on Cloudflare Workers — define your plans and meters in code, sync them to Stripe, handle webhooks, and gate features by subscription. ## Features - **Config-driven plans & meters** — declare them once with `defineBillingConfig`; sync to Stripe. - **Subscriptions** — checkout, subscription state, and a webhook-driven sync into your database. - **Metered usage** — report usage events for usage-based pricing. - **Webhooks** — verified webhook handling with `handleWebhook`. - **Subscription guards** — gate SvelteKit routes by plan/entitlement. ## Install ```bash pnpm add @delightstack/stripe stripe ``` | Import | Use | | --- | --- | | `@delightstack/stripe/server` | `defineBillingConfig`, `createBillingHandle`, `syncSubscription`, `syncAll`, `reportMeterEvent`, `handleWebhook`, `getStripe` | | `@delightstack/stripe/sveltekit` | `createBillingGuards` | | `@delightstack/stripe/client` | reactive Svelte 5 billing client | ## 1. Define your billing config ```typescript import { defineBillingConfig } from '@delightstack/stripe/server'; export const billing = defineBillingConfig({ secret_key: env.STRIPE_SECRET_KEY, plans: [ { id: 'pro', name: 'Pro', price: 2000, interval: 'month', entitlements: ['premium'] }, ], meters: [ { id: 'ai-tokens', name: 'AI tokens', event_name: 'ai_tokens' }, ], }); ``` ## 2. Sync products & handle webhooks ```typescript // hooks.server.ts import { createBillingHandle } from '@delightstack/stripe/server'; export const billingHandle = createBillingHandle({ config: billing, getDb: (event) => event.platform.env.DB, }); ``` `syncAll()` pushes your plans/meters to Stripe; `handleWebhook()` verifies incoming events and `syncSubscription()` reconciles them into your database. ## 3. Gate routes ```typescript // +page.server.ts import { createBillingGuards } from '@delightstack/stripe/sveltekit'; const { requirePlan } = createBillingGuards(billing); export const load = (event) => { requirePlan(event, 'pro'); // redirect / 402 if not subscribed }; ``` ## 4. Report metered usage ```typescript import { reportMeterEvent } from '@delightstack/stripe/server'; await reportMeterEvent(billing, { meter: 'ai-tokens', value: 1200, customer }); ``` **Note:** Webhook secrets and the publishable key are set as worker secrets / vars (`STRIPE_SECRET_KEY`, `PUBLIC_STRIPE_PUBLISHABLE_KEY`). See the [package README](https://github.com/brianschwabauer/delightstack/tree/main/packages/stripe). --- # Realtime (WebSocket) > Room-scoped realtime for SvelteKit on Cloudflare — reactive presence, typed events, hibernation, and live database sync. `@delightstack/websocket` is a realtime layer for SvelteKit on Cloudflare Workers — room-scoped connections, reactive presence, typed custom events, and database sync, backed by one Durable Object per room with hibernation support. ## Features - **Room-scoped** — one Durable Object per room/org; connections in a room share an instance for broadcast and presence. - **Hibernation API** — the DO sleeps between messages and recovers session state on wake. - **SharedWorker multiplexing** — a single SharedWorker holds one WebSocket per room across all tabs. - **Reactive presence** — `ws.sessions` is a Svelte 5 `$state` array, always current. - **Typed events & metadata** — pass a custom event map and session-metadata type as generics. - **Auto-reconnect** — exponential backoff with jitter and client ping keep-alive. - **Database sync** — `ws.databaseHooks()` wires entity changes into `DatabaseClient`. ## Install ```bash pnpm add @delightstack/websocket ``` | Import | Use | | --- | --- | | `@delightstack/websocket/worker` | `WebsocketServer` — the Durable Object class | | `@delightstack/websocket/server` | `createWebsocketHandle` — SvelteKit upgrade handle | | `@delightstack/websocket/client` | `WebsocketClient` — reactive Svelte 5 client | ## 1. Register the Durable Object ```typescript import { WebsocketServer } from '@delightstack/websocket/worker'; export class AppWebsocketServer extends WebsocketServer { // optional: onConnect / onDisconnect / onMessage hooks } ``` Declare it in `wrangler.toml` (see [Architecture](/getting-started/architecture/)). ## 2. Wire the SvelteKit handle ```typescript // hooks.server.ts import { createWebsocketHandle } from '@delightstack/websocket/server'; export const websocketHandle = createWebsocketHandle({ getServer: (event) => event.platform.env.WS, // authorizes via @delightstack/auth locals by default }); ``` The handle intercepts `/api/websocket` upgrade requests, authorizes them, and forwards to the DO for the connecting room. ## 3. Connect from the client ```svelte

{ws.sessions.length} online

{#each ws.sessions as session} {session.meta?.user_name} {/each} ``` `ws.sessions` updates automatically from `session:list`, `session:connected`, and `session:disconnected` events. **Tip:** Combine with [Database](/packages/database/): pass `ws.databaseHooks()` to your `DatabaseClient` so entity changes broadcast to every connected client and keep local search indexes in sync. --- # Accessibility > Built-in accessibility features in DelightStack components and best practices for building inclusive interfaces. Accessibility is not an add-on in DelightStack — it is built into every component from the start. Components use semantic HTML, proper ARIA attributes, keyboard navigation, and focus management by default. ## Built-in Features ### Semantic HTML Components render appropriate semantic elements: - `Button` renders `` (not `

`) - `Input` uses `` with proper `type` attributes and linked `` elements - `Modal` and `Alert` use `

` - `List` renders `

` / `
` with `
1. ` items - `Tabs` uses `role="tablist"`, `role="tab"`, and `role="tabpanel"` - `Accordion` uses semantic `
   ` / `

   ` - `Breadcrumbs` renders a `

Small Normal (default) Large ``` Form controls (`Input`, `Select`, the form `Button` heights, and the smaller controls) use a `'0'`–`'3'` subset that also drives a shared **height** — see [Control sizing](#control-sizing). ## Control sizing Form controls share one **canonical height system** so a row of them lines up. The `size` prop picks a font from the `--control-font-*` scale, and the control's height is then `font × ratio`. The density modifiers (`dense` / `comfortable`) swap the ratio. One scale → a default row is the same height, and a dense row is the same height, with no per-component hardcoding. ```css :root { /* rem so controls scale with the root font-size; even-px fonts × 0.5-step ratios keep every size on a whole-pixel height */ --control-font-0: 0.875rem; /* 14px → 42px tall */ --control-font-1: 1rem; /* 16px → 48px tall (default) */ --control-font-2: 1.125rem; /* 18px → 54px tall */ --control-font-3: 1.25rem; /* 20px → 60px tall */ --control-height-ratio: 3; /* default → 48px @ size 1 */ --control-height-ratio-dense: 2.5; /* dense → 40px @ size 1 */ --control-height-ratio-comfortable: 3.5; /* comfortable → 56px @ size 1 */ --control-pad-x: 1em; /* inline padding */ --control-pad-x-dense: 0.75em; --control-pad-x-comfortable: 1.25em; } ``` `Input`, `Select` and `Button` (including standalone icon buttons) snap to these heights: | `size` | dense | default | comfortable | | ------ | ----- | -------- | ----------- | | 0 | 35px | 42px | 49px | | **1** | 40px | **48px** | 56px | | 2 | 45px | 54px | 63px | | 3 | 50px | 60px | 70px | So a row of controls at the same `size` (and density) is the same height: ```svelte

Go ``` The smaller controls (`Checkbox`, `Radio`, `Toggle`, `Range`, `Rating`) read the same `--control-font-*` scale so `size` means the same text scale everywhere; they keep their natural glyph height and **center** within a control-height row (`align-items: center`). **Note:** `Input` and `Select`'s floating label sits **outside** the component's layout box — it straddles the top border and overflows ~`0.4em` above it. The bordered box _is_ the control height, so controls top-align in a row; just leave the usual bit of vertical space above a labeled row (don't `overflow: hidden` a flush container). ## Breakpoints Used sparingly for page-level layout (components prefer container queries): ```css :root { --breakpoint-sm: 640px; --breakpoint-md: 768px; --breakpoint-lg: 1024px; --breakpoint-xl: 1280px; } ``` **Tip:** For a worked theming example, see the [Theming](/guides/theming/) guide. --- # Working with Forms > How to build validated forms with the Form component using Standard Schema validators like Zod, Valibot, and ArkType. DelightStack provides a `Form` component that handles validation, error display, and submission state management. It integrates with **Standard Schema** — a universal interface supported by Zod, Valibot, ArkType, and other validation libraries. ## Basic Form Setup Wrap your form fields in a `Form` component and pass a `schema` for validation: ```svelte

Create Account ``` ## How It Works The `Form` component creates a **form context** that child components (`Input`, `Select`, `Checkbox`, `Radio`, `Toggle`, `Range`, `Rating`) consume automatically. When a field has a `name` prop, it registers with the form context and: 1. **Reads its value** from `data[name]` 2. **Writes changes** back to `data[name]` 3. **Displays errors** from the validation result for that field 4. **Reports touched state** when the user interacts with it You do not need to wire up `bind:value` or error display manually — the form context handles it. **Tip:** Form fields still work independently outside of a `Form` component. The `name` prop only activates form context integration when a parent `Form` exists. ## Choosing a Validation Library The `Form` component accepts any validator that implements the [Standard Schema](https://github.com/standard-schema/standard-schema) interface. Here is the same validation written in three libraries: **Zod** ```typescript import { z } from 'zod'; const schema = z.object({ name: z.string().min(2, 'Name is required'), email: z.string().email('Invalid email'), age: z.number().min(18, 'Must be 18 or older'), }); ``` **Valibot** ```typescript import * as v from 'valibot'; const schema = v.object({ name: v.pipe(v.string(), v.minLength(2, 'Name is required')), email: v.pipe(v.string(), v.email('Invalid email')), age: v.pipe(v.number(), v.minValue(18, 'Must be 18 or older')), }); ``` **ArkType** ```typescript import { type } from 'arktype'; const schema = type({ name: 'string>=2', email: 'string.email', age: 'number>=18', }); ``` All three produce identical behavior when passed to the `Form` component's `schema` prop. ## Entity-Backed Forms (Database Tables) If you define your data with `Database.table()` from `@delightstack/database`, the entire form — values, validation, submission, and saving state — wires itself up from the entity: ```svelte

goto('/people')}> Save ``` No `bind:value`, no schema, no submit handler, no saving state: - **Values** flow through the form context — each field reads and writes `person.value` directly (a field with a `name` and no explicit `value` becomes *context-driven*). - **Validation** runs per field via the `parse` validator included in each spread, on blur and on submit. Only the fields actually rendered are validated, so partial forms just work. - **Submission**: submit validates, normalizes each field through its `parse` (so `''` becomes `undefined` and schema transforms apply), then calls `person.save()` — which creates when the entity has no id and updates otherwise. `onsaved` fires on success. - **State**: the form derives `is_dirty` from `person.has_changes`, its submitting state from `person.saving` (submit `Button`s auto-disable and spin), and reset restores the last server values via `person.reset()`. The `entity` prop is structural — any object with `value` and `save()` works (see `FormEntity` in the [Form docs](/components/form/form/)), so you can hand it a custom store too. Every table also exposes the pieces individually when you want manual control: - **`table.form.field.`** (also on `entity.form.field`) — props to spread onto a field component: `name`, `type`, `label`, `placeholder`, `description`, `required`, `readonly`, length/value constraints, enum `options`, array `multiple`, and a `parse` validator. - **`table.form.schema`** — a Standard Schema validator covering all of the table's editable fields, for the `Form` component's `schema` prop (it resolves dot-notation field names against nested data, so it validates both flat form records and entity values). With the table defined as: ```typescript export const personTable = Database.table('person', (s) => ({ id: s.primaryKey(), name: s.string().min(1).max(100).label('Full name'), email: s.string().email().optional(), relationship: s.enum(['parent', 'child', 'friend']).optional(), })); ``` `field.email` spreads as `{ name: 'email', type: 'email', label: 'Email', parse }` — the input type, label, validation, and value binding all come from the one schema definition. ### How field props are derived | Schema builder | Effect on the spread props | | ------------------------------- | ------------------------------------------------------------------------------------------------- | | `s.string().email()` | `type="email"` (likewise `.url()`, `.date()`, `.datetime()`, `.time()`, `.color()`, `.password()`, `.phone()`) | | `s.string().textarea()` | `type="textarea"` | | `.label('...')` | `label` — auto-derived from the field name when omitted (`first_name` → "First name") | | `.placeholder('...')` | `placeholder` | | `.description('...')` | `description` text below the input | | `.optional()` / `.default(...)` | the field is not `required` (fields inside an optional object are also not required) | | `.readonly()` | `readonly` | | `.min()` / `.max()` | `minlength`/`maxlength` on strings, `min`/`max` on numbers | | `s.enum([...])` | `options` as `{ value, label }[]`, ready for `Select` — pass `{ value, label }` pairs to `s.enum()` for custom labels | | `s.array(...)` | `multiple` (chips mode on `Input`, multi-select on `Select`) | | `s.boolean()` | `type: 'boolean'` — spread onto `Checkbox` or `Toggle` (not `Input`) | | `s.boolean().optional()` | `tristate: true` — `null`/`undefined` mean "unanswered" and display as indeterminate | | `s.boolean().default(...)` | `default_checked` — an empty draft displays (and saves) the default | Primary keys, foreign keys, and derived fields are excluded from `form.field` and `form.schema` — they are not user-editable. ### Tri-state booleans An optional boolean with no default is genuinely **tri-state**: `true` / `false` / `NULL`-meaning-unanswered (optional fields are stored as `NULL` in SQLite). The form layer surfaces that: - On `Checkbox`, an unanswered value displays as **indeterminate**; clicking resolves it to checked (matching the browser's native indeterminate-checkbox behavior). The user can't click back to "unanswered". - On `Toggle`, the spread enables the **three-stop track** — the unanswered value is the middle stop, and the user *can* cycle or drag back to it (writing `null`). Use Toggle when "no answer" must be re-enterable. Defaulted booleans (`.default(true)`) are not tri-state: an empty draft displays the default, and submitting fills the default into the saved data — so what the user sees always matches what gets stored. **Tip:** Every `parse` function returns the parsed value and throws an error whose `message` is safe to show to the user (e.g. `"Full name is required"`, `"Invalid email address"`) — never a raw validation dump. ## Field Validation Without a Form Sometimes a whole `Form` is more than you need — a single setting input, an inline rename field. The `Input` component accepts a `parse` prop (the same function included in every `table.form.field` spread): ```svelte ``` Standalone, the input runs `parse` when it loses focus and shows the thrown error's message below the field. While the field is errored it re-validates on every keystroke, so the message clears the moment the value is fixed — without nagging the user before they finish typing. ## How Form and Field Validation Work Together Validation can live in two places, and they are designed not to conflict: 1. **Form-level schema** — the `Form` component's `schema` prop validates the whole `data` object. 2. **Field-level `parse`** — validates a single field's value. Inside a `Form`, an `Input` never runs `parse` itself. It registers the function with the form, and the form runs all field validators together with the form schema on its `validate_on` timing. The merge rule is simple: - If **both** produce an error for the same field, the **form schema's message wins**. - Fields the form schema does not cover keep their field-level error. - One error per field is ever shown. When the form schema is `table.form.schema`, the two layers are literally the same validation functions, so they always agree. ## Validation Modes The `validate_on` prop controls when fields are validated: | Mode | Behavior | | ---------- | ------------------------------------------------------------------- | | `'change'` | Validate immediately as the user types or changes a value | | `'blur'` | Validate when the user leaves the field (default) | | `'submit'` | Only validate when the form is submitted | ```svelte

...

...

``` **Note:** The `'blur'` mode is the default and works well for most forms. It provides feedback after the user finishes a field without being intrusive during typing. ## Error Display When validation fails, each field automatically displays its error message below the input. The error is associated via `aria-describedby` for screen reader accessibility. Errors are only shown for fields that have been **touched** (interacted with by the user), so a freshly loaded form does not show a wall of errors. On submit, all fields are marked as touched and all errors become visible. ## Form Context The `Form` component provides a context object that child components read. You can also access it programmatically in your own components: ```typescript import type { FormContext } from '@delightstack/components'; ``` The context provides: | Property | Type | Description | | --------------- | ---------------------------- | ---------------------------------------- | | `data` | `Record` | Current form data | | `errors` | `Record` | Validation errors by field name | | `touched` | `Record` | Which fields have been interacted with | | `is_dirty` | `boolean` | Whether any field has changed | | `is_submitting` | `boolean` | Whether submission is in progress | | `is_valid` | `boolean` | Whether all fields pass validation | | `disabled` | `boolean` | Whether the form is disabled | | `validate_on` | `'change' \| 'blur' \| 'submit'` | Current validation mode | And these methods: | Method | Description | | ---------------- | ------------------------------------- | | `setValue(name, value)` | Update a field's value | | `setTouched(name)` | Mark a field as touched | | `validateField(name)` | Validate a single field | | `register(name, el, validator?)` | Register a field element and optional field-level validator | | `unregister(name)` | Unregister a field | ## Form Props | Prop | Type | Default | Description | | ----------------- | ----------------------- | ------- | ------------------------------------------------ | | `data` | `Record` | `{}` | Form data object (bindable) | | `schema` | `StandardSchema` | — | Standard Schema validator | | `validate_on` | `'change' \| 'blur' \| 'submit'` | `'blur'` | When to validate fields | | `disabled` | `boolean` | `false` | Disable the entire form | | `reset_on_submit` | `boolean` | `false` | Reset to initial values after successful submit | | `dense` | `boolean` | `false` | Compact spacing between fields | | `comfortable` | `boolean` | `false` | Relaxed spacing between fields | ## Form Events | Event | Detail | Description | | ---------- | ----------------------------------- | ----------------------------------- | | `onsubmit` | `{ data, is_valid }` | Called on form submission | | `onchange` | `{ data, errors }` | Called when form data changes | | `onerror` | `{ errors }` | Called when validation fails on submit | ## Complete Example Here is a registration form with multiple field types, validation, and user feedback: ```svelte

Skill level

Reset Create Account

``` **Tip:** The `reset_on_submit` prop resets the form data back to its initial values after a successful submission. The `onsubmit` callback supports returning a Promise — the form automatically sets `is_submitting` to `true` while it resolves, disabling the submit button. ## Using Fields Without a Form Every form component works independently when used without a parent `Form`: ```svelte ``` In this case, you manage state with `bind:value` and handle validation yourself. --- # Scrolling > How DelightStack styles scrollbars — the token-driven native baseline, the overlay scrollbar attachment, and the touch-device policy. Scrollbars are part of the design system. DelightStack replaces the browser's default chrome with a two-layer system so every scrollbar — from the document itself down to a dropdown menu — shares the same thin, token-driven look: 1. **A styled-native baseline (pure CSS).** Every scrollbar gets a thin, pill-shaped, theme-aware thumb on a transparent track. This covers the document scrollbar and any scroller that isn't individually enhanced, and it works with JavaScript disabled. 2. **An overlay scrollbar (the `scrollbar` attachment).** Component scroll areas (Table, Modal, Popover, Code, CommandPalette, …) upgrade to a custom overlay bar that takes **zero layout space**, fades in while you scroll or hover and back out when idle, stays clear of rounded corners, and supports thumb dragging and click-to-jump like a native bar. Native scrolling is never reimplemented — wheel, keyboard, touch, momentum, and accessibility behavior all stay with the browser. Only the visuals change. ## The baseline Importing the global stylesheet applies the baseline everywhere: ```ts import '@delightstack/styles'; // global.css, includes scrollbar.css ``` If you only want tokens plus scrollbars (the docs site does this so Starlight keeps its own base styles): ```css @import '@delightstack/styles/tokens.css'; @import '@delightstack/styles/scrollbar.css'; ``` Under the hood the baseline uses `::-webkit-scrollbar` pseudo-elements in Chromium/Safari and falls back to the standard `scrollbar-width: thin` + `scrollbar-color` properties in Firefox. **Caution:** In Chromium, setting `scrollbar-width` or `scrollbar-color` on an element **disables** all `::-webkit-scrollbar` styling for it — the browser switches that element to the simpler standard rendering. Don't sprinkle those properties in app CSS; set the `--scrollbar-*` tokens instead. ### Tokens | Token | Default | Role | | -------------------------------- | ---------------------- | ---------------------------------------------------------- | | `--scrollbar-size` | `10px` | Full gutter thickness (track width) | | `--scrollbar-inset` | `2px` | Gap between the thumb and the container edge | | `--scrollbar-thumb-color` | 35% text over transparent | Resting thumb color (adapts to light/dark automatically) | | `--scrollbar-thumb-color-active` | 60% text over transparent | Thumb color while hovered/dragged | | `--scrollbar-track-inset` | `0px` | Per-container: keeps the native thumb out of rounded corners | ### Rounded containers A scrollbar that runs into a rounded corner looks broken — the thumb pokes past the curve. For containers that keep the *native* (baseline) scrollbar, set `--scrollbar-track-inset` to the container's border radius and the track is shortened at both ends: ```css .my-rounded-scroller { border-radius: var(--radius-xl); /* Half the radius is enough — the thumb hugs the edge, where the curve has already receded */ --scrollbar-track-inset: calc(var(--radius-xl) / 2); } ``` The overlay attachment below handles this automatically. ## The overlay scrollbar The `scrollbar` attachment is exported from `@delightstack/components`: ```svelte

``` What it does: - Hides the element's native scrollbars and overlays a floating thumb that takes **no layout space** (no more shifting content on Windows). - **Autohides**: fades in on scroll or pointer movement, fades out ~1s after activity stops. The fade-in is instant and the fade-out eased, matching the design system's "snap in, ease out" motion rule. - **Respects rounded corners**: it reads the element's `border-radius` (inheriting the parent's radius when the scroller sits flush inside a rounded card, like a modal body) and insets the track ends by **half the radius** — enough to clear the curve at the edge the thumb hugs, without shortening the track more than necessary. No configuration needed. - Full pointer support: drag the thumb, click the track to jump, scroll the wheel over the bar. The thumb thickens while hovered, like a native overlay bar. - Handles both axes, RTL layouts, and content/container resizes (via `ResizeObserver` + `MutationObserver`). - Honors `prefers-reduced-motion`. ### Options ```ts scrollbar({ /** Fade out when idle (default true) */ autohide: true, /** ms after the last activity before fading (default 1000) */ autohide_delay: 1000, /** Override the automatic corner inset, in px */ corner_inset: 10, /** Per-edge overrides (px); a function is re-evaluated on every layout. Table uses this to pin the track top to its sticky header. */ track_insets: (el) => ({ top: el.querySelector('thead')?.offsetHeight }), }); ``` **Tip:** Scroll containers inside overlays (modals, popovers, dropdowns, palettes) should also set `overscroll-behavior: contain` so reaching the end of the list doesn't start scrolling the page behind it. All DelightStack overlay components ship with this. ### Requirements & caveats - The element's **parent** is used as the positioning context for the overlay (it's given `position: relative` if static), so apply the attachment to a scroller that lives inside its visual frame — not to an element whose parent is shared with unrelated absolutely-positioned UI. - Elements in the **top layer** (`popover`, anchored `position: fixed` panels) can't host a sibling overlay. Those keep the styled-native baseline — that's why Select/Input dropdown menus use `--scrollbar-track-inset` instead. - Chrome's find-in-page tick marks aren't shown inside enhanced scrollers (the native bar is hidden). - The **document scrollbar** intentionally stays native-styled: it sits at the viewport edge (no radius to avoid), macOS already overlays it, and it keeps working before JavaScript loads. ## Touch devices On touch-only devices (`hover: none` / `pointer: coarse`) **both layers stand down**: the baseline media query doesn't match and the attachment is a no-op. Mobile browsers already use transient overlay indicators that auto-hide and take no space — they're also the user's only scroll-position feedback, so DelightStack leaves them alone. ## Components that use the overlay Table, Modal, Popover, CommandPalette, Code, Calendar (time slots), Timeline (horizontal), SplitPane, BottomSheet, and PDF all ship with the overlay scrollbar wired in. Select, Input autocomplete, and Table cell-editor dropdowns use the corner-inset native baseline (they're anchored top-layer panels). --- # Theming > Customize the look and feel of DelightStack by overriding CSS custom properties. DelightStack's entire visual system is controlled by CSS custom properties. To create a custom theme, you override these tokens in your global CSS — no build step, no JavaScript, no configuration files. ## How Theming Works Every component reads its colors, spacing, typography, and other visual properties from CSS custom properties defined on `:root`. When you change a token, every component that uses it updates automatically. ```css /* Your global CSS — override any token */ :root { --color-action: light-dark(#059669, #34d399); --radius-md: 0.75rem; } ``` That is all it takes. Every Button, Input, Select, and other interactive component now uses your green action color and slightly rounder corners. ## Creating a Custom Theme Here is a complete example of a brand-colored theme. You only need to override the tokens you want to change — everything else falls back to the defaults. ### Example: Emerald Brand Theme ```css :root { color-scheme: light dark; /* Brand colors */ --color-action: light-dark(#059669, #34d399); --color-action-active: oklch(from var(--color-action) calc(l - 0.1) c h); --color-action-text: oklch(from var(--color-action) 0.92 calc(c * 0.15) h); --color-action-text-active: white; --color-accent: light-dark(#0891b2, #22d3ee); --color-accent-active: oklch(from var(--color-accent) calc(l - 0.1) c h); --color-accent-text: oklch(from var(--color-accent) 0.92 calc(c * 0.15) h); --color-accent-text-active: white; /* Warmer backgrounds */ --color-bg: light-dark(#fafaf9, #0c0a09); --color-bg-muted: light-dark(#f5f5f4, #1c1917); /* Rounder corners */ --radius-md: 0.625rem; --radius-lg: 1rem; /* Custom font */ --font-sans: 'Inter', ui-sans-serif, system-ui, sans-serif; } ``` ### Example: Rose Brand Theme ```css :root { color-scheme: light dark; --color-action: light-dark(#e11d48, #fb7185); --color-action-active: oklch(from var(--color-action) calc(l - 0.1) c h); --color-action-text: oklch(from var(--color-action) 0.92 calc(c * 0.15) h); --color-action-text-active: white; --color-accent: light-dark(#7c3aed, #a78bfa); --color-accent-active: oklch(from var(--color-accent) calc(l - 0.1) c h); --color-accent-text: oklch(from var(--color-accent) 0.92 calc(c * 0.15) h); --color-accent-text-active: white; /* Sharper corners for a crisp look */ --radius-sm: 0.125rem; --radius-md: 0.25rem; --radius-lg: 0.375rem; } ``` ## Overriding Derived Colors The action and accent colors use the `oklch(from ...)` relative color syntax to automatically derive hover, active, and text states. When you change the base color, the derived states update automatically: ```css :root { /* Just change the base — everything else follows */ --color-action: light-dark(#7c3aed, #a78bfa); } ``` If you want full control over the derived states, override them explicitly: ```css :root { --color-action: #7c3aed; --color-action-active: #5b21b6; /* Custom active */ --color-action-text: #f5f3ff; /* Custom text on action bg */ --color-action-text-active: white; } ``` ## Per-Component Overrides CSS custom properties cascade, so you can scope overrides to specific parts of your page: ### Scoped to a Container ```css .sidebar { --color-action: light-dark(#7c3aed, #a78bfa); --color-action-active: oklch(from var(--color-action) calc(l - 0.1) c h); --color-action-text: oklch(from var(--color-action) 0.92 calc(c * 0.15) h); --color-action-text-active: white; } ``` ```svelte

Sidebar Action

Main Action ``` ### Scoped with Inline Styles For one-off overrides, use inline `style` attributes: ```svelte Delete ``` ## Customizing Specific Token Groups ### Typography ```css :root { /* Use a custom font */ --font-sans: 'Plus Jakarta Sans', ui-sans-serif, system-ui, sans-serif; --font-mono: 'JetBrains Mono', ui-monospace, monospace; /* Adjust the type scale */ --text-base: 0.9375rem; /* 15px instead of 16px */ --text-lg: 1.0625rem; } ``` ### Border Radius ```css :root { /* Sharp, minimal look */ --radius-sm: 2px; --radius-md: 4px; --radius-lg: 6px; --radius-xl: 8px; --radius-2xl: 12px; } ``` ```css :root { /* Fully rounded, playful look */ --radius-sm: 0.5rem; --radius-md: 0.75rem; --radius-lg: 1rem; --radius-xl: 1.5rem; --radius-2xl: 2rem; } ``` ### Shadows ```css :root { /* Softer, more diffused shadows */ --shadow-md: light-dark( 0 4px 12px -2px rgb(0 0 0 / 0.06), inset 0 1px 0 0 rgb(255 255 255 / 0.06) ); } ``` ### Transitions ```css :root { /* Snappier animations */ --duration-fast: 75ms; --duration-normal: 150ms; --duration-slow: 200ms; /* Or slower, more deliberate */ --duration-fast: 150ms; --duration-normal: 300ms; --duration-slow: 500ms; } ``` ## Theme Switching To support runtime theme switching (beyond light/dark), use a CSS class on `:root` or ``: ```css :root.theme-ocean { --color-action: light-dark(#0284c7, #38bdf8); --color-accent: light-dark(#0891b2, #22d3ee); --color-bg: light-dark(#f0f9ff, #0c0a09); } :root.theme-forest { --color-action: light-dark(#059669, #34d399); --color-accent: light-dark(#65a30d, #a3e635); --color-bg: light-dark(#f0fdf4, #052e16); } ``` ```svelte setTheme('ocean')}>Ocean setTheme('forest')}>Forest ``` **Tip:** For light/dark mode switching specifically, use the built-in `ThemeToggle` component and the `color-scheme` property. See the [Dark Mode](/guides/dark-mode/) guide for details. --- # Alert > A streamlined confirmation dialog built on Modal, providing consistent yes/no decision flows with a programmatic API. ## Import ```svelte import { Alert } from '@delightstack/components'; ``` For the programmatic API: ```typescript import { alert } from '@delightstack/components'; ``` ## Basic Usage ```svelte showAlert = true}>Confirm Action showDestructive = true}>Delete Item ``` ## Examples ### With Icon Display an icon component above the title for visual emphasis. ```svelte showWarning = true}>Show Warning ``` ### Programmatic API Create an alert dialog imperatively using the `alert()` function. It returns a `Promise` that resolves to `true` (confirmed) or `false` (cancelled). ```svelte Delete Item ``` ### Promise-Aware Confirm When `oncontinue` returns a `Promise`, the confirm button automatically enters loading state until the promise resolves. ```svelte showAlert = true}>Process Data ``` ## Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `open` | `boolean` | `false` | Controls visibility (`$bindable()`) | | `title` | `string` | `'Confirm'` | Alert title | | `message` | `string` | `''` | Alert message / question | | `cancel_text` | `string` | `'Cancel'` | Cancel button label | | `continue_text` | `string` | `'Continue'` | Confirm button label | | `destructive` | `boolean` | `false` | Style confirm button with `error` color | | `icon` | `Component` | `undefined` | Optional icon component displayed above the title | | `id` | `string` | auto-generated | Element ID | | `class` | `string` | `''` | Additional CSS classes | | `oncancel` | `() => void` | `undefined` | Called when Cancel is clicked | | `oncontinue` | `() => void \| Promise` | `undefined` | Called when Confirm is clicked; promise-aware (button shows loading until resolved) | ## Events | Event | Detail | Description | |-------|--------|-------------| | `oncancel` | none | Fires when the user cancels (Cancel button, backdrop click, or Escape key) | | `oncontinue` | none | Fires when the user confirms. If it returns a `Promise`, the button shows a loading state. | ## Types The component exports the `AlertOptions` interface for the programmatic API and the `alert` function: ```typescript interface AlertOptions { title?: string; message: string; cancel_text?: string; continue_text?: string; destructive?: boolean; icon?: Component; } function alert(options: AlertOptions): Promise; ``` ## Accessibility - Inherits all Modal accessibility features (`role="dialog"`, `aria-modal`, focus trap) - Keyboard navigable: Tab between Confirm and Cancel buttons - Escape key and backdrop click trigger the cancel action - When `destructive` is true, the `icon` section is styled with the error color --- # Button > A versatile, polished button with ripple effects, promise-aware loading states, dropdown menus, and confirmation flows. ## Import ```svelte import { Button } from '@delightstack/components'; ``` ## Basic Usage ```svelte console.log('clicked')}> Click Me ``` ## Examples ### Variants Combine variant booleans freely. The default appearance (solid action-colored) requires no variant props. ```svelte Solid (default) Outline Transparent Translucent ``` ### Color Schemes Apply semantic color schemes with the `accent`, `error`, or `success` props. These combine with any variant. ```svelte Accent Error Success Transparent Error Outline Accent Translucent Success ``` ### Sizes The `size` prop controls font size, which drives padding and dimensions via `em` units. ```svelte Extra Small Small Default Large Extra Large ``` ### Pill, Dense & Comfortable `dense` and `comfortable` adjust the height and padding using the shared control sizing tokens, so a Button lines up with `dense`/`comfortable` Input and Select fields in the same form row. ```svelte Dense Default Comfortable Pill Button Pill Dense ``` ### Icon Buttons Set `icon` for circular icon-only buttons. Combine with any variant or badge. ```svelte ``` ### Disabled & Loading Set `loading` to show a spinner whenever you drive the busy state yourself. ```svelte Disabled Loading ``` ### Icon Button Loading Icon buttons support the same loading feedback: the spinner (and the success checkmark) overlays the button while the icon scales away beneath it, and inherits the variant's text color. Works with the `loading` prop or a promise-returning `onclick` — try the first button. ```svelte ``` ### Promise-Aware Click Handler When `onclick` returns a `Promise`, the button manages its own loading feedback — no `loading` prop required: - **Instant actions don't flash.** The spinner only appears if the promise is still pending after ~100ms; anything faster is treated as instant. - **The spinner can't blink.** Once shown, it stays for at least ~1s, then eases out quickly. - **Success is confirmed automatically.** On resolve, a brief checkmark flashes; on reject, no checkmark is shown. Try each button below: the first shows the spinner then a checkmark, the second resolves too fast to ever show a spinner, and the third shows a spinner but no checkmark because it rejects. ```svelte Save ``` ### Manual Success Checkmark When you drive `loading` yourself (e.g. from a store or form), set `loading_success` to flash the same confirming checkmark as `loading` returns to `false`. Leave it off and the spinner simply disappears. ```svelte Save ``` ### Badge Display a notification indicator. Pass `true` for a dot or a string for a count. ```svelte Notifications Messages ``` ### Link Button When `href` is set, the button renders as an `` element. ```svelte Visit Site ``` ### Dropdown Menu Pass a `menu` snippet to render a popover dropdown when the button is clicked. ```svelte Options {#snippet menu({ close })} { edit(); close(); }}>Edit { remove(); close(); }}>Remove {/snippet} ``` ### Split Button with Dropdown Use the `dropdown` snippet for a secondary dropdown trigger alongside the main button action. ```svelte Save {#snippet dropdown({ close })} { saveAs(); close(); }}>Save As... { saveCopy(); close(); }}>Save Copy {/snippet} ``` ## Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `size` | `'0000' \| '000' \| '00' \| '0' \| '1' \| '2' \| '3' \| '4' \| '5' \| '6'` | `undefined` | Font size tier, driving all dimensions via `em` units | | `icon` | `boolean` | `false` | Render as a circular icon-only button | | `pill` | `boolean` | `false` | Fully rounded corners | | `transparent` | `boolean` | `false` | No background or border (ghost style) | | `translucent` | `boolean` | `false` | Semi-transparent tinted background with backdrop blur | | `outline` | `boolean` | `false` | Transparent background with visible border | | `grouped` | `boolean` | `false` | Indicates the button is part of a group (border radius adjusted) | | `error` | `boolean` | `false` | Red/destructive color scheme | | `success` | `boolean` | `false` | Green/success color scheme | | `accent` | `boolean` | `false` | Accent/brand color scheme | | `overlay` | `boolean` | `false` | Dark overlay style with backdrop blur | | `dense` | `boolean` | `false` | Reduced padding/height for compact layouts | | `comfortable` | `boolean` | `false` | Increased padding/height for roomy layouts | | `full_width` | `boolean` | `false` | Stretch to container width | | `full_height` | `boolean` | `false` | Stretch to container height | | `disable_ripple` | `boolean` | `false` | Disable the ripple click effect | | `href` | `string` | `undefined` | Renders as `` instead of `` | | `target` | `'_self' \| '_blank' \| '_parent' \| '_top'` | `undefined` | Link target attribute (when `href` is set) | | `tooltip` | `string` | `''` | Hover tooltip text | | `disabled` | `boolean` | `false` | Disable interaction | | `active` | `boolean` | `false` | Visually pressed/selected state (useful in toggle groups) | | `loading` | `boolean` | `undefined` | Show the loading spinner manually. Leave unset to let a promise-returning `onclick` drive it | | `loading_success` | `boolean` | `false` | For the manual `loading` path: flash a success checkmark when `loading` goes `true` → `false`. The promise path shows it automatically on resolve | | `badge` | `string \| boolean` | `undefined` | Badge indicator; `true` renders a dot, a string renders the text | | `menu` | `Snippet<[{ close: () => void }]>` | `undefined` | Popover dropdown content triggered by clicking the button | | `show_chevron` | `boolean` | `false` | Show a chevron icon (useful with `menu`) | | `dropdown` | `Snippet<[{ close: () => void }]>` | `undefined` | Content for a secondary dropdown trigger | | `disable_dropdown` | `boolean` | `false` | Disable and hide the secondary dropdown trigger | | `popover_close_on_inside_click` | `boolean` | `false` | Close the popover when clicking inside it | | `popover_placement` | `Placement` | `'bottom-end'` | Floating UI placement for the popover | | `popover_strategy` | `Strategy` | `'fixed'` | CSS positioning strategy for the popover | | `popover_disable_initial_focus` | `boolean` | `false` | Skip auto-focusing content when the popover opens | | `children` | `Snippet<[{ isLoading: boolean; isLoadingSuccess: boolean }]>` | `undefined` | Button label content (receives loading state) | | `id` | `string` | auto-generated | Element ID | | `class` | `string` | `''` | Additional CSS classes | | `style` | `string` | `''` | Inline CSS styles | | `onclick` | `(e: MouseEvent) => void \| Promise` | `undefined` | Click handler; returning a Promise enables automatic loading state | ## Accessibility - Full keyboard activation via Space and Enter keys - Clear focus ring using inset box-shadow - `aria-haspopup` and `aria-expanded` set automatically when a `menu` snippet is provided - Disabled state communicated via the `disabled` attribute - Loading state disables pointer events and sets `tabindex="-1"` - Ripple effect respects `prefers-reduced-motion` --- # ButtonGroup > A container that groups related buttons with shared borders, coordinated styling, and context-driven prop inheritance. ## Import ```svelte import { ButtonGroup, Button } from '@delightstack/components'; ``` ## Basic Usage ```svelte Save Save As Discard ``` ## Examples ### Toggle Group (Single Selection) Use the `active` prop on child Buttons to create a toggle group. Icon buttons rarely speak for themselves, so pass a `tooltip` to each one. Hover a button and its tooltip appears after a short delay — then slide across to the next button and its tooltip shows **instantly**, no waiting. The skip-delay window is shared by every tooltip on the page and persists briefly after you leave, so the buttons don't even need to touch. ```svelte viewMode = 'grid'} icon tooltip="Grid view" aria-label="Grid view"> viewMode = 'list'} icon tooltip="List view" aria-label="List view"> ``` ### Variant Inheritance Set variant props on the group to apply them to all children at once. ```svelte First Second Third ``` ### Vertical Orientation Stack buttons vertically instead of horizontally. ```svelte Option 1 Option 2 Option 3 ``` ### Split Button with Dropdown Combine a primary action button with a dropdown trigger inside a group. ```svelte Save {#snippet menu({ close })} { saveAs(); close(); }}>Save As... { saveCopy(); close(); }}>Save Copy {/snippet} ``` ### Detached (Non-Attached) Mode Set `attached={false}` to add a small gap between buttons instead of merging borders. ```svelte One Two Three ``` ## Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `size` | `'0000' \| '000' \| '00' \| '0' \| '1' \| '2' \| '3' \| '4' \| '5' \| '6'` | `undefined` | Size applied to all child Buttons via context | | `outline` | `boolean` | `false` | Apply outline variant to all children | | `transparent` | `boolean` | `false` | Apply transparent variant to all children | | `translucent` | `boolean` | `false` | Apply translucent variant to all children | | `accent` | `boolean` | `false` | Apply accent color to all children | | `error` | `boolean` | `false` | Apply error color to all children | | `success` | `boolean` | `false` | Apply success color to all children | | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction | | `disabled` | `boolean` | `false` | Disable all child Buttons via context | | `attached` | `boolean` | `true` | Visually connect buttons (shared borders, merged radii) | | `id` | `string` | auto-generated | Element ID | | `class` | `string` | `''` | Additional CSS classes | | `children` | `Snippet` | `undefined` | Child Button components | ## Types The ButtonGroup exports a `ButtonGroupContext` interface used for its context contract with child Buttons: ```typescript interface ButtonGroupContext { size: | undefined | '0000' | '000' | '00' | '0' | '1' | '2' | '3' | '4' | '5' | '6'; outline: boolean; transparent: boolean; translucent: boolean; accent: boolean; error: boolean; success: boolean; disabled: boolean; } ``` Child Buttons read this context via `getContext('button-group')` and merge the group values with their own props (own props take precedence when explicitly set). ## Accessibility - `role="group"` on the container element - Provide an `aria-label` to describe the group's purpose - Buttons remain individually focusable - Hovered and focused buttons are raised above siblings via `z-index` for clean border visibility --- # CommandPalette > A keyboard-driven command interface with fuzzy search, recent commands tracking, category grouping, and match highlighting. ## Import ```svelte import { CommandPalette } from '@delightstack/components'; ``` ## Basic Usage ```svelte open = true}>Open Command Palette ``` ```svelte ``` The palette automatically registers a global `Ctrl/Cmd + K` keyboard shortcut to toggle visibility. ## Examples ### Full Command Setup ```svelte ``` ### Compact / Dense Mode Use `dense` for tighter spacing in smaller interfaces. ```svelte ``` ### Roomy / Comfortable Mode Use `comfortable` for more generous spacing and larger tap targets — handy on touch interfaces or when the palette is the primary surface. ```svelte ``` ### Without Category Grouping Disable grouping to show a flat list of results. ```svelte ``` ### With Selection Callback Track when any command is selected using the `onselect` prop. ```svelte { analytics.track('command_used', { id: command.id }); }} /> ``` ### Promise-Aware Commands When a command's `onselect` returns a `Promise`, a spinner appears while executing. On success, the palette closes. On failure, it stays open. ```svelte const commands = [ { id: 'sync', title: 'Sync Data', description: 'Synchronize with the server', onselect: async () => { await api.syncAll(); } } ]; ``` ### Custom Placeholder ```svelte ``` ## Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `open` | `boolean` | `false` | Controls visibility (`$bindable()`) | | `commands` | `CommandOption[]` | `[]` | Available commands to search | | `placeholder` | `string` | `'Type a command or search...'` | Input placeholder text | | `recent_limit` | `number` | `5` | Number of recent items to show when input is empty | | `group_by` | `'category' \| 'none'` | `'category'` | How to group results | | `dense` | `boolean` | `false` | Compact result item spacing | | `comfortable` | `boolean` | `false` | Roomy result item spacing | | `onselect` | `(command: CommandOption) => void` | `undefined` | Called when any command is selected | | `id` | `string` | auto-generated | Element ID | | `class` | `string` | `''` | Additional CSS classes | ## Events | Event | Detail | Description | |-------|--------|-------------| | `onselect` | `CommandOption` | Fires when a command is selected, before executing `command.onselect` | ## Types ```typescript interface CommandOption { /** Unique identifier for the command */ id: string; /** Display title of the command */ title: string; /** Optional description shown below the title */ description?: string; /** Category for grouping commands */ category?: string; /** Optional icon component */ icon?: Component; /** Keyboard shortcut keys to display (e.g. ['Ctrl', 'K']) */ shortcut?: string[]; /** Additional search keywords */ keywords?: string[]; /** Whether the command is disabled */ disabled?: boolean; /** Called when the command is selected */ onselect: () => void | Promise; } ``` ## Keyboard Navigation | Key | Action | |-----|--------| | `Ctrl/Cmd + K` | Toggle open (global shortcut) | | `Arrow Up` / `Arrow Down` | Navigate results | | `Enter` | Execute selected command | | `Escape` | Close palette | ## Fuzzy Search The palette uses a built-in fuzzy search engine that scores matches across `title`, `description`, `category`, and `keywords` fields. Matching characters in the title are highlighted in the results. Scoring priority: exact match > starts with > word boundary match > contains > fuzzy character match. Title matches are weighted highest, followed by keywords, description, and category. ## Recent Commands Recently used commands are tracked in memory and shown when the input is empty. The list is sorted by recency and limited by the `recent_limit` prop. ## Accessibility - ARIA combobox pattern (`role="combobox"` on input, `role="listbox"` on results) - `aria-activedescendant` tracks the highlighted result - `aria-expanded` reflects whether results are visible - `aria-autocomplete="list"` on the input - `role="option"` with `aria-selected` and `aria-disabled` on each result item - Focus trap keeps focus within the palette while open - Input is always focused while the palette is open --- # ContextMenu > A right-click context menu system using the {@attach contextMenu()} Svelte attachment API with Popover-based positioning and List rendering. ## Import ```svelte import { contextMenu } from '@delightstack/components'; ``` Also import the `ContextMenu` component itself (typically in your root layout) to mount the global context menu renderer: ```svelte import { ContextMenu } from '@delightstack/components'; ``` ## Basic Usage Attach a context menu to any element using `{@attach contextMenu()}`. The `ContextMenu` component must be mounted somewhere in your component tree (usually in your root layout). ```svelte

editItem() }, { label: 'Duplicate', onclick: () => duplicateItem() }, { label: 'Delete', onclick: () => deleteItem() }, ] })}> Right-click in this area

``` ```svelte

editItem() }, { label: 'Delete', onclick: () => deleteItem() } ] })}> Right-click me

``` ## Examples ### With Icons Pass a Svelte component to an action's `icon` property to render it before the label. ```svelte

lastAction = 'Edit clicked' }, { label: 'Copy', icon: CopyIcon, onclick: () => lastAction = 'Copy clicked' }, { label: 'Delete', icon: DeleteIcon, onclick: () => lastAction = 'Delete clicked' }, ] })}> Right-click for file options

``` ### With Links Actions can navigate using `href` and `target` instead of `onclick`. ```svelte

Right-click for navigation options

``` ### With Active State and Disabled Items ```svelte

viewMode = 'grid' }, { label: 'List View', active: viewMode === 'list', onclick: () => viewMode = 'list' }, { label: 'Table View', disabled: true }, ] })}> Right-click to change view (current: {viewMode})

``` ### Custom Rendered Items Set an action's `snippet` property to render custom content instead of a plain `label`. Each action renders its own snippet, so you can compose icons, secondary text, shortcut hints, or any markup you like. ```svelte

lastAction = 'Shared via email' }, { snippet: linkItem, onclick: () => lastAction = 'Link copied' }, { snippet: embedItem, onclick: () => lastAction = 'Embed code copied' }, ] })}> Right-click to share

{#snippet row(emoji, title, hint)} {emoji} {title} {hint} {/snippet} {#snippet emailItem()}{@render row('✉️', 'Email', '⌘E')}{/snippet} {#snippet linkItem()}{@render row('🔗', 'Copy link', '⌘C')}{/snippet} {#snippet embedItem()}{@render row('🧩', 'Embed', '⌘B')}{/snippet} ``` ### Promise-Aware Actions When an action's `onclick` returns a Promise, the clicked item shows a loading spinner while it is pending (after a short delay, so fast actions never flash one), and the menu stays open until the promise resolves. ```svelte

status = 'Renamed' }, ] })}> Right-click and choose "Sync to cloud"

``` ## API ### `contextMenu()` Attachment The `contextMenu` function is a Svelte attachment that registers context menu options for an element. It uses a `WeakMap` internally for garbage-collectible associations. ```svelte

Right-click target

``` ### ContextMenuOptions ```typescript interface ContextMenuOptions { actions: Array<{ onclick?: (event: PointerEvent) => void | Promise; href?: string; target?: '_blank' | '_self' | '_parent' | '_top'; active?: boolean; label?: string; disabled?: boolean; icon?: Component; snippet?: Snippet<[ContextMenuOptions & { el: HTMLElement }]>; }>; } ``` ## Props The `ContextMenu` component itself has no props -- it is a global singleton that listens for `contextmenu` events on the window and renders the appropriate menu via Popover. ## Types ```typescript interface ContextMenuOptions { actions: Array<{ onclick?: (event: PointerEvent) => void | Promise; href?: string; target?: '_blank' | '_self' | '_parent' | '_top'; active?: boolean; label?: string; disabled?: boolean; icon?: Component; snippet?: Snippet<[ContextMenuOptions & { el: HTMLElement }]>; }>; } ``` ## Accessibility - Menu items are rendered using `List` and `ListItem` components with proper semantics - Keyboard activation on menu items via Enter/Space - Escape closes the context menu - The menu closes on scroll to prevent stale positioning - Context tracking uses a `WeakMap` for automatic cleanup when elements are removed from the DOM --- # Modal > A polished dialog overlay with smooth animations, focus trapping, backdrop blur, and crossfade transitions. ## Import ```svelte import { Modal } from '@delightstack/components'; ``` ## Basic Usage ```svelte open = true}>Open Modal

This is a modal dialog with some example content. Click outside or press Escape to close.

``` ## Examples ### With Footer Actions ```svelte

Update your profile information below.

{#snippet footer()} open = false}>Cancel open = false}>Save Changes {/snippet} ``` ### Custom Header Replace the entire header with a custom snippet. ```svelte {#snippet header()}

Settings

Configure your preferences

{/snippet}

Settings content goes here.

``` ### Header Start and End Slots Add content before the title or after it (before the close button). ```svelte {#snippet header_start()} Draft {/snippet} {#snippet header_end()} {/snippet}

Document content...

``` ### Custom Width and Height Override the default sizing with explicit CSS values. ```svelte

This modal has a custom size of 800x500px.

``` ### Non-Closable Modal Prevent closing via Escape key and backdrop click for required flows. ```svelte

You must complete this step before continuing.

{#snippet footer()} open = false}>Done {/snippet} ``` ### Transition from Element Animate the modal from a specific trigger element for a connected spatial experience. ```svelte showModal = true}> Open

This modal animated from the button.

``` ## Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `open` | `boolean` | `false` | Controls visibility (`$bindable()`) | | `title` | `string` | `''` | Modal title text | | `closable` | `boolean` | `true` | Allow closing via Escape key and backdrop click | | `disable_close_icon` | `boolean` | `false` | Hide the X close button | | `modal_id` | `string` | `''` | ID used for transition target tracking | | `width` | `string` | `''` | Explicit CSS width (desktop) | | `height` | `string` | `''` | Explicit CSS height (desktop) | | `max_width` | `string` | `'calc(100vw - 2rem)'` | Maximum width | | `max_height` | `string` | `'calc(100svh - 2rem)'` | Maximum height | | `transition_target` | `HTMLElement \| Element` | `undefined` | Element to animate from when opening | | `style` | `string` | `''` | Inline CSS styles | | `class` | `string` | `''` | Additional CSS classes | | `children` | `Snippet` | `undefined` | Main modal content | | `header` | `Snippet` | `undefined` | Replace entire header | | `header_start` | `Snippet` | `undefined` | Content before the title | | `header_end` | `Snippet` | `undefined` | Content after the title (before close button) | | `footer` | `Snippet` | `undefined` | Footer content area | | `footer_start` | `Snippet` | `undefined` | Left side of footer | | `footer_end` | `Snippet` | `undefined` | Right side of footer | | `onopen` | `() => void` | `undefined` | Called when the modal opens | | `onclose` | `() => boolean \| undefined \| void` | `undefined` | Called when the modal closes. Return `false` to prevent closing. | | `onbackdropclick` | `() => void` | `undefined` | Called when the backdrop is clicked | ## Events | Event | Detail | Description | |-------|--------|-------------| | `onopen` | none | Fires when the modal mounts | | `onclose` | none | Fires when the modal is being closed. Return `false` to prevent it. | | `onbackdropclick` | none | Fires when the backdrop overlay is clicked | ## Accessibility - `role="dialog"` with `aria-modal="true"` - `aria-labelledby` pointing to the title element - `aria-describedby` pointing to the body content - Focus trap via `focusTrap` from `@delightstack/utilities` (Tab cycles within modal only) - Escape key dismissal (when `closable` is true) - Body scroll is locked while the modal is open (`html { overflow: hidden }`) - Backdrop has a blur effect for visual depth --- # Popover > A floating content container with smart Floating UI positioning, multiple trigger modes, focus trapping, and hover trapezoid for safe diagonal mouse movement. ## Import ```svelte import {Popover} from '@delightstack/components'; ``` ## Basic Usage ```svelte Toggle Popover

Popover Title

Positioned automatically using Floating UI.

Click outside to dismiss.

``` ## Examples ### Popover State Demo Control the state of the popover externally ```svelte

({ label: p, value: p }))} bind:value={placement} />

Popover position reference

Resize the container to see the popover reposition.

Popover Title

Popover opened state is controlled outside the popover component.

``` ### Hover Info Popover Open on hover with a delay. The hover trapezoid allows safe diagonal mouse movement between the trigger and the popover. ```svelte Hover over me for info Helpful tooltip-like information appears on hover. ``` ### Context Menu Positioning (x/y) Position the popover at an arbitrary coordinate instead of relative to a reference element. Useful for right-click menus. ```svelte

{ e.preventDefault(); menuX = e.clientX; menuY = e.clientY; menuOpen = true; }}> Right-click in this area

Custom context menu

``` ### Focus-Triggered Popover Open when the reference element receives focus, close on blur. ```svelte

• Suggestion 1
• Suggestion 2
• Suggestion 3

``` ### Dense and Comfortable Control the padding with `dense` or `comfortable` props. ```svelte Compact Default Spacious ``` ## Props | Prop | Type | Default | Description | | --------------------- | ----------------------- | -------------- | ------------------------------------------------------------------- | | `ref_element` | `HTMLElement` | `undefined` | Element to position relative to | | `opened` | `boolean` | `false` | Controls visibility (`$bindable()`) | | `placement` | `Placement` | `'bottom'` | Preferred Floating UI placement | | `strategy` | `'absolute' \| 'fixed'` | `'fixed'` | CSS positioning strategy. `'fixed'` renders through a Portal. | | `arrow` | `boolean` | `true` | Show arrow pointer toward the trigger | | `x` | `number` | `undefined` | X coordinate for virtual positioning (used instead of `ref_element`) | | `y` | `number` | `undefined` | Y coordinate for virtual positioning (used instead of `ref_element`) | | `open_on_hover` | `boolean` | `false` | Open when the reference element is hovered | | `open_on_click` | `boolean` | `false` | Open when the reference element is clicked | | `open_on_focus` | `boolean` | `false` | Open when the reference element receives focus | | `close_on_outside_click` | `boolean` | `true` | Close when clicking outside the popover | | `close_on_inside_click` | `boolean` | `false` | Close when a button-like element inside is clicked | | `close_on_escape_key` | `boolean` | `true` | Close on Escape key | | `disable_initial_focus` | `boolean` | `false` | Do not auto-focus content when opened | | `hover_delay` | `number` | `100` | Delay in ms before opening on hover | | `dense` | `boolean` | `false` | Reduced padding (`0.5rem 0.75rem`) | | `comfortable` | `boolean` | `false` | Increased padding (`1.5rem 2rem`) | | `radius` | `string` | `undefined` | Border radius override via `--popover-radius` | | `children` | `Snippet` | `undefined` | Popover content | | `id` | `string` | auto-generated | Element ID | | `class` | `string` | `''` | Additional CSS classes | | `style` | `string` | `''` | Inline CSS styles | ## Events | Event | Detail | Description | | ------------------- | --------- | ----------------------------------------------------- | | `opened` (bindable) | `boolean` | Reactive state reflecting whether the popover is open | ## Accessibility - Focus trap via `focusTrap` from `@delightstack/utilities` keeps Tab cycling within the popover - Escape key closes the popover (respects nested popovers -- closes innermost first) - Focus returns to the trigger element on close - Keyboard activation on the trigger element via Enter/Space (when `open_on_click` or `open_on_focus` is used) - Proper `z-index` stacking with `data-popover-index` for nested popovers --- # Portal > A utility component that renders children in a different DOM location, escaping parent overflow and stacking contexts. ## Import ```svelte import { Portal } from '@delightstack/components'; ``` The `portal` action is also available for direct element usage: ```svelte import { portal } from '@delightstack/components'; ``` ## Basic Usage ```svelte

This content renders in the .portals container at the end of body.

``` ## Examples ### Default Target (.portals) By default, Portal creates (or reuses) a `.portals` container at the end of ``: ```svelte

This escapes any overflow:hidden ancestors.

``` The resulting DOM structure: ```html

``` ### Custom CSS Selector Target Specify a CSS selector to portal content to a specific element. ```svelte

Saved successfully

``` ### HTMLElement Target Pass a direct DOM element reference as the target. ```svelte

Content portaled into the custom container.

``` ### Svelte Action Usage The `portal` function is also exported as a Svelte action for use with `use:portal`: ```svelte

Content moved to #my-target

``` ### Escaping Overflow Containers A common use case is rendering floating content that would otherwise be clipped by a parent with `overflow: hidden`. ```svelte

This container clips its children.

Option 1 Option 2

``` ## Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `target` | `string \| HTMLElement` | `'.portals'` | Destination element or CSS selector | | `children` | `Snippet` | `undefined` | Content to portal | | `id` | `string` | auto-generated | Element ID for the portal wrapper | ## How It Works 1. Children are rendered normally in the Svelte component tree (reactivity stays intact). 2. On mount, the DOM nodes are moved to the target element using `use:portal`. 3. Svelte reactivity, event handlers, and bindings continue to work across the portal boundary. 4. On unmount, nodes are removed from the target and cleaned up. The portal wrapper uses `display: contents` so it does not affect layout at the target location. ## Accessibility - Maintains proper reactivity and event handling across the portal boundary - DOM order should match visual order when possible - Combine with `focusTrap` from `@delightstack/utilities` for modal-like portaled content - Screen readers follow DOM order, so portaled content appears at the portal target location :::note Most overlay components (Modal, Popover, CommandPalette) handle portaling internally. Direct Portal usage is typically only needed for custom overlay patterns or when building new overlay components. ::: --- # ThemeToggle > A theme switcher that cycles between light, dark, and auto modes with animated sun-to-moon icon morphing and localStorage persistence. ## Import ```svelte import { ThemeToggle } from '@delightstack/components'; ``` ## Basic Usage ```svelte ``` ## Examples ### Bindable Theme State Bind to the `theme` prop to read or control the current theme preference. ```svelte

Current theme: {theme}

``` ### Two-State Toggle (No Auto) Disable the system/auto option to cycle only between light and dark. ```svelte ``` ### With a Text Label Set `show_label` to display the current mode name ("Light" / "Dark" / "Auto") beside the icon. Pass `label` to override the text with your own. ```svelte ``` ### Detecting Effective Dark Mode Bind to `is_dark` to get the resolved dark state (taking system preference into account when theme is `'auto'`). ```svelte {#if is_dark}

Dark mode is active

{:else}

Light mode is active

{/if} ``` ### In a Header / Navbar Use a smaller size to fit in navigation bars. ```svelte

``` ### Reacting to Changes Use the `onchange` callback to run logic when the theme changes. ```svelte { console.log('Theme changed to:', newTheme); }} /> ``` ### Custom Tooltip Override the default tooltip text. ```svelte ``` ## Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `theme` | `'light' \| 'dark' \| 'auto'` | `'auto'` | Current theme preference (`$bindable()`) | | `is_dark` | `boolean` | `false` | Computed resolved dark state (`$bindable()`, read-only). True when effective appearance is dark. | | `size` | `'0' \| '1' \| '2'` | `'1'` | Component size (`'0'` = 18px icon, `'1'` = 24px icon, `'2'` = 32px icon) | | `disable_auto` | `boolean` | `false` | Hide the auto/system option (two-state toggle only) | | `show_label` | `boolean` | `false` | Show a text label beside the icon ("Light" / "Dark" / "Auto") | | `label` | `string` | `undefined` | Custom label text override. Falls back to the current mode name when `show_label` is set. | | `tooltip` | `string` | `''` | Override the default tooltip text. Defaults to the `aria-label` value. | | `id` | `string` | `undefined` | Element ID | | `class` | `string` | `''` | Additional CSS classes | | `onchange` | `(theme: 'light' \| 'dark' \| 'auto') => void` | `undefined` | Called when the theme changes | ## Events | Event | Detail | Description | |-------|--------|-------------| | `onchange` | `'light' \| 'dark' \| 'auto'` | Fires after cycling to a new theme state | ## Theme Cycle Order | Mode | Cycle | |------|-------| | Three-state (default) | `light` -> `dark` -> `auto` -> `light` | | Two-state (`disable_auto`) | `light` -> `dark` -> `light` | ## Theme Application When the theme changes, the component: 1. Sets `document.documentElement.style.colorScheme` to `'light'` or `'dark'` based on the effective dark state. 2. Saves the preference to `localStorage` under the key `'delightstack:theme'`. 3. Watches for system preference changes via `matchMedia('(prefers-color-scheme: dark)')` and updates `is_dark` reactively when theme is `'auto'`. ### Anti-Flash Script To prevent a flash of wrong theme on page load, add the following inline script to your HTML `` (runs synchronously before the body renders): ```html ``` ## Accessibility - Renders as a `` element with a descriptive `aria-label` (e.g., "Theme: dark", "Theme: auto (system preference)") - Keyboard toggle via Space and Enter keys - Focus ring on `:focus-visible` - Tooltip via `{@attach tooltip()}` showing the current state - The SVG icon uses `aria-hidden="true"` since the button's `aria-label` conveys the meaning - When theme is `'auto'`, a small "A" indicator appears on the button --- # Accordion > A vertically stacked set of collapsible sections built on semantic details/summary elements with smooth animations. ## Import ```svelte import { Accordion, AccordionItem } from '@delightstack/components'; ``` ## Basic Usage ```svelte

Getting started is easy! Create an account and follow the onboarding steps.

We accept all major credit cards, PayPal, and bank transfers.

Reach our support team via email or through the in-app chat.

``` ## Examples ### Variants By default an accordion is borderless — just a subtle hairline between items (and none after the last one), with items sitting flush against each other. Add `filled` to join the items into one tinted surface, or `outline` to wrap the whole set in a single bordered, rounded frame. Corners follow the library's squircle treatment. `filled` and `outline` are independent, so you can combine them for a framed set of filled items. ```svelte … … … ``` ### Separated Panels By default items stay connected. Add `separated` and the open item animates _apart_ from the list, gaining a gap above and below so the active section reads as emphasised. With `filled` or `outline` this is especially nice: the single surface starts connected and **splits into rounded pieces** as an item opens — the item above rounds its bottom corners, the active item rounds all four, and the item below rounds its top corners. Closing the item glides everything back into one piece. ```svelte … … ``` ### Multiple Panels Open Allow multiple sections to be expanded simultaneously. When `multiple` is true, `value` is an array of strings. ```svelte

Content for the first section.

Content for the second section.

Content for the third section.

``` ### Always One Open Prevent all sections from being collapsed by setting `collapsible` to `false`. ```svelte

At least one section is always open.

Click to switch which section is open.

``` ### Custom Trigger Use the `trigger` snippet to replace the default title rendering with custom content. ```svelte {#snippet trigger()}

Profile Settings

{/snippet}

Manage your name, avatar, and public profile information.

{#snippet trigger()}

Advanced Settings

{/snippet}

Configure advanced options like API keys, webhooks, and integrations.

``` ### Dense and Comfortable Spacing ```svelte

Less padding for dense layouts.

Tighter spacing between items.

More padding for a relaxed feel.

Extra breathing room between items.

``` ### Skeleton Loading ```svelte … ``` ### Nested Accordions ```svelte

A compiler-based framework that shifts work to build time.

A library for building user interfaces with a virtual DOM.

Popular choices include Node.js, Python, Go, and Rust.

``` ## Props ### Accordion | Prop | Type | Default | Description | |------|------|---------|-------------| | `value` | `string \| string[]` | `''` | Currently open item(s), bindable | | `multiple` | `boolean` | `false` | Allow multiple panels open simultaneously | | `collapsible` | `boolean` | `true` | Allow closing all items | | `disabled` | `boolean` | `false` | Disable all items | | `dense` | `boolean` | `false` | Compact header/content padding | | `comfortable` | `boolean` | `false` | Relaxed header/content padding | | `filled` | `boolean` | `false` | Join items into one subtly tinted, rounded surface | | `outline` | `boolean` | `false` | Wrap the whole set in a single bordered, rounded (squircle) frame | | `separated` | `boolean` | `false` | Animate the open item apart from the list; with `filled`/`outline` the surface splits into rounded pieces | | `skeleton` | `boolean` | `false` | Show loading skeleton | | `skeleton_count` | `number` | `3` | Number of skeleton items to render | | `id` | `string` | auto | Element ID | | `class` | `string` | `''` | Additional CSS classes | | `children` | `Snippet` | - | AccordionItem children | ### AccordionItem | Prop | Type | Default | Description | |------|------|---------|-------------| | `value` | `string` | required | Unique identifier for this item | | `title` | `string` | `''` | Header text shown in the summary | | `disabled` | `boolean` | `false` | Disable this individual item | | `trigger` | `Snippet` | - | Custom header content replacing title text | | `children` | `Snippet` | - | Panel content | ## Accessibility - Uses semantic `

`/`

` elements for native accessibility - `aria-expanded` on each `

` reflects its open/closed state - `aria-controls` links each `

` to its content panel - `role="region"` on each content panel with `aria-labelledby` - **Tab** moves focus between summary elements - **Arrow Down / Arrow Up** moves focus to next/previous summary - **Enter / Space** toggles the focused item - **Home** moves focus to the first summary - **End** moves focus to the last summary - Disabled items are excluded from arrow key navigation - Respects `prefers-reduced-motion` for chevron transitions --- # Avatar > A profile image component with initials fallback, status indicators, and deterministic OKLCH color generation. ## Import ```svelte import { Avatar } from '@delightstack/components'; ``` ## Basic Usage ```svelte ``` ## Examples ### With Image ```svelte ``` ### Initials Fallback When no `src` is provided (or the image fails to load), the avatar displays initials derived from the `name` prop on a deterministic OKLCH-hashed background color. ```svelte ``` ### Sizes Six size presets are available, from inline mentions to hero sections. ```svelte ``` ### Status Indicator ```svelte ``` ### Badge ```svelte ``` ### Square Shape and Ring ```svelte ``` ### Interactive Avatar When `onclick` is provided, the avatar becomes a focusable button with hover/active states. ```svelte openProfile(user)} /> ``` ### With Tooltip ```svelte ``` ### Skeleton Loading ```svelte ``` ## Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `src` | `string` | - | Image URL | | `name` | `string` | - | Name for initials fallback and auto alt text | | `size` | `'0' \| '1' \| '2' \| '3' \| '4' \| '5'` | `'1'` | Avatar size preset | | `square` | `boolean` | `false` | Rounded square shape instead of circle | | `status` | `'online' \| 'away' \| 'busy' \| 'offline'` | - | Status indicator dot | | `status_position` | `'top' \| 'bottom'` | `'bottom'` | Status dot position | | `badge` | `number \| boolean` | - | Notification badge (true for dot, number for count) | | `ring` | `boolean` | `false` | Show colored ring around avatar | | `ring_color` | `string` | - | Custom ring color | | `skeleton` | `boolean` | `false` | Show a skeleton until the avatar has content — it dismisses itself once the image loads (or immediately when `name`/children can render) | | `tooltip` | `string` | `''` | Tooltip text | | `onclick` | `(e: MouseEvent) => void` | - | Click handler (makes avatar interactive) | | `id` | `string` | auto | Element ID | | `class` | `string` | `''` | Additional CSS classes | | `children` | `Snippet` | - | Custom fallback content | ## Events | Event | Detail | Description | |-------|--------|-------------| | `onclick` | `MouseEvent` | Fires when an interactive avatar is clicked | ## Accessibility - `name` prop auto-generates `alt` text on the image element - Decorative avatars (no name) use `alt=""` - Status indicator has `aria-label` (e.g., "Online") - Badge has `aria-label` (e.g., "5 notifications") - Interactive avatars (with `onclick`) receive `role="button"`, are focusable, and support Enter/Space activation - Focus ring is visible on keyboard navigation - Respects `prefers-reduced-motion` for pulse animation on online status --- # AvatarGroup > A stacked group of overlapping avatars with overflow indicator, commonly used to show participants. ## Import ```svelte import { AvatarGroup } from '@delightstack/components'; ``` ## Basic Usage ```svelte ``` ## Examples ### Limiting Visible Avatars When the number of avatars exceeds `max`, a "+N" overflow indicator appears. ```svelte ``` ### Different Sizes ```svelte ``` ### Expandable Overflow When `expandable` is true, clicking the overflow indicator reveals all hidden avatars. ```svelte ``` ### Clickable Avatars ```svelte openProfile(avatar)} /> ``` ### With Overflow Click Handler ```svelte showAllParticipants(remaining)} /> ``` ### Skeleton Loading ```svelte ``` ## Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `avatars` | `AvatarData[]` | `[]` | Array of avatar data | | `max` | `number` | `5` | Maximum visible avatars before overflow | | `size` | `'0' \| '1' \| '2' \| '3' \| '4' \| '5'` | `'1'` | Avatar size (passed to each Avatar) | | `overlap` | `number` | `0.25` | Overlap ratio (0-1) | | `direction` | `'left' \| 'right'` | `'right'` | Stack direction | | `ring_color` | `string` | `'var(--color-bg)'` | Ring/border color around each avatar | | `expandable` | `boolean` | `false` | Click overflow to reveal all | | `skeleton` | `boolean` | `false` | Show loading skeleton | | `skeleton_count` | `number` | `4` | Number of skeleton circles to show | | `id` | `string` | auto | Element ID | | `class` | `string` | `''` | Additional CSS classes | ## Events | Event | Detail | Description | |-------|--------|-------------| | `onclick` | `{ avatar: AvatarData, index: number }` | Individual avatar clicked | | `onoverflowclick` | `{ remaining: AvatarData[] }` | Overflow "+N" indicator clicked | ## Types ```typescript interface AvatarData { src?: string; name: string; href?: string; } ``` ## Accessibility - Container has `role="group"` with `aria-label="Avatar group"` - Each avatar has an accessible name from the `name` field in `AvatarData` - Tooltips display each avatar's name on hover - Overflow indicator has `aria-label` (e.g., "3 more avatars") - When `expandable` or `onoverflowclick` is set, the overflow indicator has `role="button"` and is keyboard accessible (Enter/Space) - Hovered avatar rises slightly with `translateY(-2px)` for visual feedback --- # Calendar > A full-featured date display and selection component with single, range, and multiple selection modes. ## Import ```svelte import { Calendar } from '@delightstack/components'; ``` The `CalendarEvent` and `MarkedDate` types are also exported: ```svelte import type { CalendarEvent, MarkedDate } from '@delightstack/components'; ``` ## Basic Usage ```svelte ``` The container is **transparent** by default so it drops onto any surface. Add `filled` for a subtle surface, or `outline` for a hairline border — both give it generously rounded card corners. They can be combined. ```svelte ``` ## Examples ### Density Use `dense` for compact spacing or `comfortable` for a roomier layout. The corner radius scales with the density. ```svelte ``` ### Single Date Selection ```svelte ``` ### Date Range Selection First click sets the start date, second click sets the end date. Hovering between clicks previews the range. ```svelte ``` ### Multiple Date Selection Click to toggle individual dates on or off. ```svelte ``` ### With Date Constraints ```svelte ``` ### With Marked Dates ```svelte ``` ### With Events ```svelte ``` ### Locale and Week Start ```svelte ``` ### With Time Slots ```svelte console.log(time, date)} /> ``` ### Skeleton Loading ```svelte ``` ## Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `value` | `Date \| Date[] \| [Date, Date]` | - | Selected date(s), bindable | | `mode` | `'single' \| 'range' \| 'multiple'` | `'single'` | Selection mode | | `month` | `Date` | `new Date()` | Currently displayed month, bindable | | `min` | `Date` | - | Minimum selectable date | | `max` | `Date` | - | Maximum selectable date | | `disabled` | `Date[] \| ((date: Date) => boolean)` | `[]` | Disabled dates (array or predicate function) | | `marked` | `MarkedDate[]` | `[]` | Dates with colored dot markers | | `events` | `CalendarEvent[]` | `[]` | Events to display on dates | | `week_starts_on` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` | First day of week (0=Sunday) | | `locale` | `string` | - | BCP 47 locale string for formatting | | `show_time_slots` | `boolean` | `false` | Show time slot picker alongside calendar | | `time_slot_interval` | `number` | `30` | Time slot interval in minutes | | `time_slot_min` | `string` | `'00:00'` | Earliest time slot | | `time_slot_max` | `string` | `'23:59'` | Latest time slot | | `dense` | `boolean` | `false` | Compact cell spacing | | `comfortable` | `boolean` | `false` | Relaxed cell spacing | | `filled` | `boolean` | `false` | Fill the container with a subtle surface (card look) | | `outline` | `boolean` | `false` | Add a 1px outline + rounded corners (transparent fill) | | `skeleton` | `boolean` | `false` | Show loading skeleton | | `id` | `string` | auto | Element ID | | `class` | `string` | `''` | Additional CSS classes | ## Events | Event | Detail | Description | |-------|--------|-------------| | `onselect` | `{ value: Date \| Date[] \| [Date, Date] }` | Selection changed | | `onmonthchange` | `{ month: Date }` | Navigated to a different month | | `ontimeslotselect` | `{ time: string, date: Date }` | Time slot selected | ## Types ```typescript interface CalendarEvent { id: string; title: string; start: Date; end?: Date; color?: string; allDay?: boolean; } interface MarkedDate { date: Date; color?: string; label?: string; } ``` ## Accessibility - Calendar container has `role="group"` with `aria-label="Calendar"` - Day grid has `role="grid"` with `aria-label="Calendar dates"` - Weekday headers use `role="columnheader"` - Each day cell is a `

` with `role="gridcell"`, `aria-selected`, and `aria-disabled` - Today and event information included in each cell's `aria-label` - Month/year header uses `aria-live="polite"` for screen reader announcements - Navigation buttons have `aria-label` ("Previous month", "Next month") - Time slots panel has `role="listbox"` with `role="option"` on each slot - Full keyboard navigation: - **Arrow keys** move focus between days - **Page Up / Page Down** moves by month (with Shift, by year) - **Home / End** moves to start/end of week - **Enter / Space** selects the focused date - Focus wraps across month boundaries automatically - Respects `prefers-reduced-motion` --- # Chart > A data visualization component supporting line, area, bar, horizontal bar, pie, and donut chart types. ## Import ```svelte import { Chart } from '@delightstack/components'; ``` The `ChartData` and `Dataset` types are also exported: ```svelte import type { ChartData, Dataset } from '@delightstack/components'; ``` ## Basic Usage ```svelte ``` ## Examples ### Line Chart ```svelte ``` ### Area Chart with Data Points ```svelte ``` ### Stacked Bar Chart ```svelte ``` ### Horizontal Bar Chart ```svelte ``` ### Donut Chart ```svelte ``` ### Pie Chart ```svelte ``` ### Custom Colors ```svelte ``` ### Theming By default the series colors come from the theme's categorical chart palette (`--chart-1` … `--chart-8` in `@delightstack/components/styles`), so a chart dropped into a delightstack dashboard matches the active theme — including light/dark — with no configuration. The palette is a tonal "brand family" derived from your `--color-primary` seed (hues stay in an analogous band while lightness varies), so rebranding the app recolors the charts automatically. To recolor a single series globally, override the token in your own CSS: ```css :root { --chart-1: #6366f1; --chart-2: oklch(0.7 0.15 30); } ``` For a one-off chart, prefer the `colors` prop or a per-series `color`. ### Skeleton Loading ```svelte ``` ## Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `type` | `'line' \| 'area' \| 'bar' \| 'horizontal-bar' \| 'pie' \| 'donut'` | `'line'` | Chart type | | `data` | `ChartData` | required | Data to display | | `height` | `number` | `300` | Chart height in pixels | | `colors` | `string[]` | theme | Custom color palette (overrides the theme `--chart-*` default) | | `show_grid` | `boolean` | `true` | Show grid lines | | `show_legend` | `boolean` | `true` | Show legend | | `show_tooltip` | `boolean` | `true` | Enable interactive tooltips | | `animate` | `boolean` | `true` | Animate on initial load and data changes | | `stacked` | `boolean` | `false` | Stack datasets (bar, area) | | `curved` | `boolean` | `true` | Smooth curves for line/area charts | | `show_points` | `boolean` | `false` | Show data points on line/area charts | | `inner_radius` | `number` | `0` | Inner radius ratio for donut (0 = pie, >0 = donut) | | `skeleton` | `boolean` | `false` | Show loading skeleton | | `id` | `string` | auto | Element ID | | `class` | `string` | `''` | Additional CSS classes | ## Types ```typescript interface ChartData { labels: string[]; datasets: Dataset[]; } interface Dataset { label: string; data: number[]; color?: string; } ``` ## Accessibility - SVG chart has `role="img"` with an `aria-label` describing the chart type - Legend items are interactive buttons for toggling dataset visibility - Tooltips appear on hover showing exact values and dataset labels - Click legend items to toggle datasets on or off (at least one dataset must remain visible) - Responsive width via `resizeObserver` attachment -- height is fixed via the `height` prop - Empty state displays a "No data available" message - Respects `prefers-reduced-motion` by disabling all animations --- # Code > A syntax-highlighted code block with line numbers, copy-to-clipboard, line highlighting, and diff display. ## Import ```svelte import { Code } from '@delightstack/components'; ``` ## Basic Usage ```svelte ``` ## Examples ### With Filename A header bar appears when `filename` or `show_copy` is set. ```svelte ``` ### Line Highlighting Draw attention to specific lines by providing their line numbers. ```svelte ``` ### Without Line Numbers ```svelte ``` ### Diff Display Lines starting with `+` get a green background, lines starting with `-` get a red background, and `@@` lines are styled as section headers. ```svelte ``` ### Max Height with Scroll Long code blocks can be constrained with a maximum height. The content scrolls vertically while the header stays visible. ```svelte ``` ### Line Wrapping ```svelte ``` ### Skeleton Loading ```svelte ``` ## Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `code` | `string` | required | Code string to display | | `language` | `string` | `'plaintext'` | Language for syntax highlighting | | `filename` | `string` | - | Filename displayed in the header | | `show_line_numbers` | `boolean` | `true` | Show line numbers | | `show_copy` | `boolean` | `true` | Show copy-to-clipboard button | | `start_line` | `number` | `1` | Starting line number | | `highlight_lines` | `number[]` | `[]` | Line numbers to highlight | | `diff` | `boolean` | `false` | Render as unified diff | | `wrap` | `boolean` | `false` | Wrap long lines instead of horizontal scroll | | `max_height` | `string` | - | Max height with vertical scroll (e.g., `'400px'`) | | `skeleton` | `boolean` | `false` | Show loading skeleton | | `id` | `string` | auto | Element ID | | `class` | `string` | `''` | Additional CSS classes | ## Supported Languages The built-in tokenizer supports these languages out of the box: - JavaScript / TypeScript (js, jsx, ts, tsx) - HTML / XML - CSS / SCSS / Sass / Less - JSON / JSONC - Python - Bash / Shell / Zsh - SQL - Svelte - Markdown - Plaintext (default) ## Accessibility - Uses semantic `

` markup
- Copy button is keyboard accessible with `aria-label` ("Copy code" / "Copied")
- Line numbers are decorative (`aria-hidden="true"`) and excluded from text selection via `user-select: none`
- Focus ring on the copy button for keyboard navigation
- Respects `prefers-reduced-motion` for skeleton animations


---



# Comparison

> An interactive before/after image comparison slider using CSS clip-path for the reveal effect.

## Import

```svelte
import { Comparison } from '@delightstack/components';
```

## Basic Usage

```svelte



```

## Examples

### With Alt Text

```svelte

```

### Custom Labels

```svelte

```

### Without Labels

```svelte

```

### Vertical Orientation

The divider moves up and down instead of left and right.

```svelte

```

### Controlled Position

Bind to the `position` prop to control or read the slider position (0-100).

```svelte




Position: {position}%
```

### Snap Points

Define snap points that the divider magnetically locks to. The divider uses springy magnetic gravity near snap points and a rubber-band effect when dragged past the edges.

```svelte

```

### Skeleton Loading

```svelte

```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `before` | `string` | required | Before image URL |
| `after` | `string` | required | After image URL |
| `before_alt` | `string` | `'Before'` | Before image alt text |
| `after_alt` | `string` | `'After'` | After image alt text |
| `position` | `number` | `50` | Divider position (0-100), bindable |
| `vertical` | `boolean` | `false` | Vertical orientation (divider moves up/down) |
| `show_labels` | `boolean` | `true` | Show before/after labels |
| `label_before` | `string` | `'Before'` | Before label text |
| `label_after` | `string` | `'After'` | After label text |
| `skeleton` | `boolean` | `false` | Show loading skeleton |
| `snaps` | `number[]` | `[]` | Snap points the divider magnetically locks to (0-100) |
| `id` | `string` | auto | Element ID |
| `class` | `string` | `''` | Additional CSS classes |

## Events

| Event | Detail | Description |
|-------|--------|-------------|
| `onchange` | `{ position: number }` | Fired when the divider position changes |

## CSS Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `--cmp-radius` | `var(--radius-xl, 20px)` | Corner radius of the container (set `0` to square it off) |
| `--cmp-aspect` | `16 / 9` | Aspect ratio of the skeleton placeholder — set it to match the real images so the skeleton ↔ loaded swap doesn't shift |

## Accessibility

- Divider handle has `role="slider"` with `aria-valuenow`, `aria-valuemin="0"`, and `aria-valuemax="100"`
- `aria-label="Comparison slider"` on the handle
- Both images have descriptive alt text
- Full keyboard support:
  - **Tab** to focus the handle
  - **Arrow Left/Right** (horizontal) or **Arrow Up/Down** (vertical) moves in 1% increments
  - **Shift+Arrow** moves in 10% increments
  - **Home** moves to 0%
  - **End** moves to 100%
- Click anywhere on the image to jump the divider to that position
- `touch-action: none` prevents scroll interference on mobile
- Images have `draggable="false"` to prevent native drag behavior


---



# Counter

> An animated number display that counts up or down with IntersectionObserver-triggered animation and locale-aware formatting.

## Import

```svelte
import { Counter } from '@delightstack/components';
```

## Basic Usage

```svelte

```

## Examples

### Revenue with Prefix

The prefix is rendered smaller and top-aligned, like a superscript.

```svelte

```

### Percentage with Suffix

```svelte

```

### Custom Formatter

Override the default `Intl.NumberFormat` with a custom function for compact display.

```svelte
 {
    if (n >= 1000000) return (n / 1000000).toFixed(1) + 'M';
    if (n >= 1000) return (n / 1000).toFixed(1) + 'K';
    return n.toString();
  }}
/>
```

### Locale-Aware Formatting

Number separators adapt to the specified locale.

```svelte

```

### With Delay and Duration

```svelte

```

### Skeleton Loading

`value` is optional — it may arrive late (e.g. while stats load). With `skeleton`
set, a number-shaped shimmer pill shows until `value` is available, and the
count-up starts the moment it arrives.

```svelte

```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `number` | - | Target number to display; may arrive late (pair with `skeleton`) |
| `duration` | `number` | `1500` | Animation duration in milliseconds |
| `delay` | `number` | `0` | Delay before animation starts (ms) |
| `decimals` | `number` | `0` | Number of decimal places |
| `prefix` | `string` | - | Text before the number (rendered small + top) |
| `suffix` | `string` | - | Text after the number (rendered small + top) |
| `format` | `(n: number) => string` | - | Custom formatter (overrides Intl.NumberFormat) |
| `separator` | `boolean` | `true` | Use locale thousands separator |
| `locale` | `string` | - | BCP 47 locale for number formatting |
| `easing` | `(t: number) => number` | quintOut | Animation easing function |
| `skeleton` | `boolean` | `false` | Show a number-shaped shimmer pill until `value` is available; the count-up starts when it arrives. Pill width is set by `--counter-skeleton-width` (default `4ch`) |
| `id` | `string` | auto | Element ID |
| `class` | `string` | `''` | Additional CSS classes |

## Methods

| Method | Description |
|--------|-------------|
| `restart()` | Reset and replay the count animation from `0` to `value`. Useful for demos and on-demand replays. |

## Events

| Event | Detail | Description |
|-------|--------|-------------|
| `oncomplete` | - | Fired when the animation finishes |

## Accessibility

- Element has `aria-live="polite"` so screen readers announce value changes
- `role="img"` with a computed `aria-label` including prefix, value, and suffix
- The true value is always exposed via `aria-label`, so assistive tech reads it regardless of the animated visual value
- `prefers-reduced-motion` disables all animation — the final value is shown immediately
- `font-variant-numeric: tabular-nums` prevents layout shift during animation
- Animation is triggered by `IntersectionObserver` — starts only when the element scrolls into view
- On the server (SSR) the counter renders at `0`, matching the initial client render so hydration is seamless; it then counts up once visible (with JS disabled it stays at `0`, but the real value remains in `aria-label`)


---



# Expand

> A smooth animated container that expands and collapses content using CSS Grid height animation.

## Import

```svelte
import { Expand } from '@delightstack/components';
```

## Basic Usage

```svelte

showDetails = !showDetails}> {showDetails ? 'Hide' : 'Show'} Details

Additional information that can be expanded and collapsed smoothly.

The height animates from 0 to auto without any JavaScript measurement.

``` ## Examples ### Toggle with a Button ```svelte visible = !visible}> {visible ? 'Collapse' : 'Expand'}

This content slides in and out smoothly.

``` ### Conditional Sections ```svelte

``` ### Always Expanded A simple example showing the Expand container in its open state. ```svelte

This content is visible because show is true.

``` ### With Custom Inline Style ```svelte visible = !visible}> {visible ? 'Hide' : 'Show'} Styled Content

This expand container has a custom inline style with an accent border and tinted background.

``` ## Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `show` | `boolean` | `false` | Controls expanded/collapsed state, bindable | | `style` | `string` | `''` | Additional inline styles | | `children` | `Snippet` | - | Content to expand/collapse | ## How It Works The component uses the CSS Grid trick for animating height to/from auto: - **Collapsed**: `grid-template-rows: min-content 0fr` with `opacity: 0` - **Expanded**: `grid-template-rows: min-content 1fr` with `opacity: 1` - A `::before` pseudo-element with `min-content` row prevents layout collapse - Content uses `visibility: hidden` when collapsed and `visibility: visible` when expanded This approach provides smooth height animation without any JavaScript measurement of content height. ## Accessibility - Uses the `inert` attribute when collapsed to prevent focus trapping in hidden content - Screen readers skip collapsed content entirely (content is not focusable or readable when hidden) - No explicit ARIA attributes are needed -- the `inert` attribute handles accessibility - Content opacity fades alongside height for a polished transition - Collapsed state takes zero space in the layout --- # List > A flexible container for list items with selection handling, multiple interaction modes, and consistent styling. ## Import ```svelte import { List, ListItem } from '@delightstack/components'; ``` ## Basic Usage ```svelte console.log('clicked')}>Action Item console.log('clicked')}>Another Action ``` ## Examples ### Appearance The list is **transparent** by default, so it composes onto any surface (a card, a sidebar, a popover) without imposing its own. Add `filled` for a subtle surface or `outline` for a bordered card — both restore the visible rounded corners, and the two can be combined. The item hover/active highlights stay rounded in every mode. ```svelte Profile Settings Sign out … … … ``` ### Radio Selection Single-select mode using radio buttons. Bind `value` to track the selected index. ```svelte Small Medium Large ``` ### Checkbox Multi-Select Multiple-select mode using checkboxes. The `value` array contains all selected indices. ```svelte Notifications Email Updates SMS Alerts ``` ### Toggle Multi-Select The same multi-select behavior as `checkbox`, rendered with toggle switches — a natural fit for settings lists. ```svelte Wi-Fi Bluetooth Airplane Mode ``` ### Spacing `dense` tightens the rows (great for action menus); `comfortable` relaxes them. The default sits between the two and lines up with the standard control height. ```svelte handleEdit()}>Edit handleDuplicate()}>Duplicate handleDelete()}>Delete … … ``` ### Text Mode (Non-Interactive) Display-only list with no hover effects or click handlers. ```svelte Read-only item Another item ``` ### Skeleton Loading ```svelte … ``` ## Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `type` | `'button' \| 'text' \| 'radio' \| 'checkbox' \| 'toggle'` | `'button'` | Interaction mode for items | | `value` | `number[]` | `[]` | Selected item indices (bindable) | | `dense` | `boolean` | `false` | Compact spacing | | `comfortable` | `boolean` | `false` | Relaxed spacing | | `filled` | `boolean` | `false` | Render on a subtle filled surface with rounded corners | | `outline` | `boolean` | `false` | Render with a 1px border + rounded corners (transparent fill); combine with `filled` for a card | | `disabled` | `boolean` | `false` | Disable all items | | `touched` | `boolean` | `false` | Whether the user has interacted (bindable) | | `padding_x` | `string` | - | Horizontal padding override (e.g. `'16px'`) | | `padding_y` | `string` | - | Vertical padding override (e.g. `'16px'`) | | `skeleton` | `boolean` | `false` | Show loading skeleton items | | `skeleton_count` | `number` | `5` | Number of skeleton items to show | | `id` | `string` | auto | Element ID | | `class` | `string` | `''` | Additional CSS classes | | `style` | `string` | `''` | Additional inline styles | | `children` | `Snippet` | - | ListItem children | ## Events | Event | Detail | Description | |-------|--------|-------------| | `ontouch` | `() => void` | Called when the first interaction occurs | | `onchange` | `(value: number[]) => void` | Called when selection changes | ## Types The List component exports a `ListContext` interface used for parent-child communication via Svelte context: ```typescript interface ListContext { type: 'button' | 'text' | 'radio' | 'checkbox' | 'toggle'; value: number[]; dense: boolean; comfortable: boolean; disabled: boolean; level: number; id: string; } ``` ## Accessibility - Renders as a `

` element with proper list semantics - `aria-selected` applied on items in selection modes - Full keyboard navigation: Arrow Up/Down to move focus, Home/End to jump, Space/Enter to activate - Focus management tracked via the `onFocusWithin` utility attachment - Disabled state communicated to assistive technology - Nested lists inherit parent context with incremented `level` --- # ListItem > A versatile list item that adapts to its parent List context, supporting buttons, radios, checkboxes, async click handling, and submenu support. ## Import ```svelte import { List, ListItem } from '@delightstack/components'; ``` ## Basic Usage ```svelte console.log('clicked')}>Click Me ``` ## Examples ### List Appearance Items sit on whatever surface the parent `List` provides. The list is transparent by default; the `filled` and `outline` props (on **`List`**, not `ListItem`) give it a surface or border — see the [List page](/components/display/list/#appearance) for details. ```svelte … … … ``` ### Navigation Links ListItems can render as anchor elements when `href` is provided. ```svelte Profile Settings Log Out ``` ### Async Click Handling When `onclick` returns a Promise, the row manages its own loading feedback — no `loading` prop required: - **Instant actions don't flash.** The spinner only appears if the promise is still pending after ~100ms; anything faster is treated as instant. - **The spinner can't blink.** Once shown, it stays for at least ~1s, then eases out quickly. - **Success is confirmed automatically.** On resolve, a brief checkmark flashes; on reject, no checkmark is shown. ```svelte { await api.saveItem(); // throws on failure -> no checkmark }}> Save Item ``` ### Manual Success Checkmark When you drive `loading` yourself (e.g. from a store), set `loading_success` to flash the same confirming checkmark as `loading` returns to `false`. Leave it off and the spinner simply disappears. ```svelte Save Item ``` ### Content Slots Use inline SVG or icons as leading/trailing content within list items. ```svelte Profile Settings ``` ### Submenu via Menu Snippet Provide a `menu` snippet to show a more-options button with a dropdown. ```svelte Document A {#snippet menu()} edit()}>Edit duplicate()}>Duplicate remove()}>Delete {/snippet} ``` ### Active State Force a selected/active appearance on an item. ```svelte Currently Selected Another Item ``` ### Disabled Item ```svelte Unavailable Action Available Action ``` ## Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `disabled` | `boolean` | `false` | Disable interaction | | `active` | `boolean` | `false` | Force active/selected appearance | | `loading` | `boolean` | `undefined` | Show the loading spinner on the action row manually. Leave unset to let a promise-returning `onclick` drive it | | `loading_success` | `boolean` | `false` | For the manual `loading` path: flash a success checkmark when `loading` goes `true` → `false`. The promise path shows it automatically on resolve | | `href` | `string` | - | Render as an anchor link | | `target` | `'_self' \| '_blank' \| '_parent' \| '_top'` | - | Link target attribute | | `menu` | `Snippet` | - | Submenu content (renders a more-options button) | | `popover_placement` | `Placement` | `'bottom-end'` | Submenu popover position | | `popover_close_on_inside_click` | `boolean` | `false` | Close submenu on inside click | | `id` | `string` | auto | Element ID | | `class` | `string` | `''` | Additional CSS classes | | `style` | `string` | `''` | Additional inline styles | | `children` | `Snippet` | - | Main content | ## Events | Event | Detail | Description | |-------|--------|-------------| | `onclick` | `(e: MouseEvent) => void \| Promise` | Click handler; return a Promise for automatic spinner + success-checkmark feedback | | `onchange` | `(value: boolean) => void` | Called when selection state changes (radio/checkbox modes) | ## Accessibility - Renders the appropriate interactive element based on the parent List type: ``, ``, ``, or plain content - `aria-selected` / `aria-checked` applied for selection states - `aria-disabled` set on disabled anchor elements - Keyboard navigation handled by the parent List - Focus indicators via `focus-visible` - Ripple feedback attachment for tactile click response --- # QR > A QR code generator component that renders scannable codes as crisp SVGs with customizable colors, logo overlay, and download support. ## Import ```svelte import { QR } from '@delightstack/components'; ``` ## Basic Usage ```svelte ``` ## Examples ### Custom Size and Colors ```svelte ``` ### Rounded Modules ```svelte ``` ### Logo Overlay When a `logo` is provided, the error correction level is automatically upgraded to `'H'` to ensure scannability despite covered modules. ```svelte ``` ### High Error Correction Use level `'H'` for environments where the QR code may be partially obscured or damaged. ```svelte ``` ### Downloadable The QR component exposes a `triggerDownload(filename?)` method so consumers can wire up their own download button. ```svelte qr_ref.triggerDownload()}>Download PNG ``` ### Skeleton Loading ```svelte ``` ## Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `value` | `string` | - | Data to encode (URL, text, etc.). May be assigned later — pair with `skeleton` to show a placeholder until it arrives | | `size` | `number` | `200` | Size in pixels (width and height) | | `level` | `'L' \| 'M' \| 'Q' \| 'H'` | `'M'` | Error correction level | | `foreground` | `string` | `'#000000'` | Module (dark) color | | `background` | `string` | `'#ffffff'` | Background (light) color | | `margin` | `number` | `4` | Quiet zone in modules around the QR code | | `logo` | `string` | - | Center logo image URL | | `logo_size` | `number` | `0.25` | Logo size as a fraction of QR size (0 to 1) | | `rounded` | `boolean` | `false` | Round module corners | | `downloadable` | `boolean` | `false` | Show a download button | | `download_filename` | `string` | `'qr-code'` | Filename for the downloaded PNG (without extension) | | `skeleton` | `boolean` | `false` | Show a skeleton while `value` is not yet available; it dismisses itself as soon as the code renders | | `id` | `string` | auto | Element ID | | `class` | `string` | `''` | Additional CSS classes | ## Error Correction Levels | Level | Recovery | Use Case | |-------|----------|----------| | `L` | ~7% | Clean environments, maximum data capacity | | `M` | ~15% | General use (default) | | `Q` | ~25% | Moderate damage expected | | `H` | ~30% | Required when using logo overlay, harsh environments | ## Accessibility - SVG element has `role="img"` with an `aria-label` describing the encoded content (e.g., "QR code for https://example.com") - Download button has `aria-label="Download QR code as PNG"` - Skeleton state has `aria-label="Loading QR code"` - Respects `prefers-reduced-motion` for shimmer animations --- # SplitPane > A resizable split view container that divides space between two panes with drag, keyboard, snap, and collapse support. ## Import ```svelte import { SplitPane } from '@delightstack/components'; ``` ## Basic Usage ```svelte {#snippet first()}
Left Pane
{/snippet} {#snippet second()}
Right Pane
{/snippet} ``` ## Examples ### Sidebar Layout A horizontal split with constrained sidebar size and snap points. ```svelte {#snippet first()} {/snippet} {#snippet second()}
Content
{/snippet} ``` ### Vertical Split Stack panes top and bottom instead of left and right. ```svelte {#snippet first()}
Editor
{/snippet} {#snippet second()}
Terminal
{/snippet} ``` ### Collapsible Panes Double-click the divider to collapse the smaller pane. An expand button appears on the collapsed edge. ```svelte {#snippet first()}
First Pane
{/snippet} {#snippet second()}
Second Pane
{/snippet} ``` ### Nested Three-Pane Layout Combine multiple SplitPanes for complex layouts. ```svelte {#snippet first()}
File Tree
{/snippet} {#snippet second()} {#snippet first()}
Editor
{/snippet} {#snippet second()}
Output
{/snippet} {/snippet} ``` ### Snap Points The divider snaps to specified percentage positions during drag. ```svelte {#snippet first()}
Pane A
{/snippet} {#snippet second()}
Pane B
{/snippet} ``` ## Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `vertical` | `boolean` | `false` | Vertical split (top/bottom) instead of horizontal (left/right) | | `size` | `number` | `50` | First pane size as a percentage (bindable) | | `min_size` | `number` | `10` | Minimum first pane size (%) | | `max_size` | `number` | `90` | Maximum first pane size (%) | | `snap` | `number[]` | `[]` | Snap points as percentages | | `snap_threshold` | `number` | `3` | Distance in % to trigger snap | | `collapsible` | `boolean` | `false` | Allow collapsing panes | | `collapsed` | `'first' \| 'second' \| null` | `null` | Which pane is collapsed (bindable) | | `id` | `string` | auto | Element ID | | `class` | `string` | `''` | Additional CSS classes | | `first` | `Snippet` | - | First pane content | | `second` | `Snippet` | - | Second pane content | ## Events | Event | Detail | Description | |-------|--------|-------------| | `onresize` | `{ size: number }` | Fired when pane size changes | | `oncollapse` | `{ pane: 'first' \| 'second' \| null }` | Fired when a pane is collapsed or expanded | ## Keyboard Navigation The divider is focusable and supports the following keyboard controls: | Key | Action | |-----|--------| | Arrow Left / Arrow Up | Decrease first pane size by 1% | | Arrow Right / Arrow Down | Increase first pane size by 1% | | Shift + Arrow | Adjust by 5% | | Home | Set to `min_size` | | End | Set to `max_size` | | Enter | Toggle collapse of the smaller pane (when `collapsible`) | ## Accessibility - Divider has `role="separator"` with `aria-orientation` matching the layout direction - `aria-valuenow`, `aria-valuemin`, and `aria-valuemax` reflect the current pane size - `aria-label="Resize panes"` on the divider - Collapsed panes have `aria-hidden="true"` - Expand buttons have descriptive `aria-label` attributes - Focus indicator visible on the divider via `focus-visible` - Touch support with `touch-action: none` on the divider - Respects `prefers-reduced-motion` for collapse transitions --- # Stat > A component for displaying key metrics with optional labels, icons, change indicators, and animated number display. ## Import ```svelte import { Stat } from '@delightstack/components'; ``` ## Basic Usage ```svelte ``` ## Examples ### With Change Indicator Positive changes show a green up-arrow, negative changes show a red down-arrow. ```svelte ``` ### With Icon Pass any Svelte component as the `icon` prop. ```svelte ``` ### Size Variants Four sizes are available for different contexts. ```svelte ``` ### Horizontal Layout ```svelte ``` ### Override Trend Direction When a decrease is positive (e.g., bug count going down), override the trend color. ```svelte ``` ### Skeleton Loading ```svelte ``` ## Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `value` | `string \| number` | required | Main statistic to display | | `label` | `string` | - | Descriptive label | | `icon` | `Component` | - | Leading icon component | | `change` | `number` | - | Percentage change from previous period | | `change_label` | `string` | - | Description for the change (e.g., "vs last month") | | `trend` | `'up' \| 'down' \| 'neutral'` | auto | Override trend direction (auto-detected from `change`) | | `size` | `'0' \| '1' \| '2' \| '3'` | `'1'` | Component size | | `horizontal` | `boolean` | `false` | Horizontal layout instead of vertical | | `animated` | `boolean` | `true` | Animate numeric values via the Counter component | | `skeleton` | `boolean` | `false` | Show loading skeleton | | `id` | `string` | auto | Element ID | | `class` | `string` | `''` | Additional CSS classes | ## Size Reference | Size | Value Font | Label Font | Use Case | |------|-----------|-----------|----------| | `'0'` | 20px | 11px | Dense dashboards | | `'1'` | 28px | 13px | Cards, summaries | | `'2'` | 40px | 15px | Hero stats | | `'3'` | 56px | 17px | Landing pages | ## Accessibility - The stat value uses `aria-live="polite"` so screen readers announce value changes - Change indicator includes an `aria-label` with direction and value (e.g., "increased by 12.5 percent, vs last month") - Trend direction is communicated via text, not just color - The arrow icon is `aria-hidden="true"` since the text conveys the information - Respects `prefers-reduced-motion` for skeleton shimmer animations --- # Table > A full-featured data table with sorting, pagination, row selection, inline cell editing, custom cell rendering, column resizing, row grouping, expandable rows, and CSV/JSON export. ## Import ```svelte import { Table } from '@delightstack/components'; import type { Column } from '@delightstack/components'; ``` ## Basic Usage ```svelte ``` ## Examples ### Sortable Columns Mark columns as `sortable` and bind the sort state. ```svelte ``` ### Custom Cell Rendering Use Svelte snippets to render custom cell content. ```svelte {#snippet statusCell({ value })} {value} {/snippet} {#snippet actionsCell({ row })} editUser(row)}>Edit {/snippet} ``` ### Row Selection with Checkboxes Enable `selectable` to show checkboxes. Supports shift-click range selection. ```svelte ``` ### Striped and Dense ```svelte ``` ### Expandable Rows ```svelte {#snippet rowDetail(row)}

Details for {row.name}: {row.bio}

{/snippet} ``` ### Virtual Scrolling Set `virtual_scroll` to render only the rows near the viewport, so the table stays fast with thousands of rows. Pass `true` for sensible defaults, or an options object to configure it. Row heights are auto-measured; sorting, selection, striping, and row clicks all work as usual. Virtualization applies to the flat data path — `group_by` tables render normally. ```svelte ``` #### Options `virtual_scroll` accepts `true` (defaults), `false` (off), or an options object: | Option | Type | Default | Description | |--------|------|---------|-------------| | `row_height` | `number` | auto | Fixed row height in px (auto-measured when omitted) | | `overscan` | `number` | `8` | Extra rows rendered above/below the viewport | | `scroller` | `'container' \| 'parent' \| 'window' \| string \| HTMLElement` | `'container'` | Which element scrolls | | `max_height` | `string \| number` | `420px` | Viewport height — **only** for the `'container'` scroller | #### Choosing the scroll container By default the table provides its own scroll frame (`scroller: 'container'`), bounded by `max_height`. To virtualize against an outer scrollbar instead, set `scroller`: ```svelte
``` For `'parent'`, `'window'`, and custom scrollers the table renders inline (no inner scroll frame) and `max_height` is ignored — the chosen element owns the scroll height. ### Pagination Add the `pagination` flag and the Table pages your data for you — 10 rows per page with a numbered pager and a "Showing X–Y of Z" summary beneath the table. Sorting, selection, and inline editing all work across pages (selection keys off each row's position in the full `data`, not the visible page). That's the whole API for the common case: ```svelte ``` Bind `page` and `page_size` to read or drive the current page, and pass a config object to tune the pager. Providing `page_size_options` adds a rows-per-page selector. ```svelte ``` #### Options `pagination` accepts `true` (defaults), `false` (off), or a config object: | Option | Type | Default | Description | |--------|------|---------|-------------| | `variant` | `'default' \| 'simple' \| 'compact'` | `'default'` | Pager style — a numbered pager, `Prev · Page X of Y · Next`, or `‹ X / Y ›` | | `position` | `'top' \| 'bottom' \| 'both'` | `'bottom'` | Where the pager sits relative to the table | | `align` | `'start' \| 'center' \| 'end' \| 'between'` | `'between'` | `'between'` splits the summary left / controls right; the others align the whole pager | | `show_info` | `boolean` | `true` | Show the "Showing X–Y of Z" summary | | `page_size_options` | `number[]` | - | Providing it adds a rows-per-page selector with these options | | `total_items` | `number` | - | Total row count for **server-side** paging (see below) | | `sibling_count` | `number` | `1` | Sibling pages shown either side of the current page | | `boundary_count` | `number` | `1` | Pages always shown at the start and end | | `size` | `'0' \| '1' \| '2' \| '3'` | `'1'` | Pager button size | #### Server-side pagination By default the Table slices `data` itself (client-side). For large datasets you fetch a page at a time: set `total_items` to the full row count and feed the Table only the current page — it won't slice. Bind `page`/`page_size` (or use `onpagechange`) to fetch when they change. ```svelte ``` In server mode, sorting via the built-in headers only reorders the current page; use the [`onsort`](#events) callback to sort on the server instead. While pagination is active, `virtual_scroll` and `reorderable` are disabled (the page slice already bounds how many rows render). ### Reorderable Rows Set `reorderable` to let users drag rows into a new order. On desktop, press and drag a row; on touch, hold a row until it lifts, then drag. The new order is handed to `onreorder` only after the drop animation finishes, so assigning it to your data never interrupts the animation. Works with `selectable` (drag the whole selection at once) and `virtual_scroll`. Give each row a stable [`row_key`](#props) (a field name or `(row) => id`) when combining `reorderable` with `selectable`. Without it, rows are keyed by their position, so committing a new order makes Svelte re-key every row by index — and the selection checkmarks redraw (a brief flash) even though the same rows stay selected. With a `row_key`, Svelte moves each row's DOM node to follow its data, so the checkmarks ride along untouched. ```svelte (users = e.newData)} /> ``` ### Resizable Columns Set `resizable` to let users drag any column border to resize it — in the header **or anywhere down the body rows**. The visible divider stays a crisp 1px line, but the drag target is widened with a few px of slack so you grab the border without having to land on the hairline. Bring the pointer to a border and the whole column boundary previews as an accent line, head to foot; while you drag, it lights up fully so it's clear what's moving. It works with mouse, touch, and pen. The header border is also a focusable separator: **arrow keys** nudge the width (hold **Shift** for a larger step) and **Home** (or **Enter**) auto-fits. **Double-click** a border to reset that column to its content-driven width, and **Escape** mid-drag cancels. Each committed change fires `oncolumnresize` with the column key and new pixel width. ```svelte console.log(e.column, e.width)} /> ``` ### Editable Cells Set `editable` to turn the table into a spreadsheet-style editor. Click a cell (or **Tab** into the grid) and it opens an inline editor immediately. Hover highlights the **cell** rather than the whole row, signalling that each cell is clickable. **Keyboard:** **↑ / ↓** move between rows, **Tab / Shift+Tab** move between cells (wrapping rows), **Enter** saves and moves down, **← / →** move the caret and jump to the neighbouring cell at the text edge, and **Esc** reverts. **Ctrl/⌘+Z** and **Ctrl/⌘+Y** undo and redo edits. Each column configures its own editor and callbacks: - **`editor`** — `'text'` (default), `'number'`, `'select'`, `'boolean'`, `'date'`, or a custom editor `Snippet`. - **`onedit`** — fires when a cell is committed (Enter or blur) and the value changed. If it returns a **Promise**, the cell shows a loading spinner while it resolves (then a success check); if it rejects, the cell keeps your value and shows an error ring so you can retry — just like the `Button` component. - **`oninput`** — fires on every keystroke (not a commit). - **`options` / `onautocomplete`** — show an autocomplete popover (like `Input`). `options` is a static list filtered by the current value; `onautocomplete(ctx)` returns results (or a Promise of them) dynamically, debounced 300ms. - **`validate`** — return an error message to block the commit and ring the cell. - **`parse` / `format`** — convert between the editor string and your stored value. The table is **controlled**: editing fires `onedit` and your handler updates `data` (an optimistic value is shown while an async save runs). Editing composes with `selectable`, `reorderable` (a drag grip appears so a cell click still edits), `virtual_scroll`, `sortable`, and `group_by`. Opt a column out with `editable: false`. ```svelte new Promise((r) => setTimeout(() => { set(row, 'name', value); r(); }, 800)), }, { key: 'age', label: 'Age', width: '90px', align: 'right', editor: 'number', validate: (v) => (v >= 0 && v <= 120 ? null : 'Enter 0–120'), onedit: ({ row, value }) => set(row, 'age', value), }, { key: 'role', label: 'Role', editor: 'select', options: ['Admin', 'Editor', 'Viewer'], onedit: ({ row, value }) => set(row, 'role', value), }, { key: 'active', label: 'Active', width: '90px', align: 'center', editor: 'boolean', onedit: ({ row, value }) => set(row, 'active', value), }, ]} /> ``` ### Skeleton Loading ```svelte ``` ## Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `data` | `T[]` | `[]` | Array of row data | | `columns` | `Column[]` | `[]` | Column definitions | | `row_key` | `string \| ((row: T) => string \| number)` | - | Stable per-row identity for the keyed `{#each}`. A field name or function. Lets Svelte move row DOM nodes (so selection survives a reorder commit without redrawing) instead of re-keying by position. Recommended for `reorderable` + `selectable` | | `sort_by` | `string` | - | Current sort column key (bindable) | | `sort_direction` | `'asc' \| 'desc'` | `'asc'` | Sort direction (bindable) | | `selectable` | `boolean` | `false` | Enable row selection with checkboxes | | `selected` | `T[]` | `[]` | Selected rows (bindable) | | `striped` | `boolean` | `false` | Alternating row background colors | | `dense` | `boolean` | `false` | Compact cell padding | | `comfortable` | `boolean` | `false` | Relaxed cell padding | | `sticky_header` | `boolean` | `true` | Sticky header on vertical scroll | | `resizable` | `boolean` | `false` | Allow column width resizing by dragging any column border, in the header or body cells (see [Resizable Columns](#resizable-columns)) | | `expandable` | `boolean` | `false` | Enable row expansion | | `reorderable` | `boolean` | `false` | Enable drag-to-reorder rows (see [Reorderable Rows](#reorderable-rows)) | | `virtual_scroll` | `boolean \| VirtualScrollOptions` | `false` | Window rows for large datasets — `true` for defaults, or an options object (see [Virtual Scrolling](#virtual-scrolling)) | | `pagination` | `boolean \| PaginationConfig` | `false` | Page the data — `true` for defaults (10/page), or a config object (see [Pagination](#pagination)) | | `page` | `number` | `1` | Current page, 1-based (bindable) | | `page_size` | `number` | `10` | Rows per page (bindable) | | `group_by` | `string` | - | Column key to group rows by | | `editable` | `boolean` | `false` | Enable inline cell editing (see [Editable Cells](#editable-cells)) | | `exportable` | `boolean` | `false` | Enable CSV/JSON export functionality | | `skeleton` | `boolean` | `false` | Show loading skeleton rows | | `skeleton_count` | `number` | `5` | Number of skeleton rows | | `id` | `string` | auto | Element ID | | `class` | `string` | `''` | Additional CSS classes | | `empty` | `Snippet` | - | Custom empty state content | | `expanded_row` | `Snippet<[T]>` | - | Content for expanded rows | ## Events | Event | Detail | Description | |-------|--------|-------------| | `onsort` | `{ column: string, direction: 'asc' \| 'desc' }` | Sort changed (use for server-side sorting) | | `onselect` | `{ selected: T[] }` | Selection changed | | `onrowclick` | `{ row: T, index: number }` | Row clicked | | `oncolumnresize` | `{ column: string, width: number }` | Column resized | | `onreorderstart` | `{ from: number[] }` | A reorder drag began (rows lifted) | | `ondrop` | `{ from: number[], to: number }` | Rows released — fires when the drop animation begins | | `onreorder` | `{ from: number[], to: number, oldData: T[], newData: T[] }` | Reorder committed — fires after the drop animation finishes; assign `newData` to your `data` | | `oncelledit` | `CellEditContext` | Table-wide commit handler — fires when a cell with no own `column.onedit` is edited. May return a Promise (→ in-cell spinner) | | `oncellinput` | `CellEditContext` | Table-wide per-keystroke handler — fallback when a column has no own `column.oninput` | | `onpagechange` | `{ page: number, page_size: number }` | Page or page size changed — use for server-side paging (fires for client-side too) | Most editing callbacks live on the column (`onedit`, `oninput`, `onautocomplete`, `validate`); `oncelledit` / `oncellinput` are table-wide fallbacks for a single shared handler. See [Editable Cells](#editable-cells). ## Types The `Column` interface defines column configuration: ```typescript interface Column { key: string; label: string; sortable?: boolean; width?: string; minWidth?: string; align?: 'left' | 'center' | 'right'; cell?: Snippet<[{ value: unknown; row: T; index: number }]>; header?: Snippet<[{ column: Column }]>; // Inline editing (active only when the Table's `editable` prop is on) editable?: boolean | ((row: T) => boolean); // per-column override / per-cell predicate editor?: 'text' | 'number' | 'select' | 'boolean' | 'date' | Snippet<[CellEditorContext]>; // a Snippet is a custom editor options?: CellOption[] | string[]; // static autocomplete / select options onautocomplete?: (ctx: CellAutocompleteContext) => CellOption[] | Promise; // dynamic options (debounced 300ms) oninput?: (ctx: CellEditContext) => void; // per keystroke onedit?: (ctx: CellEditContext) => void | Promise; // commit (Promise → spinner) validate?: (value: unknown, row: T, index: number) => string | null | Promise; // error message blocks the commit parse?: (raw: string, row: T) => unknown; // editor string → stored value format?: (value: unknown, row: T) => string; // stored value → display string placeholder?: string; } interface CellOption { value: string; label?: string; description?: string; disabled?: boolean; } interface CellEditContext { value: unknown; // the committed (parsed) value, or the live value for oninput previous: unknown; // the prior stored value row: T; index: number; column: Column; key: string; // the edited column's key } ``` The `virtual_scroll` prop is `boolean | VirtualScrollOptions`: ```typescript type VirtualScroller = | 'container' // the Table's own scroll frame (default) | 'parent' // the Table's direct parent element | 'window' // the page / document | string // a CSS selector for a scrollable ancestor | HTMLElement; interface VirtualScrollOptions { row_height?: number; // fixed row height in px (auto-measured when omitted) overscan?: number; // extra rows above/below the viewport (default 8) scroller?: VirtualScroller; // which element scrolls (default 'container') max_height?: string | number; // viewport height — only for the 'container' scroller } ``` The `pagination` prop is `boolean | PaginationConfig`: ```typescript interface PaginationConfig { variant?: 'default' | 'simple' | 'compact'; // pager style (default 'default') position?: 'top' | 'bottom' | 'both'; // pager placement (default 'bottom') align?: 'start' | 'center' | 'end' | 'between'; // pager alignment (default 'between') show_info?: boolean; // show the "Showing X–Y of Z" summary (default true) page_size_options?: number[]; // providing it adds a rows-per-page selector total_items?: number; // total count for server-side paging (Table won't slice) sibling_count?: number; // sibling pages around the current page (default 1) boundary_count?: number; // pages always shown at each end (default 1) size?: '0' | '1' | '2' | '3'; // pager button size (default '1') } ``` ## Accessibility - Uses semantic ``, ``, ``, `

`, and `

` elements - `aria-sort` on sortable column headers indicates current sort state - Checkbox selection uses proper `` with `aria-label` - Row expansion uses `aria-expanded` on toggle buttons - Keyboard navigation: Tab through interactive elements, Enter to sort columns - Header checkbox has `aria-label="Select all rows"` - Respects `prefers-reduced-motion` for skeleton shimmer and chevron animations --- # Timeline > A chronological event display for vertical or horizontal timelines with scroll-reveal animations, status markers, and on-demand loading. ## Import ```svelte import { Timeline, TimelineItem } from '@delightstack/components'; ``` The `TimelineItem` is re-exported from the `Timeline` module. Both `Timeline` and `TimelineItem` are backed by the same Svelte component -- when used inside a Timeline context, it renders as an item; at the top level, it renders as the container. ## Basic Usage ```svelte First step completed. Currently in progress. ``` ## Examples ### Order Tracking ```svelte Your order has been confirmed. Package picked up by carrier. Expected delivery today. ``` ### Horizontal Process Steps ```svelte ``` ### Alternating Sides Events alternate between left and right in vertical mode. ```svelte Description A Description B Description C ``` ### On-Demand Loading Load more events as the user scrolls near the end of the timeline. ```svelte {#each events as event} {event.description} {/each} ``` ### Interactive Items Give an item an `onclick` and/or `href` to make it clickable (mirroring ``). Interactive items get a pointer cursor, a hover tint, a ripple, and a press effect; items without either stay static. ```svelte (selected = 'Order Confirmed')}> Tap to view the confirmation. ``` ### Async Actions Return a promise from `onclick` and the step's marker drives its own loading feedback (just like ``): a spinner appears in the circle if the work outlasts ~100ms, stays visible long enough not to blink, then a brief success check confirms a resolve. Re-clicks are ignored while it's in flight. ```svelte Compiled successfully. All checks green. Click to deploy — the marker shows a spinner while it runs, then a check. ``` ### Custom Marker Color ```svelte A red-themed event marker. ``` ### Skeleton Loading ```svelte … ``` ## Timeline Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `horizontal` | `boolean` | `false` | Horizontal layout instead of vertical | | `alternate` | `boolean` | `false` | Alternate items left/right (vertical) or top/bottom (horizontal) | | `pending` | `boolean` | `false` | Show a pending/loading indicator at the end | | `dense` | `boolean` | `false` | Compact event spacing | | `comfortable` | `boolean` | `false` | Relaxed event spacing | | `animate` | `boolean` | `true` | Play the entrance reveal + active pulse. Set `false` for a fully static timeline. (The reveal is also skipped automatically when content replaces a skeleton.) | | `skeleton` | `boolean` | `false` | Show loading skeleton | | `skeleton_count` | `number` | `3` | Number of skeleton items | | `id` | `string` | auto | Element ID | | `class` | `string` | `''` | Additional CSS classes | | `children` | `Snippet` | - | TimelineItem children | ## Timeline Events | Event | Detail | Description | |-------|--------|-------------| | `onloadmore` | `() => void \| Promise` | Called when scrolling near the end for on-demand loading | ## TimelineItem Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `date` | `Date \| string` | - | Event timestamp | | `title` | `string` | `''` | Event title | | `icon` | `Component` | - | Marker icon component | | `color` | `string` | - | Marker color override (CSS color value) | | `status` | `'complete' \| 'active' \| 'pending'` | - | Event status for marker styling | | `href` | `string` | - | Makes the item a link (renders an ``). Enables hover/ripple/press effects | | `onclick` | `(event) => void \| Promise` | - | Click handler. Makes the item interactive (hover/ripple/press effects). Return a promise to show a loading spinner in the marker, then a success check on resolve | | `target` | `'_self' \| '_blank' \| '_parent' \| '_top'` | - | Link target (used with `href`) | | `children` | `Snippet` | - | Event body content | ## Types The Timeline exports a `TimelineContext` interface for internal context: ```typescript interface TimelineContext { horizontal: boolean; alternate: boolean; dense: boolean; comfortable: boolean; animate: boolean; reveal: boolean; register: () => number; } ``` ## Accessibility - Timeline renders as an ordered list (` `) with `role="list"` for semantic structure - Dates use `` elements with `datetime` attributes - Status is communicated visually through marker styling (a checked node for complete, a glowing/pulsing node for active, a hollow ring for pending) - Scroll-reveal animations respect `prefers-reduced-motion` -- items appear without animation when reduced motion is preferred - The load-more sentinel and skeleton items use `aria-hidden="true"` - Horizontal mode supports native touch/swipe scrolling with CSS snap points --- # Tree > A hierarchical data display component for folder structures and nested data with expand/collapse, checkboxes, drag-and-drop, lazy loading, and search filtering. ## Import ```svelte import { Tree } from '@delightstack/components'; import type { TreeNode, FlatTreeNode } from '@delightstack/components'; ``` ## Basic Usage ```svelte ``` ## Examples ### Selectable with Icons ```svelte ``` ### Checkbox Selection Parent checkboxes reflect children state with an indeterminate state when partially selected. Checking a parent checks all children. ```svelte ``` ### Flat Data with Parent IDs The component automatically detects flat data (arrays with `parentId` properties) and builds the tree structure internally. ```svelte ``` ### Search/Filter Nodes matching the filter term are highlighted. Non-matching branches without matching descendants are hidden, and parent nodes auto-expand to reveal matches. ```svelte ``` ### Drag-and-Drop Enable drag-and-drop reordering between nodes. ```svelte { updateTree(node, target, position); }} /> ``` ### Lazy Loading Load children on demand when a node is expanded. A loading spinner replaces the chevron during the fetch. ```svelte { return await fetchChildren(node.id); }} /> ``` ### Connecting Lines ```svelte ``` ### Custom Node Content ```svelte {#snippet customNode({ node, level })} {node.label} {#if node.data?.badge} {node.data.badge} {/if} {/snippet} ``` ### Density Use `dense` for compact node spacing or `comfortable` for relaxed spacing. The default sits between the two. ```svelte ``` ### Skeleton Loading ```svelte ``` ## Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `data` | `TreeNode[] \| FlatTreeNode[]` | required | Tree data (nested or flat with parent IDs) | | `selected` | `string[]` | `[]` | Selected node IDs (bindable) | | `expanded` | `string[]` | `[]` | Expanded node IDs (bindable) | | `selectable` | `boolean` | `false` | Enable node selection | | `multi_select` | `boolean` | `false` | Allow multiple selection | | `checkboxes` | `boolean` | `false` | Show checkboxes for selection | | `show_lines` | `boolean` | `false` | Show connecting lines between nodes | | `draggable` | `boolean` | `false` | Enable drag-and-drop reordering | | `filter` | `string` | - | Search/filter term to highlight and filter matches | | `dense` | `boolean` | `false` | Compact node spacing | | `comfortable` | `boolean` | `false` | Relaxed node spacing | | `skeleton` | `boolean` | `false` | Show loading skeleton | | `skeleton_count` | `number` | `5` | Number of skeleton nodes | | `skeleton_depth` | `number` | `2` | Nesting depth of skeleton nodes | | `id` | `string` | auto | Element ID | | `class` | `string` | `''` | Additional CSS classes | | `load_children` | `(node: TreeNode) => Promise` | - | Lazy load children on expand | | `node_content` | `Snippet<[{ node: TreeNode; level: number }]>` | - | Custom node content renderer | ## Events | Event | Detail | Description | |-------|--------|-------------| | `onselect` | `{ node: TreeNode, selected: string[] }` | Selection changed | | `onexpand` | `{ node: TreeNode, expanded: boolean }` | Node expanded or collapsed | | `ondrop` | `{ node: TreeNode, target: TreeNode, position: 'before' \| 'after' \| 'inside' }` | Node dropped after drag | ## Types ### TreeNode The nested tree data format: ```typescript interface TreeNode { id: string; label: string; icon?: Component; children?: TreeNode[]; disabled?: boolean; data?: unknown; } ``` ### FlatTreeNode The flat data format with parent references: ```typescript interface FlatTreeNode { id: string; parentId: string | null; label: string; icon?: Component; disabled?: boolean; data?: unknown; } ``` ## Keyboard Navigation | Key | Action | |-----|--------| | Arrow Down | Move focus to next visible node | | Arrow Up | Move focus to previous visible node | | Arrow Right | Expand focused node, or move to first child if already expanded | | Arrow Left | Collapse focused node, or move to parent if already collapsed | | Enter / Space | Select or toggle checkbox on focused node | | Home | Move focus to first visible node | | End | Move focus to last visible node | | * (asterisk) | Expand all siblings of the focused node | ## Accessibility - Container has `role="tree"`, each node has `role="treeitem"` - `aria-expanded` on expandable nodes - `aria-selected` on selectable nodes - `aria-level` indicating nesting depth - `aria-activedescendant` for focus management - `aria-multiselectable` when multiple selection is enabled - `aria-disabled` on disabled nodes - Full keyboard navigation with arrow keys, Home, End, Enter, Space - Expand/collapse animations respect `prefers-reduced-motion` - Search matches are highlighted with `` elements --- # Typewriter > An animated text component that simulates character-by-character typing with natural variation, smart punctuation pauses, and text cycling. ## Import ```svelte import { Typewriter } from '@delightstack/components'; ``` ## Basic Usage ```svelte ``` ## Examples ### Hero Section ```svelte ``` ### Cycling Through Multiple Texts When an array of strings is provided, the component types each one, backspaces, and types the next. Common prefixes are preserved during transitions. ```svelte We help you ``` ### Block Cursor Style A terminal-like block cursor for code snippets. ```svelte ``` ### Chat-Like Interface Fire a callback when typing completes. ```svelte showInput = true} /> {#if showInput} {/if} ``` ### Controlled Animation Pause and resume the animation programmatically. ```svelte isPaused = !isPaused}> {isPaused ? 'Resume' : 'Pause'} ``` ### Underscore Cursor ```svelte ``` ## Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `text` | `string \| string[]` | required | Text to type (single or array for cycling) | | `speed` | `number` | `50` | Base typing speed in milliseconds per character | | `delay` | `number` | `1000` | Delay before typing starts (ms) | | `loop` | `boolean` | `false` | Loop through texts continuously | | `pause_between` | `number` | `2000` | Pause between texts when cycling (ms) | | `cursor` | `'block' \| 'line' \| 'underscore' \| false` | `'line'` | Cursor style | | `cursor_blink` | `boolean` | `true` | Blink cursor when idle | | `delete_speed` | `number` | `30` | Backspace speed in milliseconds per character | | `paused` | `boolean` | `false` | Programmatically pause the animation | | `id` | `string` | auto | Element ID | | `class` | `string` | `''` | Additional CSS classes | ## Events | Event | Detail | Description | |-------|--------|-------------| | `onstart` | - | Typing started | | `oncomplete` | - | All text typed (or full cycle completed) | | `onloop` | `{ index: number }` | Loop iteration started | ## Natural Typing Behavior The component simulates human-like typing with several features: - **Variable speed**: Each character's delay is randomized around the base `speed` (80-120% of base) - **Micro-pauses**: 5% chance of a 2x speed pause to simulate thinking - **Smart punctuation pauses**: Periods, question marks, and exclamation marks add a 3x pause; commas add 1.8x; semicolons and colons add 2x - **Common prefix preservation**: When cycling between "I love coding" and "I love designing", only "coding" is deleted and "designing" is typed ## Accessibility - The component renders an `aria-label` on the outer `` containing the full text (or all texts joined for arrays) - The visual typing animation is wrapped in `aria-hidden="true"` so screen readers see the complete text immediately - When `prefers-reduced-motion` is active, the full text is displayed immediately with no character-by-character animation - The cursor blink animation is also disabled under reduced motion preferences --- # Callout > A highlighted information block for drawing attention to important content, supporting inline callouts and full-width banners. ## Import ```svelte import { Callout } from '@delightstack/components'; ``` ## Basic Usage ```svelte Your changes are automatically saved. ``` ## Examples ### Variants Use boolean props to set the visual variant. When none is set, the default `info` style is used. **Info (default)** ```svelte This is an informational callout. ``` **Success** ```svelte Your changes have been saved successfully. ``` **Warning** ```svelte This action cannot be undone. ``` **Error** ```svelte Failed to connect to the server. Please try again. ``` **Tip** ```svelte Press Cmd+K to open the command palette. ``` ### Dismissible Add `dismissible` to show a close button. Use `ondismiss` to handle the event. ```svelte {#if visible} (visible = false)}> You can use keyboard shortcuts to speed up your workflow. {/if} ``` ### Custom Icon and Action Override the default icon or add an action area using snippets. ```svelte {#snippet icon()} {/snippet} New feature available! Check out our latest update with improved performance. {#snippet action()} Learn more {/snippet} ``` ### Banner Mode Set `banner` for a full-width banner with solid background. Combine with `sticky` to pin it to the top on scroll. ```svelte {#if showBanner} showBanner = false}> We've updated our privacy policy. Please review the changes. {#snippet action()} Learn more {/snippet} {/if} Scheduled maintenance tonight at 11pm UTC. ``` ### Dense and Comfortable Spacing ```svelte Compact callout with less padding. Spacious callout with more padding. ``` ### Skeleton Loading ```svelte … ``` ## Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `success` | `boolean` | `false` | Success variant (green) | | `warning` | `boolean` | `false` | Warning variant (yellow/orange) | | `error` | `boolean` | `false` | Error variant (red) | | `tip` | `boolean` | `false` | Tip variant (accent/purple) | | `banner` | `boolean` | `false` | Full-width banner mode with solid background | | `title` | `string` | `''` | Optional heading text | | `dismissible` | `boolean` | `false` | Show close/dismiss button | | `sticky` | `boolean` | `false` | Stick to top on scroll (banner mode only) | | `dense` | `boolean` | `false` | Compact padding | | `comfortable` | `boolean` | `false` | Relaxed padding | | `skeleton` | `boolean` | `false` | Show loading skeleton state | | `id` | `string` | auto | Element ID | | `class` | `string` | `''` | Additional CSS classes | | `children` | `Snippet` | - | Main content | | `icon` | `Snippet` | - | Custom icon (overrides default variant icon) | | `action` | `Snippet` | - | Action area (button, link, etc.) | ## Events | Event | Detail | Description | |-------|--------|-------------| | `ondismiss` | `() => void` | Called when the dismiss button is clicked | ## Accessibility - Uses `role="alert"` for warning and error variants - Uses `role="status"` for info, success, and tip variants - Banner mode renders as a semantic `