Installation

Add components to an existing Next.js or Vite + React project. There is no init step and no config file.

Requirements

• Next.js (App Router) or Vite + React, with React 18 or later, or Vite + Vue 3.5 or later for the Vue pilot. The CLI checks these versions before installing
• Tailwind CSS v4, set up as in the official guide for Next.js or Vite
• TypeScript: components are .tsx files (or .vue files with <script setup lang="ts">)
• Node.js 20.9 or later, and npm, pnpm, Yarn (with nodeLinker: node-modules), or Bun

Your first component

Run the command from your app directory. It prints the plan, then writes the files.

Files go to src/components/seamless, or components/seamless when the project has no src directory. With the @/* path alias that Next.js sets up, import them like this:

import { Button } from "@/components/seamless/ui/button";

Tailwind v4 scans your project automatically, so the component classes work without changing your CSS. Vite projects without the @/* alias import with a relative path; the CLI prints the right import after installing.

Install from a local build

@seamlessui/cli is not published to npm yet, so the npx @seamlessui/cli commands on this site will not work until the release. Until then, build the CLI from the repository and point it at the live registry:

# In the Seamless UI repository
corepack enable
pnpm install
pnpm --filter @seamlessui/registry build
pnpm --filter @seamlessui/cli build
pnpm --filter @seamlessui/cli pack    # writes packages/cli/seamlessui-cli-0.1.0.tgz

# In your app
npx --package /path/to/seamlessui/packages/cli/seamlessui-cli-0.1.0.tgz \
  seamless add tool-call-card --registry https://seamlessui-site.vercel.app/r

Vue pilot

Button, Dialog, Tool Call Card, and Agent Workspace (with Badge and the agent-run event contract they use) have native Vue 3 implementations. Run the same commands in a Vite + Vue project; the CLI detects Vue and installs .vue files into src/components/seamless:

npx @seamlessui/cli add tool-call-card

<script setup lang="ts">
import ToolCallCard from "@/components/seamless/agent/ToolCallCard.vue";
</script>

Components without a Vue implementation are refused with a message that names the Vue items available. Every Vue item is installed and built in a clean Vite + Vue app by CI.

Package managers

When a component needs npm packages (for example Base UI or Motion), the CLI installs them with your project's package manager before writing any file. It reads the packageManager field and lockfiles (package-lock.json, pnpm-lock.yaml, yarn.lock, bun.lock) and stops if they disagree. npm, pnpm, Yarn 4, and Bun are each verified by CI installing a component with a dependency and building the app. Yarn 4 refuses lockfile changes when it detects a CI environment, so add components locally and commit the result.

Monorepos

Run the command inside the app that should receive the components, or pass --cwd apps/web. Run from a workspace root, and the CLI lists the apps it found instead of guessing.

Troubleshooting

Unsupported project

The CLI looks for next, or vite plus react, in package.json. Run it in the app directory or pass --cwd.

Tailwind CSS v4 is required

Install tailwindcss 4 with @tailwindcss/postcss (Next.js) or @tailwindcss/vite (Vite), and add @import "tailwindcss" to your CSS.

A file has local changes

The CLI never overwrites your edits. It stops before writing anything. Keep your version, or move it aside and run the command again.

Conflicting package manager signals

Both an npm and a pnpm lockfile were found, or the packageManager field disagrees with the lockfile. Remove the stale one.

See the CLI reference for every option.