Skip to content

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.

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.

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).

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.

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; }

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>).

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.

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.

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).