Vercel UI SDK Setup Guide for Next.js and Nuxt (2026)

Vercel UI SDK guide covering what the new headless UI library is, how to set it up in Next.js and Nuxt, style and test it, and let AI agents use your UI.
· 13 min read
Vercel Labs released UI SDK on 12 November 2026. Despite the name, it has nothing to do with calling language models; that's the AI SDK. UI SDK is a TypeScript library of UI behaviors such as focus, keyboard navigation, selection, popups, drag and drop, and the ARIA they need. On top of them sit 55 unstyled components and a bridge that lets AI agents use the interface directly.
I build Nuxt and React front ends, so I set up the beta in a React project and a Nuxt 4 app to write this. This guide covers what UI SDK is, how to install it in Next.js and Nuxt, how styling and custom components work, and where the agent features fit. Everything was checked against 0.1.0-beta.1, the current release at the time of writing. It's a beta, so expect some APIs to change.
What is Vercel's UI SDK?
UI SDK is an open-source TypeScript library of UI behaviors from Vercel Labs. Behaviors are the tested pieces that make components work, such as roving focus, typeahead, popups and selection. Vercel ships 55 unstyled components built from them for React, Vue, Svelte, Solid and Web Components, plus an agent bridge that lets AI agents read and operate the interface.
The key facts:
- Who makes it. Vercel Labs. The source is at github.com/vercel-labs/ui under the Apache-2.0 licence, and the docs live at ui-sdk.dev.
- Status. A public beta, released on 12 November 2026. Every package is at
0.1.0-beta.1. - What you get
- more than 50 behaviors in
@ui-sdk/core; - 55 components, from Accordion to Waterfall, including Select, Combobox, Dialog, Date Picker, Color Picker, Token Input and Tree;
- a testing kit;
- the agent bridge.
- more than 50 behaviors in
- No styles. Components render no CSS of their own. An optional stylesheet gives them a neutral default look.
| Framework | Package | Notes |
|---|---|---|
| React, Next.js | @ui-sdk/react | React 19+; @types/react 19.2.10+ for TypeScript |
| Vue, Nuxt | @ui-sdk/vue | Vue 3.5+; includes a Nuxt module |
| Svelte | @ui-sdk/svelte | Same parts, Svelte components |
| Solid | @ui-sdk/solid | Same parts, Solid components |
| Web Components | @ui-sdk/web | Custom elements such as <ui-toggle>, usable without a build step |
Every framework package needs @ui-sdk/core installed next to it. Core holds the behaviors and is a peer dependency, so one copy serves the components and any helpers you import.
UI SDK vs AI SDK
They solve different problems. The AI SDK connects your app to language models. UI SDK builds the interface, and lets agents use it.
| Vercel AI SDK | Vercel UI SDK | |
|---|---|---|
| What it does | Calls models for text, structured output, tools and streaming chat | Builds accessible components from behaviors and exposes them to agents |
| Main APIs | streamText, generateText, useChat | definePrimitive, createParts, <Select>, createAgent |
| Packages | ai, @ai-sdk/react, provider packages | @ui-sdk/core, @ui-sdk/react, @ui-sdk/vue and others |
| Status | Stable, version 7 | Beta, version 0.1 |
Nothing official ties the two together yet, but they fit. UI SDK's agentTools exports plain tool definitions (name, description, JSON Schema) and leaves the model loop to you. So an assistant built with the AI SDK, or any other model SDK, could drive a screen built with UI SDK. If you're new to the AI SDK, my Vercel AI SDK 7 tutorial builds a chat with tools and generative UI in Next.js and Nuxt.
How behaviors, primitives, parts and components fit together
UI SDK has four layers, each built on the one below:
- Behaviors are functions in
@ui-sdk/core, such ascreateRovingFocus(one Tab stop for a group, arrow keys inside it),createTypeahead,createPopup,createSelection,createReorderandcreateVirtualizer. - A primitive puts a component's state, actions and parts together in one framework-agnostic definition, made with
definePrimitive. - Parts are the framework components
createPartsmakes from a primitive, such asRoot,TriggerandContent, rendered as the elements you choose. - Components are the ready-made library (
Dialog,Select,Tabsand the rest). They are built the same way, so you can rebuild any of them under your own names.
The behavior lives in core, and each framework package only connects it to its framework. That's why a Select behaves the same in React, Vue and a custom element. The docs say component tests run in React, Vue and Web Components, and the Dialog page alone lists about 90 automated checks.
How to set up UI SDK in Next.js
You install two packages, optionally import the default stylesheet, and render components straight from your pages. No provider is needed.
1. Check the requirements
You need React 19 and React DOM 19 or newer, which a current Next.js App Router project already uses. With TypeScript, you also need @types/react 19.2.10 or newer.
2. Install the packages
npm install @ui-sdk/react @ui-sdk/core
3. Add the default look (optional)
For a neutral starting point, import web.css once at the top of app/layout.tsx:
// app/layout.tsx
import "@ui-sdk/core/web.css"
import "./globals.css"
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>{children}</body>
</html>
)
}
With Tailwind CSS, import it in your global stylesheet instead, after Tailwind, and declare the ui-sdk layer above both:
/* app/globals.css */
@layer ui-sdk;
@import "tailwindcss";
@import "@ui-sdk/core/web.css" layer(components);
layer(components) puts the default look above Tailwind's base styles and below its utilities, so your classes still win.
The stylesheet follows the system light or dark theme. You theme it with --ui-* custom properties such as --ui-primary, --ui-radius and --ui-font-sans.
4. Render your first component
// app/bookmark-button.tsx
import { Toggle } from "@ui-sdk/react/toggle"
export function BookmarkButton() {
return (
<Toggle className="rounded-md border px-3 py-1.5 text-sm data-pressed:bg-neutral-900 data-pressed:text-white">
Bookmark
</Toggle>
)
}
Toggle renders a <button>, tracks its pressed state, handles Enter and Space, and sets aria-pressed. On the server, <Toggle defaultPressed>Bold</Toggle> renders this HTML. I checked it with React's server renderer:
<button data-slot="toggle" type="button" aria-pressed="true" data-pressed="">Bold</button>
Each component is imported from its own entry, such as @ui-sdk/react/toggle. There is no root import from @ui-sdk/react, so a page only pulls in what it uses.
5. Build a real form control
// app/role-select.tsx
import {
Select,
SelectContent,
SelectItem,
SelectLabel,
SelectTrigger,
SelectValue,
} from "@ui-sdk/react/select"
export function RoleSelect() {
return (
<Select placeholder="Select a role">
<SelectLabel>Role</SelectLabel>
<SelectTrigger>
<SelectValue />
</SelectTrigger>
<SelectContent>
<SelectItem value="viewer">Viewer</SelectItem>
<SelectItem value="editor">Editor</SelectItem>
</SelectContent>
</Select>
)
}
The trigger renders as an ARIA combobox, with aria-haspopup="listbox", aria-expanded and a label reference, and typing while it's closed selects the next match. The same component also handles:
- multiple selection;
- search inside the popup;
- async options;
- groups;
- a "select all" item.
6. Know where "use client" goes
UI SDK's component modules already include "use client". A Server Component page can render <Toggle> or <Select> directly, and the server sends the initial HTML with its ARIA state.
You only add the directive to your own files when they own React state, callbacks or render functions:
// app/mute-toggle.tsx
"use client"
import { Toggle } from "@ui-sdk/react/toggle"
import { useState } from "react"
export function MuteToggle() {
const [muted, setMuted] = useState(false)
return (
<>
<Toggle pressed={muted} onPressedChange={setMuted}>
Mute
</Toggle>
<output>{muted ? "Sound is off" : "Sound is on"}</output>
</>
)
}
How to set up UI SDK in Nuxt (and Vue)
@ui-sdk/vue ships a Nuxt module. Add it to modules, and every part becomes an auto-imported component that renders on the server. Few component libraries make Nuxt this easy on day one.
1. Install the packages
You need Vue 3.5 or newer. The module's peer range covers Nuxt 4 and Nuxt 5.
npm install @ui-sdk/vue @ui-sdk/core
2. Register the module and the stylesheet
// nuxt.config.ts
export default defineNuxtConfig({
modules: ["@ui-sdk/vue"],
css: ["@ui-sdk/core/web.css"],
})
The module adds no plugin and no styles of its own. The css line is the optional default look, so drop it if you style everything yourself.
3. Use components without imports
<!-- pages/index.vue -->
<script setup lang="ts">
const role = ref<string | null>(null)
</script>
<template>
<Dialog>
<DialogTrigger>Share</DialogTrigger>
<DialogBackdrop />
<DialogContent>
<DialogTitle>Share link</DialogTitle>
<DialogDescription>Anyone with the link can view this project.</DialogDescription>
<DialogClose>Done</DialogClose>
</DialogContent>
</Dialog>
<Select v-model:value="role" placeholder="Select a role">
<SelectLabel>Role</SelectLabel>
<SelectTrigger>
<SelectValue />
</SelectTrigger>
<SelectContent>
<SelectItem value="viewer">Viewer</SelectItem>
<SelectItem value="editor">Editor</SelectItem>
</SelectContent>
</Select>
</template>
I prerendered this page with nuxt generate on Nuxt 4. The dialog trigger and the select render on the server with their ARIA attributes, and nothing is imported by hand. Each auto-import still points at its own entry, so a page bundles only the parts it uses.
v-model:value and v-model:open let you own the state. Change events receive details as their second argument, and calling details.cancel() refuses the change.
4. Avoid name clashes with a prefix
If your app already has a Dialog or Select component, yours wins. To use both, give UI SDK a prefix:
// nuxt.config.ts
export default defineNuxtConfig({
modules: ["@ui-sdk/vue"],
uiSdk: { prefix: "U" },
})
With that prefix, <DialogTrigger> becomes <UDialogTrigger>. Nuxt UI already uses the U prefix (USelect, UModal), so if you run both, pick another letter.
Without Nuxt, import parts from their entries (import { Toggle } from "@ui-sdk/vue/toggle"), and put import "@ui-sdk/core/web.css" at the top of main.ts. If you're still choosing between the two frameworks, I compared them in React vs Vue in 2026.
How to style UI SDK components
Style from attributes, not from classes the library adds. Every part has a data-slot attribute, and its state shows up as attributes such as data-pressed, data-open and data-disabled.
- Plain CSS. Select parts and their state:
[data-slot="toggle"] { border: 1px solid #d4d4d4; border-radius: 0.5rem; } [data-slot="toggle"][data-pressed] { background: #171717; color: white; } - Tailwind. Use attribute variants such as
data-pressed:bg-neutral-900anddata-disabled:opacity-50. - React state functions. In a client component,
classNameandstyleaccept a function of the part's state, for exampleclassName={(state) => (state.pressed ? "font-bold" : "font-normal")}. - Animations. Popup content gets
data-starting-stylebefore it enters anddata-ending-stylewhile it leaves, and stays mounted until the exit transition ends. - CSS variables. Popups expose
--anchor-width,--available-heightand--transform-originfor sizing and origin-aware animations. - The cascade layer. UI SDK injects a little CSS (for example, to keep closed popups hidden) into a layer named
ui-sdk. Put@layer ui-sdk;at the top of your global stylesheet so your own styles always win. - Content Security Policy. If your
style-srchas no'unsafe-inline', add<meta property="csp-nonce" nonce="…">to the page head. Server-rendered pages also needstyle-src-attr 'unsafe-inline'for a few style attributes.
How to build your own component with definePrimitive
When the library lacks a component, define a primitive once and render it in any framework. Here's a complete mute button, adapted from the docs:
// lib/mute-button.ts
import { definePrimitive } from "@ui-sdk/core"
export const muteButton = definePrimitive({
name: "mute-button",
state: () => ({ muted: false }),
api: (context) => ({
toggle: () => context.store.set({ muted: !context.store.get().muted }),
}),
slots: (slot) => ({
root: slot({
attrs: (state) => ({
type: "button",
"aria-pressed": String(state.muted),
}),
press: ({ api }) => api.toggle(),
}),
}),
})
Then render it in React:
// components/mute-button.tsx
"use client"
import { createParts } from "@ui-sdk/react/primitive"
import { muteButton } from "@/lib/mute-button"
export const { Root: MuteButton } = createParts(muteButton, { root: "button" })
In Vue, the same two lines import createParts from @ui-sdk/vue/primitive instead. Either way, <MuteButton>Mute</MuteButton> renders <button data-slot="mute-button" type="button" aria-pressed="false">Mute</button>.
Real components combine several behaviors. The docs' icon picker opens with createPopup, gives its grid one Tab stop with createRovingFocus, follows the layout with spatialMove, ranks search results with fuzzyScore and reports the number of matches with announce.
How do AI agents use a UI SDK interface?
Through the agent bridge. createAgent lists the components on the page with their state and available actions, then runs actions through each component's own API. An agent changes a Select the same way your code would, without screenshots or simulated clicks.
import { createAgent } from "@ui-sdk/react/agent"
export const agent = createAgent()
agent.snapshot()
// [{ ref: "c1", component: "input", label: "Project name", value: "Apollo", actions: ["setValue", "clear"] }]
await agent.act({
steps: [{ ref: "Project name", action: "setValue", args: ["Atlas"] }],
})
Vue, Svelte, Solid and Web Components have the same bridge under @ui-sdk/vue/agent, @ui-sdk/svelte/agent and so on. You decide what the agent may do, at three levels:
- An
allowcallback oncreateAgentapproves or refuses each action before it runs. Return a promise to wait for your own confirmation UI. By default it gives up after 5 minutes. - Change callbacks receive
details.source, which is"agent"for the bridge's changes. Calldetails.cancel()to keep the current value. - Marks in your markup
data-agent-confirmalways waits for a person;data-agent-hiddenremoves a region from what the agent sees;data-agent-secretredacts a value.
Password, card and one-time-code fields count as secret without a mark.
<Select
defaultValue="europe"
onValueChange={(value, details) => {
if (details.source === "agent" && value === "asia-pacific") {
details.cancel()
}
}}
>
{/* label, trigger and items */}
</Select>
<Button data-agent-confirm="Charges $20 to your card for 1,000 credits" onClick={buyCredits}>
Buy credits
</Button>
For browser agents, registerTools publishes snapshot, query and act through WebMCP when the browser supports it, and does nothing when it doesn't:
import { createAgent, registerTools } from "@ui-sdk/react/agent"
const agent = createAgent()
const unregister = registerTools(agent, {
allow: (step) => step.action !== "press" || window.confirm(`Press ${step.args[0]}?`),
})
Is it faster than letting an agent click through the page? Vercel's own benchmark says yes, with caveats. An agent renamed a project, updated members and settings, and saved. One run used browser tools on the screen built with another, unnamed component library; the other used the bridge on the same screen built with UI SDK. Both used Sonnet through Claude Code, and the figures are medians of three runs:
| Browser tools | UI SDK agent bridge | Change | |
|---|---|---|---|
| Tool calls | 16 | 5 | −69% |
| Text read (characters) | 39.8k | 6.8k | −83% |
| Time | 41 s | 16 s | −61% |
| Cost | $0.073 | $0.032 | −56% |
That's a vendor benchmark on one task, so treat it as a direction rather than a promise.
Treat what the tools return as untrusted, because a snapshot can include text your users wrote, such as a name in a table row. Gate anything that costs money or deletes data behind a person.
WebMCP works inside a browser tab, with the user's session. When assistants should reach your product without a tab open, you need a remote MCP server instead, which I covered in MCP servers for SaaS.
How to build UI SDK components with a coding agent
Install the UI SDK skill, and point your agent at the docs that ship inside the packages:
npx skills add vercel-labs/ui --skill ui-sdk
Each package carries Markdown docs for its exact version, such as node_modules/@ui-sdk/react/docs/llms.txt. The official setup prompt adds a note to AGENTS.md telling the agent to read them before it touches UI SDK code. For a beta whose APIs are still moving, docs from the installed version beat whatever the model remembers.
Start with a small component, describe the interaction rather than the markup, and check the result with the testing kit below. If the rest of the app was also built quickly with AI tools, my production checklist for vibe-coded apps covers what to fix before launch.
How to test accessibility with the UI SDK testing kit
@ui-sdk/core/testing checks a rendered widget against its WAI-ARIA pattern, and tests primitives directly:
import { checkPattern } from "@ui-sdk/core/testing"
await checkPattern(root, "dialog")
The kit has three main tools:
checkPatternchecks roles, names, states, references between parts and keyboard interactions, and throws one error listing every problem. The 15 supported patterns are listbox, menu, menubar, tabs, radio group, toolbar, tree, dialog, alert dialog, disclosure, accordion, combobox, slider, switch and checkbox. In places it is deliberately stricter than the WAI-ARIA Authoring Practices, requiring Home and End in listboxes, tabs and toolbars, andaria-modal="true"on modal dialogs.mounttests a primitive with simulated clicks, keys, typing, hovering and dragging, and records each change with its reason and input source.checkServerrenders a primitive without a DOM. It fails if the primitive reads browser globals, the clock or randomness, which are the usual causes of hydration mismatches.
Interaction tests need jsdom or a real browser. Server checks don't.
UI SDK vs shadcn/ui, Radix, Base UI, React Aria and Nuxt UI
UI SDK is closest to Radix, Base UI and React Aria, which also offer unstyled, accessible building blocks. Of the libraries below, it is the only one that serves five frameworks from one core, and the only one with a runtime bridge for agents. It credits several of them, plus Geist and the WAI-ARIA Authoring Practices, as inspiration.
| Library | Styling | Frameworks | Runtime agent bridge | Maturity (Nov 2026) |
|---|---|---|---|---|
| UI SDK | Unstyled, optional default theme | React, Vue and Nuxt, Svelte, Solid, Web Components | Yes | Beta, 0.1 |
| shadcn/ui | Tailwind, code copied into your project | React | No | Widely used, CLI 4.x |
| Radix Primitives | Unstyled | React | No | Stable for years |
| Base UI | Unstyled | React | No | Stable, 1.x |
| React Aria | Unstyled hooks and components | React | No | Stable, 1.x |
| Nuxt UI | Tailwind, built on Reka UI | Vue, Nuxt | No | Stable, v4 |
How I'd choose:
- Already happy on shadcn/ui or Nuxt UI? Stay. Nothing here forces a migration, and a beta is a poor foundation for a design system you ship to customers.
- Starting a design system for both React and Vue teams? UI SDK is the first option where one primitive renders natively in each, so it's worth a prototype now.
- Building screens that agents will operate? The agent bridge is the reason to try it. Nothing else here offers it.
- Need a component nobody ships, such as a kanban board or a scrubbable timeline? Build that one from UI SDK's behaviors, even if you keep another library for the basics.
Is UI SDK ready for production?
Not yet as the foundation of a customer-facing design system. It's a public beta, its docs say APIs may still change, and it hasn't reached 1.0. It is ready for prototypes, internal tools and isolated components, if you take a few precautions:
- Pin exact versions (
0.1.0-beta.1, no caret), and upgrade on purpose after reading the changelog. - Wrap the parts in your own components, such as an
AppSelect, so an API change touches one file. - Style through
data-slotand state attributes, never generated IDs. - Run
checkPatternon every composite widget in CI. - Give your coding agent the installed version's docs through
AGENTS.mdandllms.txt, not its memory. - Before customers get the agent bridge, set
allow, mark costly actions withdata-agent-confirmand hide sensitive regions withdata-agent-hidden. - Watch the GitHub issues for the components you depend on, and report what breaks. That's the point of a beta.
Where I can help
I build Nuxt and React front ends, including design systems and AI features, working from Romania (CET) with teams in the EU, UK and US. If you're weighing UI SDK for a component library, a Nuxt app or an interface agents should operate, these pages cover how I work:
Tell me what you're building and get a quote. I'll reply within one working day.
FAQ
Is UI SDK made by Vercel?
Yes. It's a Vercel Labs project. The source is at github.com/vercel-labs/ui, the docs site links to Vercel, and the beta runs under Vercel's public beta terms. It's open source under the Apache-2.0 licence.
Is UI SDK the same as the Vercel AI SDK?
No. The AI SDK (the ai package, version 7) connects apps to language models for text, tools and streaming chat. UI SDK (the @ui-sdk/* packages, version 0.1 beta) builds accessible components and lets agents operate them. They work well together.
Is UI SDK free?
Yes. It's open source under Apache-2.0 and installs from npm, with no account or API key.
Does UI SDK work with Nuxt?
Yes. @ui-sdk/vue includes a Nuxt module. Add "@ui-sdk/vue" to modules, and every part is auto-imported and renders on the server. It needs Vue 3.5 or newer, and the module supports Nuxt 4 and 5.
Does UI SDK come with styles, and does it work with Tailwind?
Components are unstyled. The optional @ui-sdk/core/web.css gives them a neutral default look that follows light and dark mode and is themed with --ui-* variables. With Tailwind, style parts with attribute variants such as data-pressed:. If you want the defaults too, import web.css into layer(components).
Is UI SDK production-ready?
It's a public beta (0.1.0-beta.1 at the time of writing), and its APIs may change before 1.0. Use it now for prototypes, internal tools and new standalone components. If you ship it, pin exact versions and wrap its parts in your own components.
