Index of every page on this site: llms.txt
All skills
Run it yourself

Builds interfaces with ui-sdk in React, Vue, Svelte, Solid or web components. Covers choosing and composing its components, building a component or behavior it doesn't ship from @ui-sdk/core (like a stepper, splitter, transfer list or emoji picker), making the interface usable by agents through createAgent, agent tools and WebMCP, and testing keyboard, focus, ARIA, server rendering and right to left, including writing tests for an existing component. Use whenever a project has @ui-sdk/* installed or the user mentions ui-sdk.

Use this Skill: https://skilld.dev/gh/vercel-labs/ui/ui-sdk

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencespatterns.md

≈2.4k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Patterns the blocks leave to you

Each snippet comes from a component that passes its tests. Adapt the names. When a block grows to cover one of these, delete the pattern.

Grid arrows with createRovingFocus and move

A set of choices in two dimensions, like emoji, colors or dates, is a grid of rows and gridcells, and the root has a name. Use createGridFocus only when every row has the same columns, like a calendar. A spreadsheet adds createCellRange for a block of cells, and copies and pastes it with range.text, cellsToText and textToCells rather than its own tab-separated parser. Emoji, swatches and other lists that wrap into rows are a flowing grid: createRovingFocus with the move below. A set in one dimension is a listbox of options. Don't use plain buttons for the cells.

For a grid whose rows and columns are in state. Keys find cells by id, not by index. Past an edge, return from.key so the arrow is handled and the page doesn't scroll.

type CellProps = { value: string; row: string; column: string }
const cellKey = (row: string, column: string) => `${row}\u001f${column}`

const roving = createRovingFocus<State, CellProps>(context, {
  slot: "cell",
  key: "focused",
  move: (event, { from, rtl }) => {
    const { rows, columns } = store.get()
    const row = rows.findIndex((r) => r.id === from.props.row)
    const column = columns.findIndex((c) => c.id === from.props.column)
    const corner = event.ctrlKey || event.metaKey
    const lastRow = rows.length - 1
    const lastColumn = columns.length - 1
    const to = (
      {
        ArrowRight: [row, column + (rtl ? -1 : 1)],
        ArrowLeft: [row, column + (rtl ? 1 : -1)],
        ArrowDown: [row + 1, column],
        ArrowUp: [row - 1, column],
        Home: corner ? [0, 0] : [row, 0],
        End: corner ? [lastRow, lastColumn] : [row, lastColumn],
      } as Record<string, [number, number]>
    )[event.key]
    if (!to) return undefined
    return rows[to[0]] && columns[to[1]]
      ? cellKey(rows[to[0]].id, columns[to[1]].id)
      : from.key
  },
})

For a grid that flows items into rows, like an emoji or swatch grid, work from the index in items and a columns count instead. Down from a column the short last row lacks should land on its last item.

Shift is never swallowed, so a grid that selects rows extends from what roving.keydown returns:

const moved = roving.keydown(event, el)
if (moved?.shift && rowOf(moved.key) !== rowOf(moved.from)) {
  selection.extend(rowOf(moved.key), {
    from: rowOf(moved.from),
    reason: "list-navigation",
    event,
  })
}

createRovingFocus: remember: false

With remember: false, the stop stays on the preferred item even while focus moves elsewhere in the group, so the focused item can have tabindex="-1". That's right for a radio group, where selection follows focus. Anywhere else, keep the default and move focus explicitly with roving.focus(key).

State derived from options and state

sync sees only options. When derived state depends on both, like lists split by an option (items) and a value that may be controlled, recompute in a store subscription that compares references. That covers every way either input changes:

let derivedFrom = { items: store.get().items, value: store.get().value }
context.onDestroy(
  store.subscribe(() => {
    const { items, value } = store.get()
    if (items === derivedFrom.items && value === derivedFrom.value) return
    derivedFrom = { items, value }
    store.set(split(items, value))
  })
)

Storing the derived arrays, rather than computing them in a slot's state, is the safe choice: whether a part compares arrays by value isn't documented.

Selection in internal state

createSelection infers its reasons from an on<Key>Change option. Internal state has none, so spell out the generics, and write with store.set:

type SelectionReason = "item-press" | "list-navigation" | "select-all"
const selection = createSelection<Options, State, "selected", SelectionReason>(
  context,
  {
    key: "selected",
    set: (selected) => (store.set({ selected }), true),
    order: () => store.get().ids,
    multiple: () => true,
    selectable: (id) => !itemById(id)?.disabled,
  }
)

Clicks map to it like this. press gets the click, so read its modifiers:

const mouse = event as MouseEvent | undefined
if (mouse?.shiftKey)
  selection.extend(id, {
    from: store.get().focused,
    reason: "item-press",
    event: mouse,
  })
else if (mouse?.ctrlKey || mouse?.metaKey)
  selection.toggle(id, { reason: "item-press", event: mouse })
else selection.choose(id, { reason: "item-press", event: mouse })

selects on an array key takes an array of values: selects({ selected: ({ key }) => [key] }). On a scalar key, a value or a pair: selects({ focused: ({ key }) => [key, null] }).

Typeahead in a roving group

createTypeahead() returns the search function itself, with reset() and active() on it. Let Space continue a query in progress, else let it toggle:

if (isTypeaheadKey(event) && (event.key !== " " || typeahead.active())) {
  const items = roving.items()
  const index = typeahead(
    event.key,
    items.map((item) => labelOf(item.el)),
    items.findIndex((item) => item.el === el)
  )
  if (index !== -1) {
    event.preventDefault()
    roving.focus(items[index].key)
  }
  return
}

A search box over options with createListbox

Keep focus in the input and highlight options with aria-activedescendant. The input is a combobox, each option an option, and choosing is a value you write with createChange:

const listbox = createListbox(context, {
  key: "highlighted",
  focus: "virtual",
  query: () => context.store.get().query,
})
input: slot({
  attrs: (state, { id, api }) => ({
    role: "combobox",
    "aria-expanded": "true",
    "aria-controls": `${id}-list`,
    "aria-activedescendant": api.listbox.activeId(state),
  }),
  on: {
    input: (event, { api }) => api.search((event.target as HTMLInputElement).value),
    keydown: (event, { api }) => api.keydown(event),
  },
}),
option: slot<{ value: string }>({
  role: "option",
  focus: "active-descendant",
  props: { value: "string" },
  selects: selects({ highlighted: ({ key }) => [key, null] }),
  present: (_state, part) => part.api.listbox.shows(part),
  attrs: (state, part) => ({
    ...part.api.listbox.attrs(state, part),
    "aria-selected": String(state.value === part.key),
  }),
  press: ({ key, api }, event) => api.choose(key, event),
  on: {
    pointerdown: (event) => event.preventDefault(),
    pointermove: (event, { key, api }) => api.listbox.highlight(key, { event }),
  },
  bind: (el, part) => part.api.listbox.bind(el, part),
}),

api.search writes the query and calls listbox.move("first"), and api.keydown chooses the highlighted key on Enter before passing other keys to listbox.keydown. pointerdown keeps focus in the input. For options from data, pass items and render listbox.items().

A createFocusRecovery fallback

fallback runs after the state change, so the part that left is already gone from your lists. Walk a stable order from its key to find the neighbor that's still there, the next one first:

const recovery = createFocusRecovery<{ value: string; list: string }>({
  fallback: (lost) => {
    const { items } = store.get()
    const list = store.get()[lost.props.list]
    const at = items.findIndex((item) => item.id === lost.key)
    const next =
      items.slice(at + 1).find((item) => list.includes(item.id)) ??
      items
        .slice(0, Math.max(at, 0))
        .reverse()
        .find((item) => list.includes(item.id))
    // `slotOf` maps a list to its option slot. Return nothing to let focus go.
    return next ? context.element(slotOf(lost.props.list), next.id) : undefined
  },
})
// Bind it next to the roving group in the item slot:
bind: (el, part) => {
  const cleanups = [
    part.api.roving.bind(el, part),
    part.api.recovery.bind(el, part),
  ]
  return () => cleanups.forEach((cleanup) => cleanup())
}

Two groups of the same kind

Two lists side by side need two createRovingFocus groups, and a group is one slot. So give each list its own option slot, built by one function inside slots, and keep each block on the api by side:

slots: (slot) => {
  const option = (side: Side) =>
    slot<OptionProps>({
      role: "option",
      props: { value: "string" },
      attrs: (state, part) => ({
        tabindex: part.api.blocks[side].roving.tabIndex(state, part),
      }),
      // …
    })
  return { available: option("available"), chosen: option("chosen") /* … */ }
}

Focus into a field from a grid

To let typing in a grid go back to its search field, focus the field on keydown and don't prevent the default. The browser types the character into the newly focused field. jsdom doesn't, so check this one in a real browser.

Reasons the vocabulary lacks

Declare them in the callback's type, with a one-line comment naming which aren't shared:

// "select-all" isn't in the shared vocabulary.
export type DataGridValueChangeReason =
  "item-press" | "list-navigation" | "select-all"

Stepper

A stepper is a list of buttons with one tab stop, and the current step has aria-current="step". Don't use radio or tab roles for it. A step a person can't go to yet is aria-disabled.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning1d3 checks · Risk SAFE
  • Gen Agent Trust Hub1d

    This skill provides a comprehensive guide for using the `ui-sdk` library to build accessible web interfaces and integrate them with AI agents. It includes security-conscious features like agent-specific confirmation attributes and secret field masking. The primary security consideration is the inherent attack surface for indirect prompt injection when an agent interacts with UI content, which the skill acknowledges and provides tools to manage.

  • Socket1d

    No alerts

  • Snyk1d

    Risk: MEDIUM · 1 issue

Signed by skilld at fb6945a. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 14 hours ago.

Activeupdated last week

README badge

README badge for vercel-labs/ui/ui-sdk