# Runtime And Raw HTML

{/* Generated by scripts/portable-runtime/generate-layered-docs-metadata.ts. Do not edit directly. */}

The Runtime surface is for raw HTML and framework adapters that already render the Starwind DOM
contract. It owns initialization, cleanup, discovery hooks, factories, DOM events, instance
methods, and theme helpers without requiring Astro or React.

Use styled components first when you want ready-to-render UI. Use the Runtime directly when you are
rendering static markup, building a framework adapter, or integrating Starwind behavior into a
non-framework surface.

## Init Starwind

`initStarwind` scans a root node for Starwind discovery attributes and initializes each matching
primitive in cleanup order. Store the returned cleanup object and call `destroy()` when that root
leaves the page.

```ts
import { initStarwind } from "@starwind-ui/runtime/init-starwind";

const starwind = initStarwind(document);

// Later, when the root is removed.
starwind.destroy();
```

## Raw HTML

Raw HTML uses `data-sw-*` discovery hooks for Runtime ownership. You provide the DOM contract, then
call `initStarwind(root?)` for automatic discovery or call a `create*` factory for one primitive
instance.

```html
<div data-sw-drawer>
  <button data-sw-drawer-trigger>Open</button>
  <div data-sw-drawer-popup hidden>
    <button data-sw-drawer-close>Close</button>
  </div>
</div>
```

The initializer registry below shows which selectors are discovered by `initStarwind`, which
factory owns each selector, and the cleanup order used when a root is destroyed.

## Data Attributes

Runtime discovery attributes use the `data-sw-*` prefix. Primitive state, options, and measured
values use short scoped `data-*` attributes such as `data-state`, `data-value`, `data-side`, and
`data-auto-init`.

Treat `data-sw-*` attributes as behavior hooks. Treat `data-slot` as public part identity for
styling and documentation. Styled components may add classes, variants, and slots around the same
Runtime-owned behavior contract.

## Runtime Factories

Every primitive has a `create*` factory. Framework adapters call these factories after rendering
primitive anatomy; raw HTML can call them directly when you want explicit ownership instead of
document-wide discovery.

Factories expose option props, state models, DOM events, and setter methods. Setter calls update the
Runtime instance without requiring a framework render cycle.

## Lifecycle And Cleanup

`initStarwind` returns a cleanup object for the initialized root. Calling `destroy()` tears down
listeners, observers, timers, floating behavior, portals, and runtime-owned presence for primitives
created under that root.

Some raw HTML initializers are ordered because child primitives depend on parent providers or form
state. Use the cleanup order in the raw HTML table when you build a custom adapter or manual
initializer.

## Events And State

Runtime factories bridge controlled and uncontrolled state with DOM events. For example,
`createDrawer` exposes open state, emits `starwind:open-change`, and provides setter methods for
updating state from framework adapters or custom DOM code.

Use event names from the factory table when listening from raw HTML. Use callback props from the
framework adapter when you are inside Astro or React primitives.

## Theme

Theme helpers are part of the Runtime surface. Use `createThemeController` for interactive controls
and `getThemeInitScript` before paint to apply the initial color theme.

Theme controls are discovered through selectors such as `[data-sw-theme-control]` and
`[data-sw-theme-toggle]`. The Runtime emits `starwind:theme-change` when the active theme changes.

## Runtime Reference
Use the Runtime directly when raw HTML or a framework adapter already renders the Starwind DOM contract.
| Fact | Value |
| --- | --- |
| Package | `@starwind-ui/runtime` |
| Initializer | `initStarwind(root?: ParentNode): StarwindCleanup` |
| Import | `@starwind-ui/runtime/init-starwind` |
| Cleanup | Store the returned cleanup object and call `destroy()` when the initialized root leaves the page. |
## Raw HTML Initializers
Raw HTML uses `data-sw-*` discovery hooks for Runtime ownership.
| Selector | Factory | Primitive | Cleanup Order | Notes |
| --- | --- | --- | --- | --- |
| `[data-sw-button][data-focusable-when-disabled]` | [`createButton`](/docs/runtime/#create-button) | [button](/docs/primitives/button/) | 0 | - |
| `[data-sw-form]` | [`createForm`](/docs/runtime/#create-form) | [form](/docs/primitives/form/) | 1 | - |
| `[data-sw-field]` | [`createField`](/docs/runtime/#create-field) | [field](/docs/primitives/field/) | 2 | - |
| `[data-sw-fieldset]` | [`createFieldset`](/docs/runtime/#create-fieldset) | [fieldset](/docs/primitives/fieldset/) | 2 | - |
| `[data-sw-input]` | [`createInput`](/docs/runtime/#create-input) | [input](/docs/primitives/input/) | 3 | - |
| `[data-sw-input-otp]` | [`createInputOtp`](/docs/runtime/#create-input-otp) | [input-otp](/docs/primitives/input-otp/) | 4 | - |
| `[data-sw-color-picker]` | [`createColorPicker`](/docs/runtime/#create-color-picker) | [color-picker](/docs/primitives/color-picker/) | 5 | - |
| `[data-sw-slider]` | [`createSlider`](/docs/runtime/#create-slider) | [slider](/docs/primitives/slider/) | 5 | - |
| `[data-sw-switch]` | [`createSwitch`](/docs/runtime/#create-switch) | [switch](/docs/primitives/switch/) | 6 | - |
| `[data-sw-tabs]` | [`createTabs`](/docs/runtime/#create-tabs) | [tabs](/docs/primitives/tabs/) | 6 | - |
| `[data-sw-toggle-group]` | [`createToggleGroup`](/docs/runtime/#create-toggle-group) | [toggle-group](/docs/primitives/toggle-group/) | 7 | - |
| `[data-sw-toggle]` | [`createToggle`](/docs/runtime/#create-toggle) | [toggle](/docs/primitives/toggle/) | 8 | - |
| `[data-sw-avatar]` | [`createAvatar`](/docs/runtime/#create-avatar) | [avatar](/docs/primitives/avatar/) | 9 | - |
| `[data-sw-checkbox-group]` | [`createCheckboxGroup`](/docs/runtime/#create-checkbox-group) | [checkbox-group](/docs/primitives/checkbox-group/) | 10 | - |
| `[data-sw-checkbox]` | [`createCheckbox`](/docs/runtime/#create-checkbox) | [checkbox](/docs/primitives/checkbox/) | 11 | - |
| `[data-sw-radio-group]` | [`createRadioGroup`](/docs/runtime/#create-radio-group) | [radio-group](/docs/primitives/radio-group/) | 12 | - |
| `[data-sw-radio]` | [`createRadio`](/docs/runtime/#create-radio) | [radio](/docs/primitives/radio/) | 13 | - |
| `[data-sw-scroll-area]` | [`createScrollArea`](/docs/runtime/#create-scroll-area) | [scroll-area](/docs/primitives/scroll-area/) | 14 | - |
| `[data-sw-select]` | [`createSelect`](/docs/runtime/#create-select) | [select](/docs/primitives/select/) | 15 | - |
| `[data-sw-sidebar-provider]` | [`createSidebarController`](/docs/runtime/#create-sidebar-controller) | [sidebar](/docs/primitives/sidebar/) | 16 | Initialized once per initStarwind root. |
| `[data-sw-combobox]` | [`createCombobox`](/docs/runtime/#create-combobox) | [combobox](/docs/primitives/combobox/) | 17 | - |
| `[data-sw-accordion]` | [`createAccordion`](/docs/runtime/#create-accordion) | [accordion](/docs/primitives/accordion/) | 18 | - |
| `[data-sw-collapsible]` | [`createCollapsible`](/docs/runtime/#create-collapsible) | [collapsible](/docs/primitives/collapsible/) | 19 | - |
| `[data-sw-dialog]` | [`createDialog`](/docs/runtime/#create-dialog) | [dialog](/docs/primitives/dialog/) | 20 | - |
| `[data-sw-alert-dialog]` | [`createAlertDialog`](/docs/runtime/#create-alert-dialog) | [alert-dialog](/docs/primitives/alert-dialog/) | 21 | - |
| `[data-sw-drawer]` | [`createDrawer`](/docs/runtime/#create-drawer) | [drawer](/docs/primitives/drawer/) | 22 | - |
| `[data-sw-dropzone]` | [`createDropzone`](/docs/runtime/#create-dropzone) | [dropzone](/docs/primitives/dropzone/) | 23 | - |
| `[data-sw-carousel]` | [`createCarousel`](/docs/runtime/#create-carousel) | [carousel](/docs/primitives/carousel/) | 24 | Skips elements with data-auto-init="false". |
| `[data-sw-context-menu]` | [`createContextMenu`](/docs/runtime/#create-context-menu) | [context-menu](/docs/primitives/context-menu/) | 25 | - |
| `[data-sw-menu]` | [`createMenu`](/docs/runtime/#create-menu) | [menu](/docs/primitives/menu/) | 26 | Skips menu roots that are also context-menu roots. |
| `[data-sw-nav-menu]` | [`createNavigationMenu`](/docs/runtime/#create-navigation-menu) | [navigation-menu](/docs/primitives/navigation-menu/) | 27 | - |
| `[data-sw-popover]` | [`createPopover`](/docs/runtime/#create-popover) | [popover](/docs/primitives/popover/) | 27 | - |
| `[data-sw-preview-card]` | [`createPreviewCard`](/docs/runtime/#create-preview-card) | [preview-card](/docs/primitives/preview-card/) | 28 | - |
| `[data-sw-progress]` | [`createProgress`](/docs/runtime/#create-progress) | [progress](/docs/primitives/progress/) | 29 | - |
| `[data-sw-tooltip]` | [`createTooltip`](/docs/runtime/#create-tooltip) | [tooltip](/docs/primitives/tooltip/) | 30 | - |
| `[data-sw-toast-viewport]` | [`createToastManager`](/docs/runtime/#create-toast-manager) | [toast](/docs/primitives/toast/) | 31 | - |
| `[data-sw-theme-control], [data-sw-theme-toggle]` | [`initThemeController`](/docs/runtime/) | - | 32 | Initialized once per initStarwind root. |
## Data Attribute Conventions
| Prefix | Purpose | Examples |
| --- | --- | --- |
| `data-sw-*` | Runtime discovery hooks. | `data-sw-drawer`, `data-sw-menu`, `data-sw-theme-toggle` |
| `data-*` | Scoped state and option attributes owned by a primitive. | `data-state`, `data-value`, `data-side`, `data-auto-init` |
## Adapter Responsibilities
| Surface | Import | Responsibility |
| --- | --- | --- |
| Raw HTML | `@starwind-ui/runtime/init-starwind` | You write the DOM contract and call initStarwind(root?) or a create* factory. |
| Astro Primitive adapters | `@starwind-ui/astro` | Adapters render primitive anatomy and attributes while the Runtime owns DOM behavior. |
| React Primitive adapters | `@starwind-ui/react` | Adapters expose framework props and refs for the same Runtime primitive contract. |
## Runtime Factories
| Factory | Import | Options | State | Events | Setters |
| --- | --- | --- | --- | --- | --- |
| `createAccordion` | `@starwind-ui/runtime/accordion` | type, defaultValue, collapsible, value | value | valueChange (starwind:value-change) | `setValue` -> state: value |
| `createAlertDialog` | `@starwind-ui/runtime/alert-dialog` | closeOnEscape, closeOnOutsideInteract, defaultOpen, modal, onCloseComplete, onOpenChange, open | open | closeComplete (starwind:close-complete), openChange (starwind:open-change) | `setOpen` -> state: open |
| `createAvatar` | `@starwind-ui/runtime/avatar` | - | imageLoadingStatus | loadingStatusChange (starwind:loading-status-change) | - |
| `createButton` | `@starwind-ui/runtime/button` | disabled | - | - | `setDisabled` -> prop: disabled |
| `createCarousel` | `@starwind-ui/runtime/carousel` | orientation, opts, plugins, setApi | - | - | - |
| `createCheckbox` | `@starwind-ui/runtime/checkbox` | checked, defaultChecked, disabled, form, id, indeterminate, name, readOnly, required, uncheckedValue, value | checked, indeterminate | checkedChange (starwind:checked-change) | `setChecked` -> state: checked, `setIndeterminate` -> state: indeterminate, `setDisabled` -> prop: disabled |
| `createCheckboxGroup` | `@starwind-ui/runtime/checkbox-group` | defaultValue, disabled, value | value | valueChange (starwind:value-change) | `setValue` -> state: value, `setDisabled` -> prop: disabled |
| `createCollapsible` | `@starwind-ui/runtime/collapsible` | defaultOpen, disabled, open | open | openChange (starwind:open-change) | `setOpen` -> state: open |
| `createColorPicker` | `@starwind-ui/runtime/color-picker` | value, defaultValue, format, alpha, allowEmpty, disabled, readOnly, name, form, required, locale, dir, getAriaValueText, getAreaRoleDescription, getColorDescription, onValueChange, onValueCommitted, onFormatChange | value, format | valueChange (starwind:value-change), valueCommitted (starwind:value-committed), formatChange (starwind:format-change) | `setValue` -> state: value, `setFormat` -> state: format, `setDisabled` -> prop: disabled, `setReadOnly` -> prop: readOnly, `setName` -> prop: name, `setOptions` -> props: alpha, allowEmpty, dir, form, getAreaRoleDescription, getAriaValueText, getColorDescription, locale, required |
| `createCombobox` | `@starwind-ui/runtime/combobox` | autoComplete, defaultInputValue, defaultOpen, defaultValue, disabled, filterMode, form, highlightItemOnHover, inputValue, locale, modal, name, open, readOnly, required, value | inputValue, open, value | inputValueChange (starwind:input-value-change), openChange (starwind:open-change), valueChange (starwind:value-change) | `setDisabled` -> prop: disabled, `setInputValue` -> state: inputValue, `setOpen` -> state: open, `setValue` -> state: value |
| `createContextMenu` | `@starwind-ui/runtime/context-menu` | closeDelay, defaultOpen, disabled, modal, onCloseComplete, onOpenChange, open | open, checked, radioValue | openChange (starwind:open-change), closeComplete (starwind:close-complete), checkedChange (starwind:checked-change), valueChange (starwind:value-change) | `setOpen` -> state: open |
| `createDialog` | `@starwind-ui/runtime/dialog` | closeOnEscape, closeOnOutsideInteract, defaultOpen, modal, onCloseComplete, onOpenChange, open | open | openChange (starwind:open-change), closeComplete (starwind:close-complete) | `setOpen` -> state: open |
| `createDrawer` | `@starwind-ui/runtime/drawer` | closeOnEscape, closeOnOutsideInteract, defaultOpen, modal, onCloseComplete, onOpenChange, open | open | openChange (starwind:open-change), closeComplete (starwind:close-complete) | `setOpen` -> state: open |
| `createDropzone` | `@starwind-ui/runtime/dropzone` | disabled, isUploading, onFilesChange | uploading | filesChange (starwind:files-change) | `setDisabled` -> prop: disabled, `setUploading` -> prop: isUploading |
| `createField` | `@starwind-ui/runtime/field` | dirty, disabled, invalid, name, touched | dirty, touched | - | `setDirty` -> prop: dirty, `setDisabled` -> prop: disabled, `setInvalid` -> prop: invalid, `setName` -> prop: name, `setTouched` -> prop: touched |
| `createFieldset` | `@starwind-ui/runtime/fieldset` | disabled | - | - | `setDisabled` -> prop: disabled |
| `createForm` | `@starwind-ui/runtime/form` | - | - | - | - |
| `createInput` | `@starwind-ui/runtime/input` | defaultValue, disabled, onValueChange, value | value | valueChange (starwind:value-change) | `setValue` -> state: value, `setDisabled` -> prop: disabled |
| `createInputOtp` | `@starwind-ui/runtime/input-otp` | defaultValue, disabled, form, id, maxLength, name, onValueChange, pattern, readOnly, required, value | value | valueChange (starwind:value-change) | `setValue` -> state: value, `setDisabled` -> prop: disabled, `setFormOptions` -> props: form, id, name, required |
| `createMenu` | `@starwind-ui/runtime/menu` | closeDelay, defaultOpen, disabled, modal, onCloseComplete, onOpenChange, open, openOnHover | open, checked, radioValue | openChange (starwind:open-change), closeComplete (starwind:close-complete), checkedChange (starwind:checked-change), valueChange (starwind:value-change) | `setOpen` -> state: open |
| `createNavigationMenu` | `@starwind-ui/runtime/navigation-menu` | closeDelay, closeOnEscape, closeOnOutsideInteract, defaultValue, onValueChange, openDelay, value | value | valueChange (starwind:value-change) | `setValue` -> state: value |
| `createPopover` | `@starwind-ui/runtime/popover` | closeOnEscape, closeOnOutsideInteract, defaultOpen, modal, onCloseComplete, onOpenChange, open, openOnHover | open | openChange (starwind:open-change), closeComplete (starwind:close-complete) | `setOpen` -> state: open |
| `createPreviewCard` | `@starwind-ui/runtime/preview-card` | closeDelay, closeOnEscape, closeOnOutsideInteract, defaultOpen, disableHoverableContent, onOpenChange, open, openDelay | open | openChange (starwind:open-change) | `setOpen` -> state: open |
| `createProgress` | `@starwind-ui/runtime/progress` | format, getAriaValueText, locale, max, min, value | value | - | `setFormatOptions` -> props: format, getAriaValueText, locale, `setValue` -> props: value, max, min |
| `createRadio` | `@starwind-ui/runtime/radio` | checked, defaultChecked, disabled, form, id, name, readOnly, required, value | checked | checkedChange (starwind:checked-change) | `setChecked` -> state: checked, `setDisabled` -> prop: disabled, `setReadOnly` -> prop: readOnly, `setFormOptions` -> props: form, name, required, value |
| `createRadioGroup` | `@starwind-ui/runtime/radio-group` | defaultValue, disabled, form, name, orientation, readOnly, required, value | value | valueChange (starwind:value-change) | `setValue` -> state: value, `setDisabled` -> prop: disabled, `setFormOptions` -> props: form, name, required, `setName` -> prop: name, `setOrientation` -> prop: orientation, `setReadOnly` -> prop: readOnly, `setRequired` -> prop: required |
| `createScrollArea` | `@starwind-ui/runtime/scroll-area` | overflowEdgeThreshold | - | - | - |
| `createSelect` | `@starwind-ui/runtime/select` | autoComplete, defaultOpen, defaultValue, disabled, form, highlightItemOnHover, modal, open, readOnly, value | open, value | openChange (starwind:open-change), valueChange (starwind:value-change) | `setOpen` -> state: open, `setValue` -> state: value |
| `createSidebarController` | `@starwind-ui/runtime/sidebar` | defaultMobileOpen, defaultOpen, keyboardShortcut, mobileOpen, mobileQuery, onMobileOpenChange, onOpenChange, open, persistOpen, persistenceKey, persistenceMaxAge, persistenceStorage | open, mobileOpen | openChange (starwind:sidebar-change), mobileOpenChange (starwind:sidebar-mobile-change) | `setOpen` -> state: open, `setMobileOpen` -> state: mobileOpen |
| `createSlider` | `@starwind-ui/runtime/slider` | defaultValue, disabled, form, largeStep, max, min, minStepsBetweenValues, name, orientation, step, value | value | valueChange (starwind:value-change), valueCommitted (starwind:value-committed) | `setValue` -> state: value, `setDisabled` -> prop: disabled, `setName` -> prop: name, `setOptions` -> props: form, largeStep, max, min, minStepsBetweenValues, orientation, step |
| `createSwitch` | `@starwind-ui/runtime/switch` | checked, defaultChecked, disabled, form, id, name, readOnly, required, uncheckedValue, value | checked | checkedChange (starwind:checked-change) | `setChecked` -> state: checked, `setDisabled` -> prop: disabled, `setFormOptions` -> props: form, name, required, uncheckedValue, value |
| `createTabs` | `@starwind-ui/runtime/tabs` | defaultValue, orientation, syncKey, value | value | valueChange (starwind:value-change) | `setValue` -> state: value |
| `createToastManager` | `@starwind-ui/runtime/toast` | - | - | - | - |
| `createToggle` | `@starwind-ui/runtime/toggle` | defaultPressed, disabled, nativeButton, pressed, syncGroup, value | pressed | pressedChange (starwind:pressed-change) | `setPressed` -> state: pressed, `setDisabled` -> prop: disabled |
| `createToggleGroup` | `@starwind-ui/runtime/toggle-group` | defaultValue, disabled, loopFocus, multiple, orientation, value | value | valueChange (starwind:value-change) | `setValue` -> state: value, `setDisabled` -> prop: disabled, `setLoopFocus` -> prop: loopFocus, `setMultiple` -> prop: multiple, `setOrientation` -> prop: orientation |
| `createTooltip` | `@starwind-ui/runtime/tooltip` | closeDelay, closeOnEscape, closeOnOutsideInteract, defaultOpen, disabled, disableHoverableContent, onOpenChange, open, openDelay | open | openChange (starwind:open-change) | `setOpen` -> state: open, `setDisabled` -> prop: disabled |
## Theme Helpers
| Helper | Import | Signature |
| --- | --- | --- |
| `createThemeController` | `@starwind-ui/runtime/theme` | `createThemeController(options?: ThemeControllerOptions): ThemeControllerInstance` |
| `initThemeController` | `@starwind-ui/runtime/theme` | `initThemeController(root?: ParentNode, options?: Omit<ThemeControllerOptions, "root">): ThemeControllerInstance` |
| `getThemeInitScript` | `@starwind-ui/runtime/theme` | `getThemeInitScript(options?: ThemeInitScriptOptions): string` |
## Theme Controls And Events
| Fact | Value |
| --- | --- |
| Control selectors | [data-sw-theme-control], [data-sw-theme-toggle] |
| Control attributes | data-theme-value, data-theme-on, data-theme-off, data-ready |
| Events | starwind:theme-change (StarwindThemeChangeDetails), theme:change (StarwindThemeChangeDetails) |