# Control UI

> Production-ready, shadcn-compatible React components, blocks, and skins for agent interfaces, distributed as editable source.

Control UI installs editable React source through the shadcn CLI. The catalog below is generated from the same page manifest used by the website, sitemap, search, and registry API.

## Documentation

- [Overview](https://control-ui.dev/overview): An owned-source registry of primitives, agent surfaces, complete blocks, and swappable skins.
- [Get started](https://control-ui.dev/get-started): Choose a skin, install a component or complete block, wire its CSS, and compose your application runtime.
- [shadcn compatibility](https://control-ui.dev/shadcn-compatibility): shadcn registry, token, and ownership conventions without writing to components/ui.
- [Architecture](https://control-ui.dev/architecture): Runtime ownership, skin layering, customization paths, and registry derivation.
- [Agent surface](https://control-ui.dev/agent-surface): Inspect and install registry items through HTTP, shadcn manifests, static metadata, and machine-readable docs.
- [Theme accessibility](https://control-ui.dev/theme-accessibility): Audit canonical theme colors plus rendered popup, badge, and active-tab states, then run the same checks from the CLI.
- [Theme AI builder](https://control-ui.dev/theme-ai-builder): Create a Control UI theme with Claude Code, Codex, or Mastra Code, then import and test it live.

## AI components

- [AI components](https://control-ui.dev/ai): Explore composable surfaces for messages, input, activity, media, and agent workflows.
- [ChatMessage](https://control-ui.dev/ai/chat-message): Composable chat message with typed role, density, and tone state.
- [ChatComposer](https://control-ui.dev/ai/chat-composer): Prompt composer with controlled text, submit state, and trigger-menu support.
- [ChatComposerAttachment](https://control-ui.dev/ai/chat-composer-attachment): Composer attachment rail with file previews, upload progress, and removal.
- [UserAsk](https://control-ui.dev/ai/user-ask): Keyboard-first agent question panel that temporarily replaces the chat composer inside its container.
- [TaskList](https://control-ui.dev/ai/task-list): Floating agent task progress pill above the composer that expands into the full task list.
- [AudioRecorder](https://control-ui.dev/ai/audio-recorder): Voice recorder with realtime waveform, duration, cancel, and submit controls.
- [AudioVisualizer](https://control-ui.dev/ai/audio-visualizer): Levels-driven realtime audio visualizer offered in two usage versions - bars and line - sharing one export and one props contract. Status: beta.
- [DynamicNotification](https://control-ui.dev/ai/dynamic-notification): 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. Status: experimental.
- [EnvironmentVariables](https://control-ui.dev/ai/environment-variables): Composable environment variable editor with .env upload, bulk paste, reveal controls, and submit helpers. Status: experimental.
- [Activity](https://control-ui.dev/ai/activity): Shared static and collapsible activity anatomy with bounded, scrollable detail content.
- [Context](https://control-ui.dev/ai/context): Compact context-window usage with an automatically derived token graph and anchored detail inspector. Status: beta.
- [InlineCitation](https://control-ui.dev/ai/inline-citation): Inline multi-source citation with a keyboard-accessible preview and source navigation. Status: beta.
- [SourceBadge](https://control-ui.dev/ai/source-badge): Linked source badge with an automatic same-origin favicon, derived hostname, and resilient fallback.
- [ActionBar](https://control-ui.dev/ai/action-bar): Reusable hover actions for message and response controls.
- [InlineAttachment](https://control-ui.dev/ai/inline-attachment): Inline file and media previews for chat turns.
- [MarkdownBlock](https://control-ui.dev/ai/markdown-block): Assistant markdown output rendered to prose, with a header and copy-source action.
- [CodeBlockEditor](https://control-ui.dev/ai/code-block-editor): Editable code surface with Shiki highlighting and token-based light/dark themes.
- [ChatLayout](https://control-ui.dev/ai/chat-layout): Layout primitives for full chat threads, turns, and thoughts.
- [ThreadRail](https://control-ui.dev/ai/thread-rail): Conversation minimap for scanning and jumping between chat turns.

## Blocks

- [Use cases](https://control-ui.dev/use-cases): Start from complete workspace templates or focused interaction patterns, then own and adapt the installed source.
- [Chat](https://control-ui.dev/use-cases/chat): Controlled chat shell that composes rendered turns and a provider-owned composer.
- [Theme toggle](https://control-ui.dev/use-cases/theme-toggle): Controlled theme controls with a three-value switch, binary switch, cycle button, and dropdown.
- [Coding agent](https://control-ui.dev/use-cases/coding-agent): Desktop coding workspace with project tasks, a focused conversation, and a persistent controlled composer. Status: beta.
- [Settings](https://control-ui.dev/use-cases/settings): Searchable multi-page settings shell with responsive navigation and accessible control groups.
- [File explorer](https://control-ui.dev/use-cases/file-explorer): Finder-inspired file browser with locations, search, resizable columns, breadcrumbs, and an item preview. Status: beta.

## Primitives

- [Primitives](https://control-ui.dev/primitives): Browse every Control UI primitive through the same live examples used in its documentation.
- [Button](https://control-ui.dev/primitives/button): Accessible action button with size, variant, and semantic tone support.
- [Collapsible](https://control-ui.dev/primitives/collapsible): Accessible disclosure primitive with measured open and close motion.
- [Tabs](https://control-ui.dev/primitives/tabs): Segmented and browser-style navigation with a stable active indicator.
- [Sidebar](https://control-ui.dev/primitives/sidebar): Responsive app sidebar with collapse, mobile sheet, and keyboard toggle support. Status: beta.
- [Scroll area](https://control-ui.dev/primitives/scroll-area): Scroll container with overlay scrollbars and edge fades.
- [Table of contents](https://control-ui.dev/primitives/table-of-contents): Sticky in-page navigation with scroll-spy range highlighting.
- [Timeline](https://control-ui.dev/primitives/timeline): Static chronological events with independent status, connectors, descriptions, and metadata.
- [Stepper](https://control-ui.dev/primitives/stepper): Static and interactive workflow steps with horizontal and vertical layouts.
- [Skeleton](https://control-ui.dev/primitives/skeleton): Loading placeholder with a token-driven shimmer. Status: beta.
- [Slider](https://control-ui.dev/primitives/slider): Single-value range control with branded and plain treatments.
- [Select](https://control-ui.dev/primitives/select): Single-choice picker with a token-matched trigger and floating list.
- [DropdownMenu](https://control-ui.dev/primitives/dropdown-menu): Dropdown menu for actions, resources, labels, separators, and submenus.
- [Context Menu](https://control-ui.dev/primitives/context-menu): Pointer-positioned right-click and long-press menu with nested actions and selection controls.
- [Toggle](https://control-ui.dev/primitives/toggle): Pressed-state button and toggle group built on the Button surface.
- [Switch](https://control-ui.dev/primitives/switch): On/off control with token-driven track, thumb, and press motion.
- [Dialog](https://control-ui.dev/primitives/dialog): Modal dialog for focused tasks, confirmations, and custom panels.
- [Popover](https://control-ui.dev/primitives/popover): Anchored floating panel for inline settings and contextual content.
- [Tooltip](https://control-ui.dev/primitives/tooltip): Hover or focus hint popup with Base UI positioning and Control UI tokens.
- [Drawer](https://control-ui.dev/primitives/drawer): Swipeable edge panel for mobile sheets and off-canvas surfaces.
- [Responsive dialog](https://control-ui.dev/primitives/responsive-dialog): Modal dialog on desktop that becomes a swipeable bottom drawer on mobile.
- [Toast](https://control-ui.dev/primitives/toast): Transient notifications with a callable toast API and single Toaster mount.
- [Input](https://control-ui.dev/primitives/input): Text field primitive sized and styled to match other controls.
- [Input group](https://control-ui.dev/primitives/input-group): Joined input wrapper for addons, icons, and focus-within rings.
- [Dropzone](https://control-ui.dev/primitives/dropzone): Composable file intake with validation, managed selection, and drag-activated overlays. Status: beta.
- [Phone input](https://control-ui.dev/primitives/phone-input): International phone field with country search, E.164 values, and Zod validation helpers. Status: beta.
- [Command](https://control-ui.dev/primitives/command): Command palette with token-matched dialog, input, and result rows.
- [Kbd](https://control-ui.dev/primitives/kbd): Keyboard shortcut chip and chord group.
- [Checkbox](https://control-ui.dev/primitives/checkbox): Single checkbox control with checked and indeterminate states.
- [Radio group](https://control-ui.dev/primitives/radio-group): Single-choice radio set for plans, filters, and option lists.
- [Accordion](https://control-ui.dev/primitives/accordion): Stacked disclosure rows with measured panel animation.
- [Avatar](https://control-ui.dev/primitives/avatar): Profile image with initials fallback and composable overlapping groups.
- [Progress](https://control-ui.dev/primitives/progress): Determinate task progress with optional label and value rows.
- [Hover card](https://control-ui.dev/primitives/hover-card): Hover or focus preview panel for profiles, links, and contextual details.
- [Alert dialog](https://control-ui.dev/primitives/alert-dialog): Modal confirmation dialog for destructive or blocking decisions.
- [Menubar](https://control-ui.dev/primitives/menubar): Desktop command bar with nested menus, shortcuts, and separators.
- [Navigation menu](https://control-ui.dev/primitives/navigation-menu): Site navigation menu with a shared animated viewport.
- [Field](https://control-ui.dev/primitives/field): Form field wrapper for labels, descriptions, errors, and validity state.
- [Form](https://control-ui.dev/primitives/form): Form wrapper that coordinates field validation and returned errors.
- [Native select](https://control-ui.dev/primitives/native-select): Native select control styled to match the Control UI control family.
- [Textarea](https://control-ui.dev/primitives/textarea): Multiline text field with CSS-first auto-growth.
- [Input OTP](https://control-ui.dev/primitives/input-otp): One-time-code field with grouped, focus-aware slots.
- [Combobox](https://control-ui.dev/primitives/combobox): Searchable single-select with input and floating option list.
- [Alert](https://control-ui.dev/primitives/alert): Inline status panel for callouts, errors, and notices. Status: beta.
- [Badge](https://control-ui.dev/primitives/badge): Compact status, label, or count chip. Status: beta.
- [Card](https://control-ui.dev/primitives/card): Content surface for panels, tiles, and settings groups. Status: beta.
- [Table](https://control-ui.dev/primitives/table): Responsive data table for lists, comparisons, and structured records.
- [Aspect ratio](https://control-ui.dev/primitives/aspect-ratio): CSS aspect-ratio wrapper for media and previews. Status: beta.
- [Button group](https://control-ui.dev/primitives/button-group): Joined button group for toolbars, split actions, and segmented controls.
- [Empty](https://control-ui.dev/primitives/empty): Empty-state layout for blank lists, zero results, and new workspaces. Status: beta.
- [Item](https://control-ui.dev/primitives/item): List row with media, content, and trailing actions. Status: beta.
- [Pagination](https://control-ui.dev/primitives/pagination): Page navigation for long lists and result sets.
- [Spinner](https://control-ui.dev/primitives/spinner): Accessible loading indicator for pending buttons, panels, and inline waits.
- [Meter](https://control-ui.dev/primitives/meter): Static range meter for quota, storage, score, or usage values.
- [Tree](https://control-ui.dev/primitives/tree): Accessible tree view with roving keyboard navigation, single/multi selection, and animated disclosure.
- [Checkbox Group](https://control-ui.dev/primitives/checkbox-group): Multi-select checkbox set with shared state and select-all support. Status: beta.
- [Autocomplete](https://control-ui.dev/primitives/autocomplete): Free-text input with search-as-you-type suggestions.
- [Number Field](https://control-ui.dev/primitives/number-field): Numeric input with stepper buttons and optional drag-to-change behavior.
- [Trigger Menu](https://control-ui.dev/primitives/trigger-menu): Caret-anchored command or mention menu for text editors. Status: beta.
- [Toolbar](https://control-ui.dev/primitives/toolbar): Roving-focus toolbar for editor controls and compact actions.
- [Dockable Panel](https://control-ui.dev/primitives/dockable-panel): Non-modal workspace panel that moves between two explicit edge slots with a mobile Drawer fallback. Status: experimental.
- [Infinite Canvas](https://control-ui.dev/primitives/infinite-canvas): Pan-and-zoom spatial workspace for arranging content without fixed bounds. Status: experimental.
- [Morphing Panel](https://control-ui.dev/primitives/morphing-panel): Accessible disclosure surface that morphs between explicit collapsed and expanded dimensions. Status: experimental.
- [Color Picker](https://control-ui.dev/primitives/color-picker): Color input with picker UI, formats, presets, and contrast helpers. Status: beta.
- [Gradient Editor](https://control-ui.dev/primitives/gradient-editor): CSS gradient editor with draggable stops and live preview. Status: beta.
- [Resizable](https://control-ui.dev/primitives/resizable): Accessible resizable panel groups and split layouts with keyboard support. Status: beta.
- [Calendar](https://control-ui.dev/primitives/calendar): Date selection grid built on react-day-picker and themed through tokens. Status: beta.
- [Typography](https://control-ui.dev/primitives/typography): The token-driven type scale — one --text-* rung per size, named by role. Publish the utilities, not a component.
- [Code](https://control-ui.dev/primitives/code): Shared code surface: Shiki-highlighted lines, gutter, clean copy, and virtualization for large files.
- [Code Diff](https://control-ui.dev/primitives/code-diff): Unified or split diff from a git patch or a before/after pair, with word-level intra-line highlighting.
- [Markdown](https://control-ui.dev/primitives/markdown): Rendered agent markdown (GFM) whose code fences compose Code, and diff fences compose CodeDiff.

## Extensions

- [ControlEffects](https://control-ui.dev/extensions/control-effects): CSS-driven control effects (top-shine, ripple, hover-circle) that follow every control app-wide through the emitted anatomy — portalled surfaces included.
- [viewTransition](https://control-ui.dev/extensions/view-transition): Interrupt-safe driver for the browser View Transitions API: page transitions, shared-element morphs, and a reduced-motion fallback for both.
- [SendAurora](https://control-ui.dev/extensions/send-aurora): Anchored ChatComposer extension: a blurred aurora backdrop that sweeps up once per sent message — activated from skin.config via the chat-composer:send-layer anchor.

## Skins

- [Skinning Control UI](https://control-ui.dev/skins): Author complete token-driven Control UI skins with slots, adornments, motion controls, and one shared component source.
- [Refined](https://control-ui.dev/skins/refined): Compact, calm starting skin with a complete Control UI token contract.
- [Windows XP](https://control-ui.dev/skins/xp): Windows XP-inspired Luna tokens, bevels, and titlebar details.
- [Liquid metal](https://control-ui.dev/skins/liquid-metal): Polished metal skin with a WebGL shader control surface.
- [Rig](https://control-ui.dev/skins/rig): Brutalist skin with coral accents, squared corners, and dense typography.
- [Flat](https://control-ui.dev/skins/flat): Neutral reset skin with square corners, no shadows, and instant motion.
- [Modern Apple](https://control-ui.dev/skins/modern-apple): Apple-inspired Liquid Glass skin: WebGL-refraction on floating surfaces, precise directional rims, transparent inputs, and continuous corners.
- [Cuicui](https://control-ui.dev/skins/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](https://control-ui.dev/skins/linear): Linear-inspired skin: indigo brand on a cool neutral ramp, a flat 13px chrome band, 4px radius, hairline borders instead of elevation, and pill-shaped filled actions.

## Hooks

- [useChatMessage](https://control-ui.dev/hooks/use-chat-message): Typed role, density, and tone state for ChatMessage.
- [useChatComposer](https://control-ui.dev/hooks/use-chat-composer): Controlled composer text and submit state.
- [useUserAsk](https://control-ui.dev/hooks/use-user-ask): Question/option registration, selection, freeform text, and keyboard flow for UserAsk.
- [useAudioRecorder](https://control-ui.dev/hooks/use-audio-recorder): Browser microphone recording state, waveform levels, and Blob completion.
- [useEnvironmentVariables](https://control-ui.dev/hooks/use-environment-variables): Editable environment variable rows with .env parsing, upload, duplicate detection, and submit helpers.
- [useCopyToClipboard](https://control-ui.dev/hooks/use-copy-to-clipboard): Copy-to-clipboard behavior with success state and fallback support.

## Utilities

- [cn](https://control-ui.dev/utils/cn): Tailwind class-name merge helper.
- [skin](https://control-ui.dev/utils/skin): Skin slot and adornment resolvers for the Control UI library.
- [contracts](https://control-ui.dev/utils/contracts): Shared prop and slot contracts for swappable skins.
- [serialize](https://control-ui.dev/utils/serialize): Bridge a rich editor doc to plain text (and structured mentions) and back — independent of any one component.

## Practice guides

- [CSS-first interactivity](https://control-ui.dev/skills/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](https://control-ui.dev/skills/css-first-motion-and-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](https://control-ui.dev/skills/react-derive-dont-duplicate): Avoid second sources of truth in component props, hook parameters, and local state.
- [Remount state boundaries](https://control-ui.dev/skills/react-remount-state-boundaries): Reset state by changing component identity or loading boundaries, not by syncing with effects.
- [Explicit names instead of comments](https://control-ui.dev/skills/react-explicit-naming): 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](https://control-ui.dev/skills/react-single-responsibility): Split domain components and hooks before fetching, filtering, selection, and form state become entangled.
- [Keep input and output APIs narrow](https://control-ui.dev/skills/react-narrow-apis): Split oversized prop, argument, and return-value APIs into cohesive responsibilities.
- [Keep context necessary, narrow, and stable](https://control-ui.dev/skills/react-context-ownership): Use context only across real composition boundaries, with the smallest stable semantic value consumers need.
- [Do not query the DOM in React](https://control-ui.dev/skills/react-no-dom-queries): Keep element identity and collections in React instead of searching rendered markup.
- [Real stack tests](https://control-ui.dev/skills/react-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](https://control-ui.dev/skills/react-test-rendered-output): Prove visual behavior through computed styles, geometry, or browser output instead of Tailwind class strings.
- [Cohesive folders](https://control-ui.dev/skills/architecture-cohesive-folders): Keep every folder a short, readable table of contents by grouping loose files into named responsibilities.
- [Single source of truth](https://control-ui.dev/skills/architecture-single-source-of-truth): Prevent shared facts from drifting by assigning each one a canonical owner.
- [Use existing components first](https://control-ui.dev/skills/tailwind-use-existing-components): Start from the local design system or registry primitive before creating a new styled element.
- [Token discipline](https://control-ui.dev/skills/tailwind-token-discipline): Use established design tokens and local CSS variables before reaching for one-off values.
- [ClassName boundaries](https://control-ui.dev/skills/tailwind-classname-boundaries): Use component APIs for intended variation instead of overriding design-system internals with className.
- [Tailwind v4 CSS configuration](https://control-ui.dev/skills/tailwind-v4-css-configuration): Configure Tailwind through CSS directives and tokens instead of adding new JavaScript config.
- [Tailwind v4 migration syntax](https://control-ui.dev/skills/tailwind-v4-migration-syntax): Use v4 names and modifiers when replacing or reviewing v3-era Tailwind classes.
- [First-class utilities before custom CSS](https://control-ui.dev/skills/tailwind-generated-utilities): Prefer Tailwind v4's first-class utility families before arbitrary properties or handwritten CSS.
- [Variant-first styling](https://control-ui.dev/skills/tailwind-variant-first-styling): Check Tailwind variants before adding handwritten selectors, style props, or React state for styling.
- [Tailwind v4 capabilities](https://control-ui.dev/skills/tailwind-v4-capabilities): Reach for new v4 utilities before layout hacks, user-agent checks, or JavaScript measurement.
- [Tailwind v4 behavior & motion](https://control-ui.dev/skills/tailwind-v4-behavior-and-motion): Account for v4 behavior changes around transforms, hover, default colors, variant order, spacing, and motion.
- [State continuity](https://control-ui.dev/skills/ux-state-continuity): Show loading, empty, partial, success, and failure states in the same product language.
- [Provenance without noise](https://control-ui.dev/skills/ux-provenance-without-noise): Surface source, runtime, and ownership cues only where they help the user trust or act.
- [Dense but scannable](https://control-ui.dev/skills/ux-dense-but-scannable): Favor compact surfaces that support repeated work without flattening hierarchy.
- [Say it once](https://control-ui.dev/skills/ux-say-it-once): Cut redundant AI-slop copy so labels, controls, and state carry the obvious meaning.
- [Skin authoring](https://control-ui.dev/skills/skin-authoring): Author a skin as three files with strict roles — theme.css owns the complete token contract, skin.config restyles slots and declares DS choices, skin.css says only what classes cannot.
- [Extension authoring](https://control-ui.dev/skills/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](https://control-ui.dev/skills/registry-first-dx): Keep the registry manifest and installed source as the contract users can inspect.
- [Skin completeness](https://control-ui.dev/skills/skin-completeness): Treat a skin as a complete source recipe, not a partial class override layer.
- [Control UI composition](https://control-ui.dev/skills/control-ui-composition): Keep blocks readable by composing public agent components, hooks, and slots explicitly.
- [Runtime-agnostic UI](https://control-ui.dev/skills/runtime-agnostic-ui): Keep core visual surfaces independent from model runners, stores, and transport lifecycles.
- [Compound components DX](https://control-ui.dev/skills/compound-components-dx): Expose named anatomy parts when users need to customize layout or actions.
- [Context vs props](https://control-ui.dev/skills/context-vs-props): Reach for a compound-component context only when props cannot reach the part, and store intent in it, not styling.

## Machine-readable indexes

- [Registry API](https://control-ui.dev/api/registry): JSON index of every public catalog item.
- [Agent index](https://control-ui.dev/r/agent-index.json): Static agent-friendly registry metadata.
- [shadcn registry](https://control-ui.dev/r/registry.json): Registry schema consumed by shadcn tooling.
- [Skin anatomy contract](https://control-ui.dev/r/skin-contract.json): Generated scopes, parts, states, paints, adornments, and semantic families.
- [Theme token contract](https://control-ui.dev/r/theme-contract.json): Generated skin token reference.

## Optional

- [Extended agent reference](https://control-ui.dev/llms-full.txt): Detailed catalog, install commands, and Control UI practice rules.