## Pages ### accordion Collapsible sections component supporting single/multiple open items, keyboard navigation, smooth transitions, and browser search within collapsed content. ## Accordion Component Organizes content into collapsible sections. Supports single or multiple open items simultaneously. ### Structure - `Accordion.Root`: Container managing overall state - `Accordion.Item`: Individual collapsible section - `Accordion.Header`: Contains visible heading - `Accordion.Trigger`: Clickable element toggling visibility - `Accordion.Content`: Collapsible body content ### Basic Usage ```svelte Item 1 Title Collapsible content Item 2 Title Collapsible content ``` ### Key Features - **Single or Multiple Mode**: `type="single"` allows one open section; `type="multiple"` allows multiple - **Accessible**: Built-in ARIA attributes and keyboard navigation - **Smooth Transitions**: CSS variables or Svelte transitions support - **Flexible State**: Uncontrolled defaults or full control with bound values - **Disabled Items**: Set `disabled` prop on items - **Hidden Until Found**: `hiddenUntilFound` prop enables browser search within collapsed content - **Horizontal Orientation**: `orientation="horizontal"` for horizontal layouts ### State Management Two-way binding: ```svelte ``` Fully controlled with function binding: ```svelte ``` ### Reusable Components Item wrapper combining Item, Header, Trigger, and Content: ```svelte {title} {content} ``` Root wrapper rendering multiple items: ```svelte {#each items as item, i (item.title + i)} {/each} ``` Usage: ```svelte ``` ### Svelte Transitions Using `forceMount` and `child` snippet: ```svelte {#snippet child({ props, open })} {#if open}

Content with transition

{/if} {/snippet} ``` Reusable transition wrapper: ```svelte {#snippet child({ props, open })} {#if open}

{@render children?.()}

{/if} {/snippet} ``` ### Examples **Horizontal Cards** with image backgrounds and descriptions: ```svelte {#each items as item (item.id)} (value = item.id)}>

{item.title} {item.description}

{/each} ``` **Checkout Steps** with multi-step form: ```svelte Shipping Information

{ completedSteps.add("1"); activeStep = "2"; }}> Continue to Payment

Payment Method

{ completedSteps.add("2"); activeStep = "3"; }}> Continue to Review

Review Order

Order Summary

Product 1: $29.99

Product 2: $49.99

Shipping: $4.99

Total: $84.97

{ completedSteps.add("3"); activeStep = ""; }}> Place Order

``` ### API Reference **Accordion.Root** - `type` (required): 'single' | 'multiple' - `value` ($bindable): string[] | string - currently active item(s) - `onValueChange`: callback when value changes - `disabled`: boolean (default: false) - `loop`: boolean - loop through items (default: false) - `orientation`: 'vertical' | 'horizontal' (default: 'vertical') - `ref` ($bindable): HTMLDivElement - `children`: Snippet - `child`: Snippet with props Data attributes: `data-orientation`, `data-disabled`, `data-accordion-root` **Accordion.Item** - `disabled`: boolean (default: false) - `value`: string - unique identifier (auto-generated if not provided) - `ref` ($bindable): HTMLDivElement - `children`: Snippet - `child`: Snippet with props Data attributes: `data-state` ('open' | 'closed'), `data-disabled`, `data-orientation`, `data-accordion-item` **Accordion.Header** - `level`: 1 | 2 | 3 | 4 | 5 | 6 - heading level (default: 3) - `ref` ($bindable): HTMLDivElement - `children`: Snippet - `child`: Snippet with props Data attributes: `data-orientation`, `data-disabled`, `data-heading-level`, `data-accordion-header` **Accordion.Trigger** - `ref` ($bindable): HTMLButtonElement - `children`: Snippet - `child`: Snippet with props Data attributes: `data-orientation`, `data-disabled`, `data-accordion-trigger` **Accordion.Content** - `forceMount`: boolean - always mount in DOM (default: false) - `hiddenUntilFound`: boolean - use `hidden="until-found"` for browser search (default: false) - `ref` ($bindable): HTMLDivElement - `children`: Snippet - `child`: Snippet with props and `open` state Data attributes: `data-orientation`, `data-disabled`, `data-accordion-content` CSS variables: `--bits-accordion-content-height`, `--bits-accordion-content-width` ### alert-dialog Modal dialog component with compound sub-components; supports state binding, focus management, scroll locking, escape/outside interaction customization, and nested dialogs with depth tracking. ## Alert Dialog Modal window for presenting content or seeking user input without navigation. Built from compound sub-components. ### Structure - **Root**: Manages state and context - **Trigger**: Opens/closes dialog - **Portal**: Renders outside DOM hierarchy - **Overlay**: Backdrop behind dialog - **Content**: Main dialog content - **Title**: Dialog title - **Description**: Additional context - **Cancel**: Closes without action - **Action**: Confirms action ### Basic Usage ```svelte Open Dialog Confirm Action Are you sure? Cancel Confirm ``` ### Reusable Component Pattern ```svelte {buttonText} {@render title()} {@render description()} {@render children?.()} Cancel Confirm ``` Usage: ```svelte {#snippet title()}Delete your account{/snippet} {#snippet description()}This action cannot be undone.{/snippet} ``` ### State Management **Two-way binding:** ```svelte ``` **Fully controlled (function binding):** ```svelte ``` ### Focus Management **Focus trap** (enabled by default): ```svelte ``` **Open auto-focus** (defaults to Content): ```svelte { e.preventDefault(); nameInput?.focus(); }}> ``` **Close auto-focus** (defaults to trigger): ```svelte Open { e.preventDefault(); nameInput?.focus(); }}> ``` ### Advanced Behaviors **Scroll lock** (enabled by default): ```svelte ``` **Escape key handling:** - `escapeKeydownBehavior`: `'close'` (default), `'ignore'`, `'defer-otherwise-close'`, `'defer-otherwise-ignore'` - `onEscapeKeydown`: Custom callback ```svelte { e.preventDefault(); /* custom logic */ }}> ``` **Outside interaction handling:** - `interactOutsideBehavior`: `'ignore'` (default), `'close'`, `'defer-otherwise-close'`, `'defer-otherwise-ignore'` - `onInteractOutside`: Custom callback ```svelte { e.preventDefault(); /* custom logic */ }}> ``` ### Nested Dialogs Data attributes for styling: - `data-nested-open`: Present when nested dialogs are open - `data-nested`: Present on nested dialog itself CSS variables: - `--bits-dialog-depth`: Nesting depth (0 for root, 1 for first nested, etc.) - `--bits-dialog-nested-count`: Number of open nested dialogs ```svelte ``` ### Form Submission ```svelte Confirm your action Are you sure? ``` **Note:** If using AlertDialog within a form, disable Portal to keep content inside form element. ### Key Features - Compound component structure for flexibility - ARIA-compliant with keyboard navigation - Portal support for proper stacking - Managed focus with customization - Controlled and uncontrolled state support - Scroll locking, escape key handling, outside interaction customization - Nested dialog support with depth tracking ### API Reference **AlertDialog.Root** - `open` ($bindable): boolean, default false - `onOpenChange`: (open: boolean) => void - `onOpenChangeComplete`: (open: boolean) => void - `children`: Snippet **AlertDialog.Trigger** - `ref` ($bindable): HTMLButtonElement - `children`: Snippet - `child`: Snippet with props - Data: `data-state` ('open'|'closed'), `data-alert-dialog-trigger` **AlertDialog.Content** - `onInteractOutside`: (event: PointerEvent) => void - `onFocusOutside`: (event: FocusEvent) => void - `interactOutsideBehavior`: 'close'|'ignore'|'defer-otherwise-close'|'defer-otherwise-ignore', default 'close' - `onEscapeKeydown`: (event: KeyboardEvent) => void - `escapeKeydownBehavior`: 'close'|'ignore'|'defer-otherwise-close'|'defer-otherwise-ignore', default 'close' - `onOpenAutoFocus`: (event: Event) => void - `onCloseAutoFocus`: (event: Event) => void - `trapFocus`: boolean, default true - `forceMount`: boolean, default false - `preventOverflowTextSelection`: boolean, default true - `preventScroll`: boolean, default true - `restoreScrollDelay`: number, default 0 - `ref` ($bindable): HTMLDivElement - `children`: Snippet - `child`: Snippet with props and open state - Data: `data-state`, `data-alert-dialog-content`, `data-nested-open`, `data-nested` - CSS: `--bits-dialog-depth`, `--bits-dialog-nested-count` **AlertDialog.Overlay** - `forceMount`: boolean, default false - `ref` ($bindable): HTMLDivElement - `children`: Snippet - `child`: Snippet with props and open state - Data: `data-state`, `data-alert-dialog-overlay`, `data-nested-open`, `data-nested` - CSS: `--bits-dialog-depth`, `--bits-dialog-nested-count` **AlertDialog.Portal** - `to`: Element|string, default document.body - `disabled`: boolean, default false - `children`: Snippet **AlertDialog.Action** - `ref` ($bindable): HTMLButtonElement - `children`: Snippet - `child`: Snippet with props - Data: `data-alert-dialog-action` - Note: Does not close dialog by default **AlertDialog.Cancel** - `ref` ($bindable): HTMLButtonElement - `children`: Snippet - `child`: Snippet with props - Data: `data-alert-dialog-cancel` **AlertDialog.Title** - `level`: 1|2|3|4|5|6, default 3 (sets aria-level) - `ref` ($bindable): HTMLDivElement - `children`: Snippet - `child`: Snippet with props - Data: `data-alert-dialog-title` **AlertDialog.Description** - `ref` ($bindable): HTMLDivElement - `children`: Snippet - `child`: Snippet with props - Data: `data-alert-dialog-description` ### aspect-ratio AspectRatio.Root component with ratio prop (number, default 1), bindable ref, children/child snippets, data-aspect-ratio-root attribute. ## Aspect Ratio Component Maintains a specified aspect ratio for content. ### Basic Usage ```svelte import { AspectRatio } from "bits-ui"; an abstract painting

``` ### Architecture - **Root**: Contains the aspect ratio logic ### Reusable Component Pattern ```svelte // MyAspectRatio.svelte import { AspectRatio, type WithoutChildrenOrChild } from "bits-ui"; let { src, alt, ref = $bindable(null), imageRef = $bindable(null), ...restProps }: WithoutChildrenOrChild & { src: string; alt: string; imageRef?: HTMLImageElement | null; } = $props(); ``` Usage: ```svelte ``` ### API Reference **AspectRatio.Root** | Property | Type | Description | |----------|------|-------------| | `ratio` | `number` | The desired aspect ratio. Default: 1 | | `ref` $bindable | `HTMLDivElement` | Reference to the underlying DOM element. Default: null | | `children` | `Snippet` | The children content to render. Default: undefined | | `child` | `Snippet` | Render delegation for custom elements. Default: undefined | Data Attributes: - `data-aspect-ratio-root`: Present on the root element ### avatar Avatar component with Root/Image/Fallback primitives; handles image loading states, supports delayMs, loadingStatus binding, and fallback display on load failure. ## Avatar Component Displays user/entity images with automatic loading state handling and fallback placeholders. ### Features - Smart image loading detection - Fallback system for unavailable/slow images - Compound component structure (Root, Image, Fallback) - Customizable loading behavior ### Architecture Three-part compound component: - **Avatar.Root**: Container managing image state and fallback display - **Avatar.Image**: Displays the image - **Avatar.Fallback**: Shows during loading or on failure ### Basic Usage ```svelte HB ``` ### Reusable Component Pattern ```svelte {fallback} ``` Usage: ```svelte {#each users as user} {/each} ``` ### Skip Loading Check For guaranteed-available images (local assets), bypass the loading check: ```svelte HB ``` ### Clickable with Link Preview Example ```svelte