# All Behaviors

Focus, selection, popups and the other pieces your components are made of.

Browse the helpers by topic. Each name links to its guide and examples.

Import helpers from `@ui-sdk/core` unless a different entrypoint is shown.

## Focus and Keys

| Helper                                                               | What It Does                                                             |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| [`createRovingFocus`](/docs/core/behaviors/focus#roving-focus)                          | Gives a group one Tab stop and moves focus with the arrow keys.          |
| [`createGridFocus`](/docs/core/behaviors/focus#grids)                                   | Moves focus by row and column, including cells that aren't rendered yet. |
| [`byCell`](/docs/core/behaviors/focus#one-tab-stop-in-a-grid)                           | Updates only the cell focus leaves and the cell it lands on.             |
| [`spatialMove`](/docs/core/behaviors/focus#spatial-focus)                               | Chooses the next item from its position on screen.                       |
| [`nearestInDirection`](/docs/core/behaviors/focus#choose-a-target-without-moving-focus) | Finds the nearest item in a direction without moving focus.              |
| [`createTypeahead`](/docs/core/behaviors/focus#typeahead)                               | Finds an item as someone types its name.                                 |
| [`createFocusRecovery`](/docs/core/behaviors/focus#focus-recovery)                      | Restores focus when the focused item is removed.                         |
| [`keepFocus`](/docs/core/behaviors/focus#focus-that-follows-a-move)                     | Preserves focus through a change that moves an element.                  |
| [`inputHints`](/docs/core/behaviors/focus#input-hints)                                  | Picks the on-screen keyboard and autofill for a kind of field.           |

## Text

| Helper                                                        | What It Does                                                               |
| ------------------------------------------------------------- | -------------------------------------------------------------------------- |
| [`createInputHistory`](/docs/core/text#bring-back-earlier-messages)   | Brings back earlier entries with ArrowUp and ArrowDown, like a terminal.   |
| [`isTypeaheadKey`](/docs/core/text#find-an-item-by-typing)            | Checks whether a key can be used for typeahead.                            |
| [`labelOf`](/docs/core/text#what-an-item-is-called)                   | Reads an element's label for matching typed text.                          |
| [`isComposing`](/docs/core/text#properly-handle-input-method-editors) | Checks whether an input event is part of text that's still being composed. |
| [`pageLocale`](/docs/core/text#the-pages-language)                    | Reads the language of the page, or of one section of it.                   |
| [`userLocale`](/docs/core/text#the-pages-language)                    | Reads the browser's preferred language.                                    |
| [`toLocale`](/docs/core/text#tags-from-elsewhere)                     | Turns a tag like `en_US` into one that `Intl` accepts.                     |

### Search Matching

Import these helpers from `@ui-sdk/core/text-match`.

| Helper                                                 | What It Does                                                  |
| ------------------------------------------------------ | ------------------------------------------------------------- |
| [`fuzzyScore`](/docs/core/text#rank-what-someone-searches-for) | Scores how well a piece of text matches what someone typed.   |
| [`matchRanges`](/docs/core/text#highlight-what-matched)        | Finds where the typed text appears in a piece of text.        |
| [`matchSegments`](/docs/core/text#highlight-what-matched)      | Splits text into matched and unmatched pieces you can render. |

## Selection

| Helper                                                | What It Does                                                     |
| ----------------------------------------------------- | ---------------------------------------------------------------- |
| [`createSelection`](/docs/core/behaviors/selection#selecting-items)      | Tracks selected items, including multiple selections and ranges. |
| [`createLasso`](/docs/core/behaviors/selection#rectangle-selection)      | Selects items touched by a rectangle drawn with the pointer.     |
| [`createCellRange`](/docs/core/behaviors/selection#ranges-of-cells)      | Selects a rectangular range of grid cells.                       |
| [`byCellRange`](/docs/core/behaviors/selection#select-a-block)           | Updates only the cells that join or leave a range.               |
| [`cellRangeMessage`](/docs/core/behaviors/selection#selecting-from-code) | Provides the default announcements for a range of cells.         |
| [`cellsToText`](/docs/core/behaviors/selection#copy-and-paste)           | Converts cell values to text for copying.                        |
| [`textToCells`](/docs/core/behaviors/selection#copy-and-paste)           | Parses pasted text into rows of cell values.                     |

## Drag and Drop

| Helper                                                              | What It Does                                                       |
| ------------------------------------------------------------------- | ------------------------------------------------------------------ |
| [`bindDrag`](/docs/core/behaviors/drag-and-drop#pointer-drags)                         | Tracks a pointer drag with capture, thresholds, and cancellation.  |
| [`dragThreshold`](/docs/core/behaviors/drag-and-drop#follow-a-pointer)                 | Sets the standard drag threshold to 3 pixels.                      |
| [`createReorder`](/docs/core/behaviors/drag-and-drop#reordering)                       | Reorders a list or grid with the pointer or keyboard.              |
| [`createTreeReorder`](/docs/core/behaviors/drag-and-drop#reordering-a-tree)            | Reorders and nests tree items with their descendants.              |
| [`createTransfer`](/docs/core/behaviors/drag-and-drop#moving-between-lists)            | Moves items within or between lists.                               |
| [`bindDragPreview`](/docs/core/behaviors/drag-and-drop#dragging-a-copy)                | Shows a copy of the dragged element above the page.                |
| [`createAutoScroll`](/docs/core/behaviors/drag-and-drop#scrolling-while-dragging)      | Scrolls a container when a drag approaches its edge.               |
| [`settleDraft`](/docs/core/behaviors/drag-and-drop#keeping-focus-and-the-draft)        | Keeps a draft visible while a controlled value catches up.         |
| [`reorderMessage`](/docs/core/behaviors/drag-and-drop#whats-read-out)                  | Provides the default announcements for reordering a list.          |
| [`subtreeEnd`](/docs/core/behaviors/drag-and-drop#limits-and-moving-from-code)         | Finds the first row index after a subtree.                         |
| [`treeReorderMessage`](/docs/core/behaviors/drag-and-drop#limits-and-moving-from-code) | Provides the default announcements for reordering a tree.          |
| [`transferMessage`](/docs/core/behaviors/drag-and-drop#a-board-with-rules)             | Provides the default announcements for moving items between lists. |

## Dragging and Resizing

| Helper                                                               | What It Does                                                        |
| -------------------------------------------------------------------- | ------------------------------------------------------------------- |
| [`createMove`](/docs/core/behaviors/direct-manipulation#moving-in-two-dimensions)       | Moves freely positioned objects with the pointer or keyboard.       |
| [`createResize`](/docs/core/behaviors/direct-manipulation#resizing-boxes)               | Resizes boxes from their edges and corners.                         |
| [`createSwipeActions`](/docs/core/behaviors/direct-manipulation#swiping-rows-aside)     | Reveals actions behind a row and supports full-swipe actions.       |
| [`bindHold`](/docs/core/behaviors/direct-manipulation#pressing-and-holding)             | Runs an action once a press is held, and can repeat it while held.  |
| [`bindRepeat`](/docs/core/behaviors/direct-manipulation#repeat-while-held)              | Steps once when a button is pressed, and keeps stepping while held. |
| [`createArea`](/docs/core/behaviors/direct-manipulation#two-dimensional-values)         | Picks a value along two axes, such as a point on a pad.             |
| [`createSpans`](/docs/core/behaviors/direct-manipulation#ranges-on-tracks)              | Draws, moves, and resizes ranges on tracks.                         |
| [`stackSpans`](/docs/core/behaviors/direct-manipulation#days-that-run-down)             | Places overlapping ranges in separate lanes.                        |
| [`createPreview`](/docs/core/behaviors/direct-manipulation#previews)                    | Tracks a value being tried before it is chosen.                     |
| [`moveMessage`](/docs/core/behaviors/direct-manipulation#several-at-once)               | Provides the default announcements for changes in position.         |
| [`resizeMessage`](/docs/core/behaviors/direct-manipulation#several-boxes-and-from-code) | Provides the default announcements for resizing boxes.              |
| [`isSpanFree`](/docs/core/behaviors/direct-manipulation#changing-ranges-from-code)      | Checks whether a proposed range overlaps another on its track.      |
| [`spansMessage`](/docs/core/behaviors/direct-manipulation#changing-ranges-from-code)    | Provides the default announcements for changes to ranges.           |

## Lists

| Helper                                                       | What It Does                                                                 |
| ------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| [`createListbox`](/docs/core/behaviors/lists#options-you-search)                | Highlights options with the arrow keys, and filters them as someone types.   |
| [`createVirtualizer`](/docs/core/behaviors/lists#long-lists)                    | Calculates which rows to render and where to place them.                     |
| [`createStickToBottom`](/docs/core/behaviors/lists#logs-that-follow-their-end)  | Follows new content while preserving the reader's place when they scroll up. |
| [`bindScrollPicker`](/docs/core/behaviors/lists#wheels-you-scroll-to-pick-from) | Picks the option at the center of a scrolling list, like a wheel.            |
| [`createInlineEdit`](/docs/core/behaviors/lists#editing-in-place)               | Manages editing, committing, and canceling a value in place.                 |

## Trees

| Helper                                              | What It Does                                                         |
| --------------------------------------------------- | -------------------------------------------------------------------- |
| [`createTreeCollection`](/docs/core/behaviors/trees#a-trees-shape)     | Looks up parents, children, levels, and visible nodes.               |
| [`treeDataNodes`](/docs/core/behaviors/trees#tree-data-and-file-paths) | Converts nested items into nodes for a tree collection.              |
| [`treeFromPaths`](/docs/core/behaviors/trees#tree-data-and-file-paths) | Builds nested tree data from file paths.                             |
| [`visibleTreeRows`](/docs/core/behaviors/trees#flat-rows)              | Flattens open branches into rows with parent, level, and index data. |
| [`treeCheckedStates`](/docs/core/behaviors/trees#check-a-branch)       | Calculates checked, unchecked, and mixed states across a tree.       |
| [`toggleTreeChecked`](/docs/core/behaviors/trees#check-a-branch)       | Returns the next checked value when a node is toggled.               |

## Transitions and Gestures

| Helper                                                         | What It Does                                                                       |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| [`bindPanel`](/docs/core/behaviors/motion#panels-and-presence)                    | Coordinates panel height, transitions, and focus when opening or closing.          |
| [`hiddenAttrs`](/docs/core/behaviors/motion#find-in-page-and-opening-at-once)     | Sets visibility attributes for hidden or searchable content.                       |
| [`bindFindable`](/docs/core/behaviors/motion#find-in-page-on-its-own)             | Reveals hidden content when the browser finds a match.                             |
| [`supportsHiddenUntilFound`](/docs/core/behaviors/motion#find-in-page-on-its-own) | Checks whether the browser can search hidden content.                              |
| [`animateIn`](/docs/core/behaviors/motion#entering-and-leaving)                   | Applies the starting state for a CSS entrance animation.                           |
| [`animateOut`](/docs/core/behaviors/motion#entering-and-leaving)                  | Applies the exit state and calls your completion callback after animations finish. |

### Gesture Calculations

Import these helpers from `@ui-sdk/core/gesture`.

| Helper                                                 | What It Does                                                             |
| ------------------------------------------------------ | ------------------------------------------------------------------------ |
| [`createVelocityTracker`](/docs/core/behaviors/motion#throws-and-springs) | Measures velocity from recent pointer positions.                         |
| [`projectDistance`](/docs/core/behaviors/motion#throws-and-springs)       | Estimates how far a moving value will travel as it slows down.           |
| [`solveSpring`](/docs/core/behaviors/motion#throws-and-springs)           | Calculates a spring's position and velocity over time.                   |
| [`rubberBand`](/docs/core/behaviors/motion#past-an-edge)                  | Adds resistance as a value moves past an edge.                           |
| [`sectorOf`](/docs/core/behaviors/motion#which-way-a-stroke-points)       | Converts a stroke's direction into a sector, such as a radial menu item. |

## Popups and Layers

| Helper                                                               | What It Does                                                           |
| -------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [`createPopup`](/docs/core/behaviors/popups#make-your-own)                              | Manages opening, closing, positioning, and focus using a popup preset. |
| [`popupState`](/docs/core/behaviors/popups#a-popup-of-your-own)                         | Creates the initial open, mounted, and payload state.                  |
| [`popupTrigger`](/docs/core/behaviors/popups#a-popup-of-your-own)                       | Builds a trigger slot that opens and closes the popup.                 |
| [`popupContent`](/docs/core/behaviors/popups#a-popup-of-your-own)                       | Builds a content slot with presence, placement, and focus handling.    |
| [`popupClose`](/docs/core/behaviors/popups#a-popup-of-your-own)                         | Builds a slot that closes the popup.                                   |
| [`popupTitle`](/docs/core/behaviors/popups#one-popup-many-triggers)                     | Connects a visible title to the popup's accessible name.               |
| [`popupDescription`](/docs/core/behaviors/popups#one-popup-many-triggers)               | Connects descriptive text to the popup.                                |
| [`popupArrow`](/docs/core/behaviors/popups#one-popup-many-triggers)                     | Builds an arrow slot that follows the popup's placement.               |
| [`popupBackdrop`](/docs/core/behaviors/popups#every-part-and-parts-of-your-own)         | Builds a backdrop slot behind a modal popup.                           |
| [`popupViewport`](/docs/core/behaviors/popups#every-part-and-parts-of-your-own)         | Builds a full-screen container slot for a popup sheet.                 |
| [`popupSlots`](/docs/core/behaviors/popups#every-part-and-parts-of-your-own)            | Builds the standard popup parts together.                              |
| [`position`](/docs/core/behaviors/popups#placing-a-popup)                               | Places an element beside an anchor and updates its placement.          |
| [`bindLayer`](/docs/core/behaviors/popups#layers-of-your-own)                           | Registers a floating element for Escape and outside-press dismissal.   |
| [`bindPersistentLayer`](/docs/core/behaviors/popups#modal-layers-and-what-stays-usable) | Keeps an element usable across layers, including modal popups.         |
| [`isDismissal`](/docs/core/behaviors/popups#modal-layers-and-what-stays-usable)         | Identifies a dismissal reason, such as Escape or an outside press.     |
| [`supportsTopLayer`](/docs/core/behaviors/popups#types-and-the-top-layer)               | Checks whether the browser supports the top layer used by popups.      |

[Popup presets](/docs/core/behaviors/popups#pick-its-behavior) choose the interaction for a popover, dialog, tooltip, or hover card. [Popup controllers](/docs/core/behaviors/popups#open-from-code) open existing popup components from code and wait for a result. Import each from its component entrypoint, such as `@ui-sdk/core/popover`.

## Preferences

| Helper                                                             | What It Does                                                                       |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
| [`createPreference`](/docs/core/behaviors/preferences#create-a-preference)            | Holds a choice from a list, notifies subscribers, and can save it between visits.  |
| [`createColorScheme`](/docs/core/behaviors/preferences#choose-a-color-scheme)         | Builds on a preference to choose light, dark, or the browser's scheme.             |
| [`colorSchemeOf`](/docs/core/behaviors/preferences#browser-preferences-on-the-server) | Reads the color scheme a browser sends with a request.                             |
| [`preferencesScript`](/docs/core/behaviors/preferences#server-rendering)              | Puts saved preferences on their attributes before the first paint.                 |
| [`createPointerKind`](/docs/core/mobile#pointer-kind)                      | Reports whether the main pointer is a finger or a mouse, and whether it can hover. |
| [`pointerKindOf`](/docs/core/mobile#render-on-the-server)                  | Guesses the pointer kind from a request's headers.                                 |

### Storage

| Helper                                                          | What It Does                                                      |
| --------------------------------------------------------------- | ----------------------------------------------------------------- |
| [`createLocalStorage`](/docs/core/storage#keep-a-value)                 | Keeps a value in localStorage, for every tab, until it's removed. |
| [`createSessionStorage`](/docs/core/storage#keep-a-value)               | Keeps a value in sessionStorage, for the tab, while it's open.    |
| [`createCookieStorage`](/docs/core/storage#read-a-cookie-on-the-server) | Keeps a value in a cookie, which the server reads too.            |

## Canvas

| Helper                                               | What It Does                                                                |
| ---------------------------------------------------- | --------------------------------------------------------------------------- |
| [`createViewport`](/docs/core/behaviors/canvas#panning-and-zooming)     | Pans and zooms a canvas and converts between screen and canvas coordinates. |
| [`createConnect`](/docs/core/behaviors/canvas#connections)              | Tracks connections between ports with the pointer or keyboard.              |
| [`connectMessage`](/docs/core/behaviors/canvas#snapping-words-and-code) | Provides the default announcements for connection steps.                    |

## Platform

| Helper                                                     | What It Does                                                        |
| ---------------------------------------------------------- | ------------------------------------------------------------------- |
| [`announce`](/docs/core/platform#announcements)                    | Reads a message out to screen readers.                              |
| [`prepareAnnouncements`](/docs/core/platform#urgent-announcements) | Adds the regions screen readers listen to before the first message. |
| [`isRTL`](/docs/core/platform#direction)                           | Checks whether an element's text runs right to left.                |
| [`matchesShortcut`](/docs/core/platform#shortcuts)                 | Checks whether a key press matches a shortcut, such as `mod+b`.     |
| [`formatShortcut`](/docs/core/platform#shortcuts)                  | Writes a shortcut the way the user's platform shows it.             |
| [`ariaKeyshortcuts`](/docs/core/platform#shortcuts)                | Writes a shortcut as an `aria-keyshortcuts` value.                  |

### Mobile

| Helper                                                         | What It Does                                          |
| -------------------------------------------------------------- | ----------------------------------------------------- |
| [`bindViewport`](/docs/core/mobile#follow-the-viewport)                | Follows the visible viewport and reports each change. |
| [`bindAvoidKeyboard`](/docs/core/mobile#keep-a-bar-above-the-keyboard) | Lifts an element above the on-screen keyboard.        |

## Changes and History

| Helper                                                                   | What It Does                                                                      |
| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| [`createChange`](/docs/core/kernel/handle-changes#changes)                       | Asks to change a state value, calling its callback first.                         |
| [`createCommit`](/docs/core/kernel/handle-changes#commits)                       | Reports the final value when an interaction ends.                                 |
| [`dispatch`](/docs/core/kernel/handle-changes#events-that-arent-state)           | Calls an action's callback, such as `onDelete`, and tells you if it was canceled. |
| [`createUndoStack`](/docs/core/kernel/handle-changes#undo)                       | Keeps snapshots of a value you record, so you can undo and redo.                  |
| [`createController`](/docs/core/kernel/handle-changes#controllers)               | Lets code outside a component call its methods.                                   |
| [`sourceOf`](/docs/core/kernel/handle-changes#how-people-are-working)            | Tells whether an event came from a mouse, touch, pen, keyboard, or code.          |
| [`isFocusFromKeyboard`](/docs/core/kernel/handle-changes#how-people-are-working) | Checks whether focus just arrived from the keyboard.                              |

### Watching Changes

Import these helpers from `@ui-sdk/core/observe`.

| Helper                                                    | What It Does                                             |
| --------------------------------------------------------- | -------------------------------------------------------- |
| [`observe`](/docs/core/observe#listen-for-changes)                | Calls you with every change to the components on a page. |
| [`elementOf`](/docs/core/observe#find-the-element)                | Finds the element of the component a change came from.   |
| [`withSource`](/docs/core/observe#keep-the-source-after-an-await) | Keeps a change's source across an `await`.               |

## Building Blocks

| Helper                                                              | What It Does                                                              |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| [`definePrimitive`](/docs/core/kernel/define-a-primitive#defineprimitive)   | Defines a component's options, state, and parts once for every framework. |
| [`idPart`](/docs/core/kernel/define-a-primitive#parts-that-come-and-go)     | Escapes an item value so it can be part of an id.                         |
| [`elements`](/docs/core/kernel/define-a-primitive#reading-parts-in-the-api) | Returns a component's bound parts in page order.                          |
| [`openAttrs`](/docs/core/kernel/define-a-primitive#naming)                  | Returns the usual attributes for an open or closed part.                  |
| [`checkedAttrs`](/docs/core/kernel/define-a-primitive#naming)               | Returns the usual attributes for a checked, unchecked, or mixed part.     |
| [`css`](/docs/core/kernel/style-a-component#pass-values-as-css-variables)   | Turns style declarations into a `style` attribute and skips empty values. |
| [`live`](/docs/core/kernel/handle-changes#live-state)                       | Writes attributes for state that changes often, without rendering again.  |
| [`selects`](/docs/core/kernel/handle-changes#live-state)                    | Tells each part which state changes it needs to hear about.               |
| [`direct`](/docs/core/kernel/handle-changes#attributes-kept-current)        | Keeps chosen attributes current between renders.                          |

## Agents

Import these helpers from `@ui-sdk/core/agent`.

| Helper                                                                      | What It Does                                                       |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| [`createAgent`](/docs/agents/connect-an-agent/reference#createagentoptions) | Lets an agent read the components on a page and use them.          |
| [`agentTools`](/docs/agents/connect-an-agent/reference#agenttools)          | Describes the `snapshot`, `act`, and `query` tools for your model. |
| [`registerTools`](/docs/agents/connect-an-agent/webmcp#register-the-tools)  | Offers the same tools to an agent built into the browser.          |

### History

Import these helpers from `@ui-sdk/core/history`.

| Helper                                                                             | What It Does                                                                                            |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| [`createHistory`](/docs/agents/connect-an-agent/history-and-undo#start-recording)  | Records every change to the page's components and who made it, so you can step back or undo one source. |
| [`describeEntry`](/docs/agents/connect-an-agent/history-and-undo#read-the-history) | Writes a short sentence for a history entry.                                                            |
| [`stageChanges`](/docs/agents/connect-an-agent/history-and-undo#try-a-suggestion)  | Tries a set of values on the real controls and lets you put the old ones back.                          |

## Values and Testing

[Number](/docs/core/number), [Date](/docs/core/date), [Color](/docs/core/color), and [Image](/docs/core/image) cover formatting, parsing, and math for each kind of value. Each has its own entrypoint, such as `@ui-sdk/core/number`. [Testing](/docs/core/testing) covers the checks for a component of your own.