컴포넌트보다 작은 단위에서 시작하는 Vercel UI SDK

TMT

https://ui-sdk.dev/docs/core/changelog/introducing-ui-sdk

버튼을 누르면 배포 환경 목록이 펼쳐지고, 그중 하나를 고를 수 있는 화면을 만든다고 해보자. 방향키로 항목을 오갈 수 있어야 하고, 이름의 첫 글자를 입력하면 해당 항목으로 이동해야 한다. Esc를 눌러 목록을 닫으면 포커스는 원래 버튼으로 돌아와야 한다. 팝업을 닫고 포커스를 돌려놓는 동작은 날짜 선택기에서도 필요하다. 이름을 입력해 팀원을 찾는 화면에서도 목록 탐색과 항목 선택은 여전히 필요하다.

shadcn/ui를 쓰면 버튼이나 다이얼로그 같은 컴포넌트 코드를 프로젝트로 가져온다. Vercel UI SDK에서는 팝업을 열거나 목록에서 항목을 찾는 동작도 따로 가져와 조합할 수 있다. shadcn이 발표에서 선택 목록인 Select를 예로 든 이유다. 배포 환경 선택기에 쓰던 팝업 동작을 날짜 선택기에도 쓸 수 있고, 이런 조합을 코딩 에이전트에게 맡길 수도 있다. shadcn/ui 소개 · shadcn의 발표

Vercel Labs는 2026년 11월 12일자 공식 발표문에서 UI SDK 공개 베타를 알렸다. 저장소에는 Apache 2.0 라이선스가 적용되어 있다. 공식 발표문 · GitHub 저장소

배포 환경 선택기를 구성하는 세 가지 동작

UI SDK가 말하는 behavior는 화면에서 일어나는 개별 동작이다. 배포 환경 선택기를 예로 들면 세 가지 동작을 조합할 수 있다. UI SDK 소개 · 동작 목록

  • 팝업 열기와 닫기는 createPopup이 맡는다. 버튼 옆에 목록을 띄우고, Esc를 누르거나 바깥을 클릭하면 닫는다.
  • 선택값 관리는 createSelection이 맡는다. 현재 어떤 항목을 골랐는지 기억한다.
  • 이름으로 항목 찾기는 createTypeahead가 맡는다. 예를 들어 pro를 입력하면 목록에서 Production으로 이동한다. 검색 결과를 서버에서 받아오는 기능은 앱에서 연결한다.
behaviors-light

여러 동작을 엮어 컴포넌트 하나를 정의할 때는 @ui-sdk/core의 definePrimitive를 쓴다. 여기에 선택값이나 열림 여부 같은 상태, 팝업을 여는 버튼과 목록 같은 구성 요소, 각 부분에서 실행할 동작을 묶는다. 이렇게 정의한 프리미티브는 React, Vue, Svelte, Solid, Web Components용 어댑터가 화면에 연결한다. 가령 React에서 만든 선택기의 동작을 Vue에서도 쓰려면 프리미티브를 재사용하고, 화면을 구성하는 코드는 Vue에 맞춰 작성하면 된다. Core 소개 · React에서 프리미티브 렌더링하기

직접 조합할 필요가 없는 화면이라면 기본으로 제공하는 컴포넌트를 가져다 쓸 수 있다. 공개 당시 기준으로 재사용할 수 있는 동작과 조립된 컴포넌트를 각각 50개 넘게 제공한다. 컴포넌트에는 키보드 조작, 포커스 관리, ARIA 속성이 들어 있다. 시각적 스타일은 일반 CSS나 Tailwind로 입힐 수 있고, 기본 스타일이 필요하면 공식 문서에서 안내하는 @ui-sdk/core/web.css를 불러오면 된다. 공식 발표문 · React 설치 문서

React에서 배포 환경 선택기 만들기

설치하려면 React와 React DOM이 모두 19 이상이어야 한다. TypeScript 프로젝트에서는 @types/react도 19.2.10 이상이 필요하다. React 설치 문서

npm install @ui-sdk/react @ui-sdk/core

@ui-sdk/react/select에서 필요한 구성 요소를 가져와 배포 환경 선택기를 만든다.

"use client"

import {
  Select,
  SelectContent,
  SelectItem,
  SelectLabel,
  SelectTrigger,
  SelectValue,
} from "@ui-sdk/react/select"

const environments = [
  { value: "preview", label: "프리뷰" },
  { value: "production", label: "프로덕션" },
]

export function EnvironmentPicker() {
  return (
    <Select items={environments} defaultValue="preview">
      <SelectLabel>배포 환경</SelectLabel>
      <SelectTrigger>
        <SelectValue />
      </SelectTrigger>
      <SelectContent>
        {environments.map(({ value, label }) => (
          <SelectItem key={value} value={value}>
            {label}
          </SelectItem>
        ))}
      </SelectContent>
    </Select>
  )
}

SelectLabel은 선택기에 ‘배포 환경’이라는 이름을 붙인다. items에 옵션 데이터를 넘겨 두면, 목록을 열기 전에도 SelectValue가 preview에 해당하는 ‘프리뷰’를 버튼에 표시한다. Select 문서

에이전트는 이 선택기를 어떻게 만들고 조작할까

코딩 에이전트에게 컴포넌트 맡기기

“배포 환경 선택기에 최근 사용한 환경을 따로 모아서 보여주고 키보드로도 고를 수 있게 해줘”라고 요청한다고 해보자. 코딩 에이전트는 문서를 참고해 기존 Select를 확장할지, 필요한 동작을 직접 조합할지 판단할 수 있다. 에이전트와 컴포넌트 만들기

  1. npx skills@latest add vercel-labs/ui --skill ui-sdk로 코딩 에이전트에 스킬을 추가한다.
  2. React 프로젝트라면 node_modules/@ui-sdk/react/docs/llms.txt를 읽게 한다. 설치된 버전에 맞는 문서가 여기에 있다.
  3. 완성한 컴포넌트는 @ui-sdk/core/testing으로 키보드 이동과 포커스 동작을 확인할 수 있다. 테스트 문서

실행 중인 화면을 에이전트가 조작하게 하기

완성된 선택기를 에이전트가 조작하게 하려면 앱에 브리지를 연결한다. 화면을 읽고 조작할 때는 다음 메서드를 쓴다. 에이전트 연결 문서 · 브리지 API

  • snapshot()은 렌더링된 컴포넌트의 이름과 현재 값, 호출할 수 있는 동작을 읽는다.
  • query()는 특정 컴포넌트의 선택지 같은 세부 정보를 조회한다.
  • act()는 setValue처럼 컴포넌트가 제공하는 동작을 호출한다.

선택기가 렌더링된 브라우저에서 다음 코드를 실행하면 ‘배포 환경’의 값이 production으로 바뀌고, 버튼에도 ‘프로덕션’이 표시된다.

import { createAgent } from "@ui-sdk/react/agent"

const agent = createAgent({
  allow: ({ component, label, action }) =>
    component === "select" && label === "배포 환경" && action === "setValue",
})

console.log(agent.snapshot())

await agent.act({
  steps: [{ ref: "배포 환경", action: "setValue", args: ["production"] }],
})

예제의 allow는 이 선택기에서 값을 바꾸는 요청만 허용한다. 앱의 에이전트에 브리지 메서드를 도구로 연결하거나, WebMCP를 지원하는 브라우저에서 registerTools()로 등록할 수 있다. 실제로 설정을 저장하거나 배포하는 기능을 연결한다면, 화면에서 값을 바꾸는 권한과 서버에서 변경을 실행하는 권한을 각각 확인해야 한다. 브리지 권한 문서 · WebMCP 연동 문서

브리지를 쓰면 얼마나 달라질까

UI SDK 팀은 에이전트에게 프로젝트 이름과 공개 범위 등을 바꿔 저장하는 작업을 맡겼다. 아래 수치는 React로 만든 두 화면에서 각각 세 번 실행한 결과의 중앙값이다. 공식 벤치마크

화면과 조작 방식도구 호출작업 시간
Base UI + 브라우저 도구17회53초
UI SDK + 에이전트 브리지7회31초

UI SDK 팀에 따르면 같은 UI SDK 화면을 브라우저 도구로 조작했을 때는 다른 라이브러리와 비슷한 시간이 걸렸다. 팀은 관찰된 차이를 도구의 차이로 해석했다. 브리지에서는 에이전트가 컴포넌트의 동작을 직접 호출할 수 있다. 공식 벤치마크

shadcn/ui, AI SDK UI와는 어떤 관계일까

세 도구는 채팅 화면 하나에서도 서로 다른 역할을 맡을 수 있다.

도구제공하는 것같은 화면에서 쓰는 예
Vercel UI SDK재사용 가능한 UI 동작과 기본 스타일이 없는 컴포넌트프로젝트 선택기의 팝업, 키보드 탐색, 포커스 관리
shadcn/ui프로젝트에 복사해 수정할 수 있는 컴포넌트 코드와 스타일채팅 입력 폼과 버튼의 디자인
Vercel AI SDK UI채팅 스트림과 메시지 상태를 관리하는 훅@ai-sdk/react의 useChat으로 응답을 실시간 표시

공식 문서에서 각 도구가 제공하는 기능을 확인할 수 있다. UI SDK React 소개 · shadcn/ui 소개 · AI SDK UI 소개

베타에서 어디부터 써 볼까

2026년 11월 18일 기준, @ui-sdk/core와 @ui-sdk/react는 npm에서 동일한 태그를 사용했다. 위 설치 명령처럼 버전이나 태그를 생략하면 latest가 가리키는 버전을 받는다. Core npm 레지스트리 · React npm 레지스트리

npm 태그두 패키지의 버전
latest (기본 설치)0.1.0-beta.6
beta0.1.0-beta.8

위 예제는 beta.6을 설치한 jsdom 환경에서 렌더링하고, 브리지로 값을 바꿨을 때 버튼에 표시되는 값이 갱신되는 것까지 확인했다. 베타 기간에는 API와 동작이 바뀔 수 있다. 실제로 beta.8은 Select가 들어간 폼에서 Enter로 제출할 때의 동작을 수정했다. beta.8 릴리스 노트 · 베타 안내

첫 실험 대상으로는 기존 디자인 시스템에서 유독 손이 많이 갔던 선택기 하나가 적당하다. 배포 환경 선택기에서 시작해 담당자를 고르는 검색창까지 만들어 보면, 두 화면이 실제로 공유할 수 있는 동작이 드러난다. 여기에 에이전트를 연결한다면, 사용자가 키보드로 고른 값과 에이전트가 setValue로 고른 값이 앱에서 같은 변경 처리로 이어지는지 확인해 볼 수 있다.

Edit this page

Search the archive

Find a page by title, or search the text inside one.