API
How the library’s API is shaped — the conventions that hold across every component. The API of a specific component (its props, slots and events) lives on that component’s own page under Components.
The headless model
Section titled “The headless model”Behaviour, state and accessibility live once in the framework-agnostic core
(@invisible-ui/core); thin per-framework adapters expose it idiomatically.
- Core — each component is a pure state plus a
connect()function that returns framework-agnostic prop getters: plain objects carrying ARIA attributes,data-*styling hooks and event handlers. The core never imports a framework and never touches the DOM. - Adapter — exposes that API in each framework’s idiom: the Svelte
adapter wraps the state in a store and applies props through
use:actions; the React adapter holds it in hooks and spreads the prop bags onto JSX. You bring the markup and the styling.
Svelte adapter: create* + actions
Section titled “Svelte adapter: create* + actions”Each component exposes a create* factory returning Svelte actions (and
reactive stores). Apply an action to your element with use:; it keeps the
element’s attributes, ARIA and event listeners in sync with state.
<script> import { createCollapsible } from "@invisible-ui/svelte"; const { rootAction, triggerAction, contentAction, open } = createCollapsible({ open: false });</script>
<div use:rootAction> <button use:triggerAction>Toggle</button> <div use:contentAction>Content</div></div>The styled components are imported from their own module
(@invisible-ui/svelte/<Component>.svelte); the headless create* functions
come from the package root (@invisible-ui/svelte).
React adapter: use* hooks
Section titled “React adapter: use* hooks”The React adapter (@invisible-ui/react) includes Button, Checkbox, Switch,
Select, TextField, SearchField, Combobox, MultiSelect, Dialog and Icon. Its
headless primitives
are exposed as use* hooks. The connected API is recomputed each render and
its prop bags are spread onto JSX; styled components and the hooks ship from
the package root, styles are opt-in via @invisible-ui/react/styles.css.
import { Checkbox, useCheckbox } from "@invisible-ui/react";import "@invisible-ui/react/styles.css";
// Styled…<Checkbox label="Subscribe" onCheckedChange={save} />;
// …or headless: render your own markup, keep only the behaviour.const api = useCheckbox({ onCheckedChange: save });<input {...api.rootProps} checked={api.checked === true} />;Python (Reflex) apps get seven components as thin wrappers over the React
build: the original six-component set plus MultiSelect. Use the invisible-ui
package, import invisible_ui as ui, and
ui.button("Save", variant="primary", on_press=State.save). Behaviour runs in
the browser as the core’s JavaScript; Python only wires state and events (ADR
0006).
Vue apps get native composables and components (@invisible-ui/vue,
the whole catalog) with v-model on the controlled values, plus the same
callback props as the React adapter (ADR 0010). The
Framework support page tracks per-adapter
coverage.
data-* styling hooks
Section titled “data-* styling hooks”Style components by targeting the data-* attributes the prop getters set —
never internal classes. The recurring hooks:
| Hook | Meaning |
|---|---|
data-state |
the component’s discrete state — e.g. open/closed, checked/unchecked, on/off, selected |
data-disabled |
present (empty string) when the element is disabled |
data-orientation |
horizontal / vertical |
data-active |
the active/highlighted item (e.g. combobox option, roving focus) |
data-value |
an item’s value, used to scope behaviour and focus |
.switch[data-state="checked"] { background: var(--ds-color-primary-500); }.switch[data-disabled] { opacity: 0.5; }Accessibility
Section titled “Accessibility”Components implement the relevant
WAI-ARIA Authoring Practices pattern: correct
roles and attributes, full keyboard support, focus management, and roving
tabindex where applicable. Interactive demos are checked with vitest-axe. Any
control that needs an accessible name takes it from the consumer (a label prop,
aria-label, or an associated <label>).
Security
Section titled “Security”Labels, descriptions and messages you pass to a component are rendered as
text, never as markup. URLs are different. A component that takes a link
(href) or an image source (src), such as Link, Breadcrumb, Navigation
Menu, Sidebar, Avatar, Avatar Group, Card (image), Carousel (slide images),
Login Form (forgot-password link) or Inline Notification, writes the URL to
the element as given. The component does not check the scheme, so a javascript: URL runs
when the link is followed.
The Svelte, Vue and web component adapters work this way. The React adapter
follows React: React 19 blocks javascript: URLs in href, while React 18
only warns about them. When a URL comes from
users or another source you do not control, validate or sanitize it before you
pass it, for example by allowing only https:, http:, mailto: and
relative paths.
Normalisation
Section titled “Normalisation”Adapters supply a normalize function that maps the generic prop bag into
framework-native props. The Svelte adapter applies props to the DOM directly via
its use: action, so normalisation is the identity — the same prop getters can
back other frameworks by remapping keys.
Theming
Section titled “Theming”Components ship no opinionated visual styling. The styled layer is themed
entirely through --ds-* CSS custom properties, so everything follows the
light/dark theme and stays re-themeable. See Foundations for the token
system (color scale, typography, contrast).