# 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:

```ts
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](/docs/core/kernel/handle-changes#control-the-state) shows.

- [Define a Primitive](/docs/core/kernel/define-a-primitive) covers options, slots, events and cleanup.
- [Handle Changes](/docs/core/kernel/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`:

```ts
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](/docs/core/behaviors/focus#roving-focus) shows how to connect it to the buttons. [Compose Behaviors](/docs/core/compose-behaviors) uses it to build the star rating.

For other interactions, start here:

| I want to…                                  | Guide                                                    |
| ------------------------------------------- | -------------------------------------------------------- |
| Choose one or more items                    | [Selection](/docs/core/behaviors/selection)                       |
| Reorder items or move them between lists    | [Drag and Drop](/docs/core/behaviors/drag-and-drop)               |
| Move, resize or swipe an element            | [Dragging and Resizing](/docs/core/behaviors/direct-manipulation) |
| Render a long list or edit an item in place | [Lists](/docs/core/behaviors/lists)                               |
| Navigate and expand nested items            | [Trees](/docs/core/behaviors/trees)                               |
| Animate a change in layout                  | [Transitions and Gestures](/docs/core/behaviors/motion)           |
| Position and dismiss a popup                | [Popups and Layers](/docs/core/behaviors/popups)                  |
| Pan, zoom or connect items on a canvas      | [Canvas](/docs/core/behaviors/canvas)                             |
| Work with calendar dates                    | [Dates](/docs/core/date)                                          |

## 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:

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

announce("Copied")
```

[Platform](/docs/core/platform) covers announcements, page direction and keyboard shortcuts. [Text](/docs/core/text) covers searching, matching and language.

To check what you've built, [Testing](/docs/core/testing) shows how to test state, keyboard behavior and accessibility.