Guide
Install
One command installs the complete set and its skin as source you own. The CSS entry is the only wiring you write.
Your agent can run all four steps from one prompt.
Install the set and its skin
One command copies every component, block, and primitive into your repository as source you own, together with the Refined skin that owns every token value they paint with.
npx shadcn@latest add https://control-ui.dev/r/all-refined.jsonWhat you should see now
A components/control-ui/ directory holding the source, styles/skin-theme.css and styles/skin.css holding the
pack, and a components.json the registry keeps writing to.
Every skin page exposes the same all-<skin> manifest, so the pack you start on is the one you name here.
Install one item at a time
A lean install picks the items instead. The skin stays required either way: it owns every token value the components paint with, and one pack always installs first.
npx shadcn@latest add https://control-ui.dev/r/skin-refined.json --overwritenpx shadcn@latest add https://control-ui.dev/r/chat-message.jsonBlocks install the same way and land as a complete composition — the chat block brings messages, input, attachments, markdown, composer controls, and actions.
npx shadcn@latest add https://control-ui.dev/r/chat-block.jsonNaming items instead of the set means the update and doctor scripts have to name them too.
Wire the CSS
Each item appends its own imports to the CSS entry named in components.json. Core plus a skin leaves you with:
/* app/globals.css */@import "tailwindcss";@import "../components/control-ui/styles/theme.css";@import "../components/control-ui/styles/skin-theme.css";@import "../components/control-ui/styles/skin.css";Then stamp the pack id on the root element:
<html data-skin="refined">…</html>What you should see now
A control paints with the skin's own radius and color, and one portalled surface — a popover, dialog, menu, or tooltip — opens carrying the same tokens. Both, or the wiring is not done.
Nothing paints? The registry always writes ../components/…, which resolves only when the entry sits one directory
above the components alias. Run node <install dir>/scripts/fix-css-imports.mjs to fold every appended line onto
this app's real paths, then verify with the doctor.
The contract
Exactly one pack owns skin.config.tsx, skin-theme.css, and skin.css. --overwrite claims all three — without
it the CLI keeps the previous pack's files in place.
The current skin contract is version 8: registered component CSS knobs carry every visual decision, sizing included, published one
slice per paint family under /r/contract/, indexed by /r/contract/index.json.
There is no token fallback when data-skin is missing or misspelled. It is the scope every token is declared under,
not a multi-skin switch, so one skin still needs it: without it every portalled surface renders with no tokens at all.
Compiled styles assume Safari 16.4+, Chrome 119+, Firefox 128+; the architecture guide's cascade section derives the floor.
Or install the package
The same set ships as @ctrl-ui/react with the Refined skin baked in, for apps that would rather pin a version
than own the source. Import paths mirror the registry tree: replace @/components/control-ui/ with
@ctrl-ui/react/ in any example on this site.
bun add @ctrl-ui/react/* app/globals.css */@import "tailwindcss";@import "@ctrl-ui/react/styles/index.css";@source "../node_modules/@ctrl-ui/react/dist";Stamp data-skin="refined" on the root element as above. Other skins, the update script, and the doctor stay
registry-only.
No results found.
Guides
Create app
Scaffold a Next.js app with every Control UI component installed as source you own, or hand the whole install to the coding agent already open in your project.
Install
One command installs the complete set and its skin as source you own. The CSS entry is the only wiring you write.
Verify
The doctor audits what the registry cannot see from inside one install: imports that resolve, theme order, app blocks fighting the skin, and the data-skin stamp.
Build a screen
Render provider-owned messages with plain props and children. No intermediary message schema, no runtime coupling.
Theme it
Pick the pack, re-value the token contract in one artifact, and check the contrast the components actually paint.
Create a skin
Re-value the token contract over an installed pack, or own a full pack of three files, then reach the component knobs beneath.
Theme AI builder
Create a Control UI theme with Claude Code, Codex, or Mastra Code, then import and test it live.
Theme accessibility
Audit canonical theme colors plus rendered popup, badge, and active-tab states, then run the same checks from the CLI.
Update & diff
Updating is a reinstall: the update manifest refreshes every installed source and never touches the three skin-owned files.
Contract versions
The skin contract is version 8. Crossing a version reinstalls core, the affected items, and the skin together.
Setup prompt
One prompt that makes the agent already open in your project read the repository, install from the registry, wire the CSS, run the doctor, and design the theme with you.
Agent skill
The skill installed with every pack: the token contract and the working rules, refreshed by every update, so later sessions build without the prompt.
Machine docs
Inspect and install registry items through HTTP, shadcn manifests, static metadata, and machine-readable docs.
Why Control UI
An owned-source registry of primitives, agent surfaces, complete blocks, and swappable skins.
Architecture
Runtime ownership, skin layering, customization paths, and registry derivation.
Lock-in
What you own at each layer, what stays proprietary, and what leaving costs — measured, not promised.
shadcn compatibility
shadcn registry, token, and ownership conventions without writing to components/ui.
Control UI vs shadcn/ui
Both ship open-source React source through the shadcn CLI. The difference starts after install: a typed knob contract, skins that re-value it wholesale, and 16 skin modes audited against WCAG AA on every commit.
Best React component libraries for AI interfaces
Eight production options compared by ownership model, theming system, and agent-specific surfaces — from shadcn/ui and AI Elements to MUI to Control UI.
Reference
Theme guides, the maintenance workflow, and the reasoning behind Control UI — everything beyond the install path.
Skins
Skinning Control UI
Author complete token-driven Control UI skins with slots, adornments, motion controls, and one shared component source.
Refined
Compact, calm starting skin with a complete Control UI token contract.
Windows XP
Windows XP-inspired Luna tokens, bevels, and titlebar details.
Liquid metal
Polished metal skin with a WebGL shader control surface.
Rig
Brutalist skin with coral accents, squared corners, and dense typography.
Flat
Neutral reset skin with square corners, no shadows, and the stock motion tempo.
Modern Apple
Apple-inspired Liquid Glass skin: WebGL-refraction on floating surfaces, precise directional rims, transparent inputs, and continuous corners.
Cuicui
Cuicui-inspired shell skin with fixed grain, a docked w-80 sidebar, a neutral main container, and the send-aurora anchored extension on ChatComposer (skin.config fills the chat-composer:send-layer anchor).
Linear
Linear-inspired skin: indigo brand on a cool neutral ramp, a flat 13px chrome band, 8px controls on 12px panels, hairline borders instead of elevation, and 8px menu rows inset in a 4px gutter.
Practices
CSS-first interactivity
Model UI reactions with relational selectors, container/style queries, and native platform elements before adding React state, effects, or event handlers.
CSS-first motion & sizing
Drive sizing, enter/exit motion, and scroll effects from CSS and native attributes — token-driven and progressively enhanced — instead of measuring and animating values in JavaScript.
Derive, do not duplicate
Avoid second sources of truth in component props, hook parameters, and local state.
Remount state boundaries
Reset state by changing component identity or loading boundaries, not by syncing with effects.
Explicit names instead of comments
Encode intent in identifiers and extracted units so the code needs no explanatory comments, and keep the rare justified one telegraphic.
One responsibility per file
Split domain components and hooks before fetching, filtering, selection, and form state become entangled.
Keep input and output APIs narrow
Split oversized prop, argument, and return-value APIs into cohesive responsibilities.
Keep context necessary, narrow, and stable
Use context only across real composition boundaries, with the smallest stable semantic value consumers need.
Do not query the DOM in React
Keep element identity and collections in React instead of searching rendered markup.
Real stack tests
Prefer tests that drive production hooks, clients, routing, and cache behavior with only the network mocked.
Test rendered output, not class names
Prove visual behavior through computed styles, geometry, or browser output instead of Tailwind class strings.
Cohesive folders
Keep every folder a short, readable table of contents by grouping loose files into named responsibilities.
Single source of truth
Prevent shared facts from drifting by assigning each one a canonical owner.
Use existing components first
Start from the local design system or registry primitive before creating a new styled element.
Token discipline
Use established design tokens and local CSS variables before reaching for one-off values.
ClassName boundaries
Use component APIs for intended variation instead of overriding design-system internals with className.
Tailwind v4 CSS configuration
Configure Tailwind through CSS directives and tokens instead of adding new JavaScript config.
Tailwind v4 migration syntax
Use v4 names and modifiers when replacing or reviewing v3-era Tailwind classes.
First-class utilities before custom CSS
Prefer Tailwind v4's first-class utility families before arbitrary properties or handwritten CSS.
Variant-first styling
Check Tailwind variants before adding handwritten selectors, style props, or React state for styling.
Tailwind v4 capabilities
Reach for new v4 utilities before layout hacks, user-agent checks, or JavaScript measurement.
Tailwind v4 behavior & motion
Account for v4 behavior changes around transforms, hover, default colors, variant order, spacing, and motion.
State continuity
Show loading, empty, partial, success, and failure states in the same product language.
Provenance without noise
Surface source, runtime, and ownership cues only where they help the user trust or act.
Dense but scannable
Favor compact surfaces that support repeated work without flattening hierarchy.
Say it once
Cut redundant AI-slop copy so labels, controls, and state carry the obvious meaning.
Skin authoring
Author a skin as three files with strict roles — theme.css owns shared tokens, skin.css re-values registered component knobs, and skin.config declares behavior and adornments.
Extension authoring
Author an extension as an optional installable layered on the library — root-mounted for cross-cutting anatomy-attached behavior, anchored for component-scoped fx activated from skin.config.
Registry-first DX
Keep the registry manifest and installed source as the contract users can inspect.
Skin completeness
Treat a skin as a complete source recipe, not a partial class override layer.
Control UI composition
Keep blocks readable by composing public agent components, hooks, and slots explicitly.
Runtime-agnostic UI
Keep core visual surfaces independent from model runners, stores, and transport lifecycles.
Compound components DX
Expose named anatomy parts when users need to customize layout or actions.
Context vs props
Reach for a compound-component context only when props cannot reach the part, and store intent in it, not styling.
Components
AI components
Explore composable surfaces for messages, input, activity, media, and agent workflows.
Email
React Email compositions with Control UI colors and typography, image layouts, columns, and HTML or plain-text export.
ChatMessage
Composable chat message with typed role, density, and lifecycle state.
ChatComposer
Prompt composer with controlled text, submit state, and trigger-menu support.
ChatComposerAttachment
Composer attachment rail with file previews, upload progress, and removal.
UserAsk
Keyboard-first agent question panel that temporarily replaces the chat composer inside its container.
TaskList
Floating agent task progress pill above the composer that expands into the full task list.
AudioRecorder
Voice recorder with realtime waveform, duration, cancel, and submit controls.
AudioVisualizer
Levels-driven realtime audio visualizer offered in two usage versions - bars and line - sharing one export and one props contract.
DynamicNotification
Dynamic Island-style AI notification pill with a thinking state that morphs into a reply bubble — token-driven surface, WebGL-enhanced backdrop blur, or real refractive liquid glass.
EnvironmentVariables
Composable environment variable editor with .env upload, bulk paste, reveal controls, and submit helpers.
Activity
Shared static and collapsible activity anatomy with bounded, scrollable detail content.
TranscriptDivider
Toned run-boundary separator for transcripts: steering, interruptions, and condensed context.
Context
Compact context-window usage with an automatically derived token graph and anchored detail inspector.
InlineCitation
Inline multi-source citation with a keyboard-accessible preview and source navigation.
SourceBadge
Linked source badge with an automatic same-origin favicon, derived hostname, and resilient fallback.
ActionBar
Reusable hover actions for message and response controls.
InlineAttachment
Inline file and media previews for chat turns.
MarkdownBlock
Assistant markdown output rendered to prose, with a header and copy-source action.
CodeBlockEditor
Editable code surface with Shiki highlighting and token-based light/dark themes.
ChatLayout
Layout primitives for full chat threads, turns, and thoughts.
ThreadRail
Conversation minimap for scanning and jumping between chat turns.
Primitives
Primitives
Browse every Control UI primitive through the same live examples used in its documentation.
Button
Accessible action button with size, variant, and semantic tone support.
Collapsible
Accessible disclosure primitive with measured open and close motion.
Tabs
Segmented and browser-style navigation with a stable active indicator.
Track highlight
Shared fluid hover, keyboard-focus, and selection highlight for custom lists and groups, with CSS anchors and a measured fallback.
Sidebar
Responsive app sidebar with animated mobile navigation, collapsible groups, nested menus, and icon collapse.
Scroll area
Scroll container with overlay scrollbars, edge fades, and optional progressive blur.
Progressive blur
CSS-driven backdrop blur that grows toward an edge, with masked layers and interruptible staggered transitions.
Table of contents
Sticky in-page navigation with scroll-spy range highlighting.
Timeline
Static chronological events with independent status, connectors, descriptions, and metadata.
Stepper
Static and interactive workflow steps with horizontal and vertical layouts.
Skeleton
Loading placeholder with a token-driven shimmer.
Slider
Single-value range control with branded and plain treatments.
Select
Single-choice picker with a token-matched trigger and floating list.
DropdownMenu
Dropdown menu for actions, resources, labels, separators, and submenus.
Context Menu
Pointer-positioned right-click and long-press menu with nested actions and selection controls.
Toggle
Pressed-state button and toggle group built on the Button surface.
Switch
On/off control with token-driven track, thumb, and press motion.
Dialog
Modal dialog for focused tasks, confirmations, and custom panels.
Popover
Anchored floating panel for inline settings and contextual content.
Tooltip
Hover or focus hint popup with Base UI positioning and Control UI tokens.
Rich tooltip
Persistent anchored tip for onboarding tours, walkthroughs, and new-feature announcements — dismissible, with optional media and step counter.
Drawer
Swipeable edge panel for mobile sheets and off-canvas surfaces.
Responsive dialog
Modal dialog on desktop that becomes a swipeable bottom drawer on mobile.
Toast
Transient notifications with a callable toast API and single Toaster mount.
Input
Text field primitive sized and styled to match other controls.
Input group
Joined input wrapper for addons, icons, and focus-within rings.
Dropzone
Composable file intake with validation, managed selection, and drag-activated overlays.
Phone input
International phone field with country search, E.164 values, and Zod validation helpers.
Command
Command palette with token-matched dialog, input, and result rows.
Kbd
Keyboard shortcut chip and chord group.
Checkbox
Single checkbox control with checked and indeterminate states.
Radio group
Single-choice radio set for plans, filters, and option lists.
Accordion
Stacked disclosure rows with measured panel animation.
Avatar
Profile image with initials fallback and composable overlapping groups.
Progress
Determinate task progress with optional label and value rows.
Hover card
Hover or focus preview panel for profiles, links, and contextual details.
Alert dialog
Modal confirmation dialog for destructive or blocking decisions.
Menubar
Desktop command bar with nested menus, shortcuts, and separators.
Navigation menu
Site navigation menu with a shared animated viewport.
Field
Form field wrapper for labels, descriptions, errors, and validity state.
Form
Form wrapper that coordinates field validation and returned errors.
Native select
Native select control styled to match the Control UI control family.
Textarea
Multiline text field with CSS-first auto-growth.
Input OTP
One-time-code field with grouped, focus-aware slots.
Combobox
Searchable single-select with input and floating option list.
Alert
Inline status panel for callouts, errors, and notices.
Badge
Compact status, label, or count chip.
Card
Content surface for panels, tiles, and settings groups.
Table
Responsive data table for lists, comparisons, and structured records.
Aspect ratio
CSS aspect-ratio wrapper for media and previews.
Button group
Joined button group for toolbars, split actions, and segmented controls.
Empty
Empty-state layout for blank lists, zero results, and new workspaces.
Item
List row with media, content, and trailing actions.
Pagination
Page navigation for long lists and result sets.
Spinner
Accessible loading indicator for pending buttons, panels, and inline waits.
Meter
Static range meter for quota, storage, score, or usage values.
Tree
Accessible tree view with roving keyboard navigation, single/multi selection, and animated disclosure.
Checkbox Group
Multi-select checkbox set with shared state and select-all support.
Autocomplete
Free-text input with search-as-you-type suggestions.
Number Field
Numeric input with stepper buttons and optional drag-to-change behavior.
Trigger Menu
Caret-anchored command or mention menu for text editors.
Toolbar
Roving-focus toolbar for editor controls and compact actions.
Dockable Panel
Non-modal workspace panel that moves between two explicit edge slots with a mobile Drawer fallback.
Infinite Canvas
Pan-and-zoom spatial workspace for arranging content without fixed bounds.
Morphing Panel
Accessible disclosure surface that morphs between explicit collapsed and expanded dimensions.
Color Picker
Color input with picker UI, formats, presets, and contrast helpers.
Gradient Editor
CSS gradient editor with draggable stops and live preview.
Resizable
Accessible resizable panel groups and split layouts with keyboard support.
Calendar
Date selection grid built on react-day-picker and themed through tokens.
Typography
The token-driven type scale — one --text-* rung per size, named by role. Publish the utilities, not a component.
Code
Shared code surface: Shiki-highlighted lines, gutter, clean copy, and virtualization for large files.
Code Diff
Unified or split diff from a git patch or a before/after pair, with word-level intra-line highlighting.
Markdown
Rendered agent markdown (GFM) whose code fences compose Code, and diff fences compose CodeDiff.
Support files
useChatMessage
Typed role, density, and lifecycle state for ChatMessage.
useChatComposer
Controlled composer text and submit state.
useUserAsk
Question/option registration, selection, freeform text, and keyboard flow for UserAsk.
useAudioRecorder
Browser microphone recording state, waveform levels, and Blob completion.
useEnvironmentVariables
Editable environment variable rows with .env parsing, upload, duplicate detection, and submit helpers.
useCopyToClipboard
Copy-to-clipboard behavior with success state and fallback support.
cn
Tailwind class-name merge helper.
skin
Skin slot and adornment resolvers for the Control UI library.
serialize
Bridge a rich editor doc to plain text (and structured mentions) and back — independent of any one component.
Blocks
Blocks
Start from complete workspace templates or focused interaction patterns, then own and adapt the installed source.
Chat
Controlled chat shell that composes rendered turns and a provider-owned composer.
Theme toggle
Controlled theme controls with a three-value switch, binary switch, cycle button, and dropdown.
Coding agent
Desktop coding workspace with project tasks, a focused conversation, and a persistent controlled composer.
Settings
Searchable multi-page settings shell with responsive navigation and accessible control groups.
File explorer
Finder-inspired file browser with locations, search, resizable columns, breadcrumbs, and an item preview.