Reference

Find the pieces you need to build your component.

Find the Core helpers for managing state, adding interactions, and working with the browser. Each section has a small example and links to the relevant guide.

ui-sdk hasn't reached 1.0 yet, so any of these can still change between releases. The ones marked experimental are the likeliest to.

State and Parts

definePrimitive puts a component's state, methods and parts together. Inside its api, use createChange to report a change:

import { createChange } from "@ui-sdk/core"

const change = createChange(context)

return {
  mute: () => change("muted", true, { reason: "press" }),
}

Calling mute reports the new value through onMutedChange. The same helper handles both controlled and uncontrolled state, as the controlled mute button shows.

Define a Primitive covers options, slots, events and cleanup.
Handle Changes covers callbacks, controlled state and undo.

Add an Interaction

Say you're building a row of buttons. createRovingFocus gives the row one Tab stop and moves between buttons with the Left and Right arrow keys. Inside the primitive's api:

import { createRovingFocus } from "@ui-sdk/core"

const roving = createRovingFocus(context, {
  slot: "item",
  key: "focused",
  orientation: () => "horizontal",
  loop: () => true,
})

This chooses how focus moves. Focus and Keys shows how to connect it to the buttons. Compose Behaviors uses it to build the star rating.

For other interactions, start here:

I want to…	Guide
Choose one or more items	Selection
Reorder items or move them between lists	Drag and Drop
Move, resize or swipe an element	Dragging and Resizing
Render a long list or edit an item in place	Lists
Navigate and expand nested items	Trees
Animate a change in layout	Transitions and Gestures
Position and dismiss a popup	Popups and Layers
Pan, zoom or connect items on a canvas	Canvas
Work with calendar dates	Dates

Use a Helper on Its Own

Some helpers work without a primitive. For example, after a copy succeeds, you can announce it to a screen reader:

import { announce } from "@ui-sdk/core"

announce("Copied")

Platform covers announcements, page direction and keyboard shortcuts. Text covers searching, matching and language.

To check what you've built, Testing shows how to test state, keyboard behavior and accessibility.