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.

referencesweb-components.md

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

Web components

What the @ui-sdk/web types don't say, learned by probing.

Setup

  • Install @ui-sdk/web at the same version as @ui-sdk/core if it's missing.
  • There's no primitive entry. createParts, wrappedButton and the element types, like UiInputElement, come from @ui-sdk/web itself.
  • A component entry, like @ui-sdk/web/input, defines its elements when imported. It also exports the component's types and its controller factory when it has one, like createInputController. A define…Elements() function you may find in another .d.ts isn't what the entry exports, and calling it fails.

Without a bundler

A plain HTML page, like an Artifact, loads our elements and their default styles with two tags in its <head>:

<script type="module" src="https://ui-sdk.dev/web.js"></script>
<link rel="stylesheet" href="https://ui-sdk.dev/web.css" />

Read https://ui-sdk.dev/web.md first: the web components docs in one file, for a page like this. web.js defines each element the first time its tag appears, so leave out imports that only define elements, like import "@ui-sdk/web/popover". What an entry exports comes from its own file, like createPopoverController from https://ui-sdk.dev/web/popover.js. To build elements of your own, import the behaviors, definePrimitive and createParts from https://ui-sdk.dev/web/core.js. It has everything in @ui-sdk/core's root, but not subpaths like @ui-sdk/core/tabs or helpers like toast(). Use the /web/ paths with web.js and the /web@0/ paths with web@0.js, so the page loads one release.

Tag names and markup

Each component's page, like node_modules/@ui-sdk/web/docs/components/input.md, shows its tags and markup. node_modules/@ui-sdk/web/custom-elements.json lists every tag each entry defines, with its attributes and their types, properties, the controller's methods on .api, events, parts and data attributes. Search it for a tag, like "tagName": "ui-input-group", before probing. To confirm what an entry defines, probe it:

import "@ui-sdk/web/input"
for (const tag of ["ui-input", "ui-input-group", "ui-input-clear"])
  console.log(tag, !!customElements.get(tag))

Parts that keep native behavior need the native element inside them. The console says which: <ui-input> needs its native element inside it for "root". For example:

<ui-input-group>
  <ui-input><input aria-label="Search" /></ui-input>
  <ui-input-clear><button aria-label="Clear">×</button></ui-input-clear>
</ui-input-group>

Elements of your own

createParts reads attributes and properties from the primitive's options schema, so give definePrimitive one, like options: { clearOnEscape: "boolean", input: "value" }. Every attribute option gets a property that reflects it, like el.clearOnEscape = true. Name booleans that start on in the root's defaults, like defaults: { loop: true }, so the property reads true without the attribute. Options the page provides go in the root's options:

createParts(clearableInput, {
  root: {
    tag: "ui-clearable-input",
    display: "block",
    // Read lazily: elements inside may upgrade after this one.
    options: (el) => ({
      input: () => el.querySelector<UiInputElement>("ui-input")?.api,
    }),
  },
})
  • Our elements expose their controller as .api and may not take a controller property, unlike their React components. If your primitive drives one of ours through a controller, take the controller as an option (a function, read when needed), so React can pass its own and web components can pass .api.
  • Don't bind a slot of yours to a native element one of ours binds. Both roots would write data-slot to it. Listen from a wrapper slot instead.

Differences from React

  • Parts that aren't present stay in written markup, with hidden. React removes them. A test helper that checks presence should treat hidden as absent.
  • Changes fire events, like valuechange on <ui-input>, with { value, reason } in detail. preventDefault() cancels the change.
  • Rendering custom elements from React JSX needs their tags in React.JSX.IntrinsicElements. Don't name the props type Element inside namespace JSX: it shadows JSX.Element.

Testing

Import the module that defines your elements in beforeAll, mount markup with innerHTML, and wait a tick before asserting, since parts register and sync after they connect. Dispatch real events with bubbles: true:

const event = new KeyboardEvent("keydown", {
  key: "Escape",
  bubbles: true,
  cancelable: true,
})
field.dispatchEvent(event)

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