Runtime And Raw HTML
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.
import { initStarwind } from "@starwind-ui/runtime/init-starwind";
const starwind = initStarwind(document);
// Later, when the root is removed.starwind.destroy();- Package
@starwind-ui/runtime- Import
@starwind-ui/runtime/init-starwind- Signature
initStarwind(root?: ParentNode): StarwindCleanup- Cleanup
- Store the returned cleanup object and call
destroy()when the initialized root leaves the page.
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.
<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-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
| Selector | Factory | Primitive | Cleanup Order | Notes |
|---|---|---|---|---|
[data-sw-button][data-focusable-when-disabled] | createButton | button | 0 | - |
[data-sw-form] | createForm | form | 1 | - |
[data-sw-field] | createField | field | 2 | - |
[data-sw-fieldset] | createFieldset | fieldset | 2 | - |
[data-sw-input] | createInput | input | 3 | - |
[data-sw-input-otp] | createInputOtp | input-otp | 4 | - |
[data-sw-color-picker] | createColorPicker | color-picker | 5 | - |
[data-sw-slider] | createSlider | slider | 5 | - |
[data-sw-switch] | createSwitch | switch | 6 | - |
[data-sw-tabs] | createTabs | tabs | 6 | - |
[data-sw-toggle-group] | createToggleGroup | toggle-group | 7 | - |
[data-sw-toggle] | createToggle | toggle | 8 | - |
[data-sw-avatar] | createAvatar | avatar | 9 | - |
[data-sw-checkbox-group] | createCheckboxGroup | checkbox-group | 10 | - |
[data-sw-checkbox] | createCheckbox | checkbox | 11 | - |
[data-sw-radio-group] | createRadioGroup | radio-group | 12 | - |
[data-sw-radio] | createRadio | radio | 13 | - |
[data-sw-scroll-area] | createScrollArea | scroll-area | 14 | - |
[data-sw-select] | createSelect | select | 15 | - |
[data-sw-sidebar-provider] | createSidebarController | sidebar | 16 | Initialized once per initStarwind root. |
[data-sw-combobox] | createCombobox | combobox | 17 | - |
[data-sw-accordion] | createAccordion | accordion | 18 | - |
[data-sw-collapsible] | createCollapsible | collapsible | 19 | - |
[data-sw-dialog] | createDialog | dialog | 20 | - |
[data-sw-alert-dialog] | createAlertDialog | alert-dialog | 21 | - |
[data-sw-drawer] | createDrawer | drawer | 22 | - |
[data-sw-dropzone] | createDropzone | dropzone | 23 | - |
[data-sw-carousel] | createCarousel | carousel | 24 | Skips elements with data-auto-init="false". |
[data-sw-context-menu] | createContextMenu | context-menu | 25 | - |
[data-sw-menu] | createMenu | menu | 26 | Skips menu roots that are also context-menu roots. |
[data-sw-nav-menu] | createNavigationMenu | navigation-menu | 27 | - |
[data-sw-popover] | createPopover | popover | 27 | - |
[data-sw-preview-card] | createPreviewCard | preview-card | 28 | - |
[data-sw-progress] | createProgress | progress | 29 | - |
[data-sw-tooltip] | createTooltip | tooltip | 30 | - |
[data-sw-toast-viewport] | createToastManager | toast | 31 | - |
[data-sw-theme-control], [data-sw-theme-toggle] | initThemeController | - | 32 | Initialized once per initStarwind root. |
Raw HTML
@starwind-ui/runtime/init-starwindYou write the DOM contract and call initStarwind(root?) or a create* factory.
Astro Primitive adapters
@starwind-ui/astroAdapters render primitive anatomy and attributes while the Runtime owns DOM behavior.
React Primitive adapters
@starwind-ui/reactAdapters expose framework props and refs for the same Runtime primitive contract.
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.
createAccordion @starwind-ui/runtime/accordion type, defaultValue, collapsible, value
- State
- value
- Events
- valueChange (starwind:value-change)
- Setters
- setValue -> state: value
- Docs
- createAccordion documentation
createAlertDialog @starwind-ui/runtime/alert-dialog closeOnEscape, closeOnOutsideInteract, defaultOpen, modal, onCloseComplete, onOpenChange, open
- State
- open
- Events
- closeComplete (starwind:close-complete), openChange (starwind:open-change)
- Setters
- setOpen -> state: open
- Docs
- createAlertDialog documentation
createAvatar @starwind-ui/runtime/avatar -
- State
- imageLoadingStatus
- Events
- loadingStatusChange (starwind:loading-status-change)
- Setters
- -
- Docs
- createAvatar documentation
createButton @starwind-ui/runtime/button disabled
- State
- -
- Events
- -
- Setters
- setDisabled -> prop: disabled
- Docs
- createButton documentation
createCarousel @starwind-ui/runtime/carousel orientation, opts, plugins, setApi
- State
- -
- Events
- -
- Setters
- -
- Docs
- createCarousel documentation
createCheckbox @starwind-ui/runtime/checkbox checked, defaultChecked, disabled, form, id, indeterminate, name, readOnly, required, uncheckedValue, value
- State
- checked, indeterminate
- Events
- checkedChange (starwind:checked-change)
- Setters
- setChecked -> state: checked, setIndeterminate -> state: indeterminate, setDisabled -> prop: disabled
- Docs
- createCheckbox documentation
createCheckboxGroup @starwind-ui/runtime/checkbox-group defaultValue, disabled, value
- State
- value
- Events
- valueChange (starwind:value-change)
- Setters
- setValue -> state: value, setDisabled -> prop: disabled
- Docs
- createCheckboxGroup documentation
createCollapsible @starwind-ui/runtime/collapsible defaultOpen, disabled, open
- State
- open
- Events
- openChange (starwind:open-change)
- Setters
- setOpen -> state: open
- Docs
- createCollapsible documentation
createColorPicker @starwind-ui/runtime/color-picker value, defaultValue, format, alpha, allowEmpty, disabled, readOnly, name, form, required, locale, dir, getAriaValueText, getAreaRoleDescription, getColorDescription, onValueChange, onValueCommitted, onFormatChange
- State
- value, format
- Events
- valueChange (starwind:value-change), valueCommitted (starwind:value-committed), formatChange (starwind:format-change)
- Setters
- 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
- Docs
- createColorPicker documentation
createCombobox @starwind-ui/runtime/combobox autoComplete, defaultInputValue, defaultOpen, defaultValue, disabled, filterMode, form, highlightItemOnHover, inputValue, locale, modal, name, open, readOnly, required, value
- State
- inputValue, open, value
- Events
- inputValueChange (starwind:input-value-change), openChange (starwind:open-change), valueChange (starwind:value-change)
- Setters
- setDisabled -> prop: disabled, setInputValue -> state: inputValue, setOpen -> state: open, setValue -> state: value
- Docs
- createCombobox documentation
createDialog @starwind-ui/runtime/dialog closeOnEscape, closeOnOutsideInteract, defaultOpen, modal, onCloseComplete, onOpenChange, open
- State
- open
- Events
- openChange (starwind:open-change), closeComplete (starwind:close-complete)
- Setters
- setOpen -> state: open
- Docs
- createDialog documentation
createDrawer @starwind-ui/runtime/drawer closeOnEscape, closeOnOutsideInteract, defaultOpen, modal, onCloseComplete, onOpenChange, open
- State
- open
- Events
- openChange (starwind:open-change), closeComplete (starwind:close-complete)
- Setters
- setOpen -> state: open
- Docs
- createDrawer documentation
createDropzone @starwind-ui/runtime/dropzone disabled, isUploading, onFilesChange
- State
- uploading
- Events
- filesChange (starwind:files-change)
- Setters
- setDisabled -> prop: disabled, setUploading -> prop: isUploading
- Docs
- createDropzone documentation
createField @starwind-ui/runtime/field dirty, disabled, invalid, name, touched
- State
- dirty, touched
- Events
- -
- Setters
- setDirty -> prop: dirty, setDisabled -> prop: disabled, setInvalid -> prop: invalid, setName -> prop: name, setTouched -> prop: touched
- Docs
- createField documentation
createFieldset @starwind-ui/runtime/fieldset disabled
- State
- -
- Events
- -
- Setters
- setDisabled -> prop: disabled
- Docs
- createFieldset documentation
createForm @starwind-ui/runtime/form -
- State
- -
- Events
- -
- Setters
- -
- Docs
- createForm documentation
createInput @starwind-ui/runtime/input defaultValue, disabled, onValueChange, value
- State
- value
- Events
- valueChange (starwind:value-change)
- Setters
- setValue -> state: value, setDisabled -> prop: disabled
- Docs
- createInput documentation
createInputOtp @starwind-ui/runtime/input-otp defaultValue, disabled, form, id, maxLength, name, onValueChange, pattern, readOnly, required, value
- State
- value
- Events
- valueChange (starwind:value-change)
- Setters
- setValue -> state: value, setDisabled -> prop: disabled, setFormOptions -> props: form, id, name, required
- Docs
- createInputOtp documentation
createPopover @starwind-ui/runtime/popover closeOnEscape, closeOnOutsideInteract, defaultOpen, modal, onCloseComplete, onOpenChange, open, openOnHover
- State
- open
- Events
- openChange (starwind:open-change), closeComplete (starwind:close-complete)
- Setters
- setOpen -> state: open
- Docs
- createPopover documentation
createPreviewCard @starwind-ui/runtime/preview-card closeDelay, closeOnEscape, closeOnOutsideInteract, defaultOpen, disableHoverableContent, onOpenChange, open, openDelay
- State
- open
- Events
- openChange (starwind:open-change)
- Setters
- setOpen -> state: open
- Docs
- createPreviewCard documentation
createProgress @starwind-ui/runtime/progress format, getAriaValueText, locale, max, min, value
- State
- value
- Events
- -
- Setters
- setFormatOptions -> props: format, getAriaValueText, locale, setValue -> props: value, max, min
- Docs
- createProgress documentation
createRadio @starwind-ui/runtime/radio checked, defaultChecked, disabled, form, id, name, readOnly, required, value
- State
- checked
- Events
- checkedChange (starwind:checked-change)
- Setters
- setChecked -> state: checked, setDisabled -> prop: disabled, setReadOnly -> prop: readOnly, setFormOptions -> props: form, name, required, value
- Docs
- createRadio documentation
createRadioGroup @starwind-ui/runtime/radio-group defaultValue, disabled, form, name, orientation, readOnly, required, value
- State
- value
- Events
- valueChange (starwind:value-change)
- Setters
- setValue -> state: value, setDisabled -> prop: disabled, setFormOptions -> props: form, name, required, setName -> prop: name, setOrientation -> prop: orientation, setReadOnly -> prop: readOnly, setRequired -> prop: required
- Docs
- createRadioGroup documentation
createScrollArea @starwind-ui/runtime/scroll-area overflowEdgeThreshold
- State
- -
- Events
- -
- Setters
- -
- Docs
- createScrollArea documentation
createSelect @starwind-ui/runtime/select autoComplete, defaultOpen, defaultValue, disabled, form, highlightItemOnHover, modal, open, readOnly, value
- State
- open, value
- Events
- openChange (starwind:open-change), valueChange (starwind:value-change)
- Setters
- setOpen -> state: open, setValue -> state: value
- Docs
- createSelect documentation
createSidebarController @starwind-ui/runtime/sidebar defaultMobileOpen, defaultOpen, keyboardShortcut, mobileOpen, mobileQuery, onMobileOpenChange, onOpenChange, open, persistOpen, persistenceKey, persistenceMaxAge, persistenceStorage
- State
- open, mobileOpen
- Events
- openChange (starwind:sidebar-change), mobileOpenChange (starwind:sidebar-mobile-change)
- Setters
- setOpen -> state: open, setMobileOpen -> state: mobileOpen
- Docs
- createSidebarController documentation
createSlider @starwind-ui/runtime/slider defaultValue, disabled, form, largeStep, max, min, minStepsBetweenValues, name, orientation, step, value
- State
- value
- Events
- valueChange (starwind:value-change), valueCommitted (starwind:value-committed)
- Setters
- setValue -> state: value, setDisabled -> prop: disabled, setName -> prop: name, setOptions -> props: form, largeStep, max, min, minStepsBetweenValues, orientation, step
- Docs
- createSlider documentation
createSwitch @starwind-ui/runtime/switch checked, defaultChecked, disabled, form, id, name, readOnly, required, uncheckedValue, value
- State
- checked
- Events
- checkedChange (starwind:checked-change)
- Setters
- setChecked -> state: checked, setDisabled -> prop: disabled, setFormOptions -> props: form, name, required, uncheckedValue, value
- Docs
- createSwitch documentation
createTabs @starwind-ui/runtime/tabs defaultValue, orientation, syncKey, value
- State
- value
- Events
- valueChange (starwind:value-change)
- Setters
- setValue -> state: value
- Docs
- createTabs documentation
createToastManager @starwind-ui/runtime/toast -
- State
- -
- Events
- -
- Setters
- -
- Docs
- createToastManager documentation
createToggle @starwind-ui/runtime/toggle defaultPressed, disabled, nativeButton, pressed, syncGroup, value
- State
- pressed
- Events
- pressedChange (starwind:pressed-change)
- Setters
- setPressed -> state: pressed, setDisabled -> prop: disabled
- Docs
- createToggle documentation
createToggleGroup @starwind-ui/runtime/toggle-group defaultValue, disabled, loopFocus, multiple, orientation, value
- State
- value
- Events
- valueChange (starwind:value-change)
- Setters
- setValue -> state: value, setDisabled -> prop: disabled, setLoopFocus -> prop: loopFocus, setMultiple -> prop: multiple, setOrientation -> prop: orientation
- Docs
- createToggleGroup documentation
createTooltip @starwind-ui/runtime/tooltip closeDelay, closeOnEscape, closeOnOutsideInteract, defaultOpen, disabled, disableHoverableContent, onOpenChange, open, openDelay
- State
- open
- Events
- openChange (starwind:open-change)
- Setters
- setOpen -> state: open, setDisabled -> prop: disabled
- Docs
- createTooltip documentation
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.
| 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 |
- 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)