Base Components

Purpose and Scope

The base component family is the part of shadcn/ui that presents components backed by Base UI primitives and styled through the v4 registry system. In the docs navigation, this family is labeled Base UI, and it contains a broad catalog that spans low-level controls, layout primitives, form surfaces, navigation, feedback, data display, and AI-adjacent message components. The purpose of this page is to help contributors and advanced users understand the family as a coherent registry surface rather than as a list of unrelated component pages. If you are choosing whether to use a Base-backed component, start by treating it as copyable application code with accessible primitive behavior supplied by Base UI and shadcn/ui styling layered on top.

Sources: apps/v4/content/docs/components/base/meta.json

The source evidence shows two complementary views of the family. The metadata file defines the documentation spine: it names the family, orders the pages, and exposes which component docs belong to the Base UI section. The preview block entrypoints show the implementation-facing side: large composite examples import many card-like blocks from apps/v4/registry/bases/base/blocks/... and arrange them in a capture-oriented grid. Together, these files show that “base components” are not only single reusable controls such as button or accordion; they are also the building blocks used to compose polished previews, examples, and registry-distributed design surfaces.

Sources: apps/v4/content/docs/components/base/meta.json, apps/v4/registry/bases/base/blocks/preview/index.tsx, apps/v4/registry/bases/base/blocks/preview-02/index.tsx

Relevant Source Files

• apps/v4/content/docs/components/base/meta.json — Defines the Base UI docs group and the ordered list of Base component pages, including controls such as accordion, button, dialog, form, message, message-scroller, sidebar, sonner, and toast.
• apps/v4/registry/bases/base/blocks/preview/index.tsx — Implements the first large Base registry preview surface by importing many authored preview cards and rendering them into a responsive, horizontally scrollable grid.
• apps/v4/registry/bases/base/blocks/preview-02/index.tsx — Implements a second Base registry preview surface with another collection of authored cards, using the same grid and capture-target structure to demonstrate breadth across product-style compositions.

System-to-Code Mapping

The mapping matters because the docs metadata and the preview registry entrypoints serve different readers. A documentation reader uses the metadata indirectly through the site navigation, moving from one component page to another. A registry contributor uses the preview files to verify that the Base implementation surface still produces complete application-like compositions. When you add or change Base components, these two surfaces should stay conceptually aligned: docs should expose the component entry, and registry previews should continue to demonstrate how copied components behave inside real layouts.

Sources: apps/v4/content/docs/components/base/meta.json, apps/v4/registry/bases/base/blocks/preview/index.tsx, apps/v4/registry/bases/base/blocks/preview-02/index.tsx

Base Family Contract

A Base component page follows the same user-facing contract shown in the official Base docs examples for components such as Accordion and Alert Dialog: the user can install with the CLI, install @base-ui/react manually when copying code, and import named components from their local @/components/ui/... path. That contract is important because shadcn/ui does not hide implementation code inside an opaque package. The registry installs code into the application, so a team can inspect it, edit it, and align it with local design tokens, import aliases, and framework conventions.

The family list in meta.json also shows that Base is intended to be a complete UI layer, not a narrow primitive experiment. It includes interactive controls such as checkbox, radio-group, slider, switch, tabs, and toggle-group; overlay and disclosure components such as dialog, drawer, popover, sheet, tooltip, and hover-card; and application structure such as sidebar, navigation-menu, pagination, resizable, and scroll-area. That breadth is a signal to contributors: changes to shared styling, slots, or composition conventions can affect many component categories, so local testing should include simple controls and larger layouts.

Sources: apps/v4/content/docs/components/base/meta.json

The same list includes specialized surfaces that are easy to miss if you only scan for traditional form widgets. message and message-scroller appear alongside bubble, attachment, and toast, which positions the Base family for modern chat, notification, and content-heavy interfaces. It also contains calendar, date-picker, data-table, chart, carousel, and typography, so the family covers both atomic components and higher-level presentation patterns. When documenting or reviewing a Base component, describe not only the primitive behavior but also how it participates in this wider catalog.

Sources: apps/v4/content/docs/components/base/meta.json

Preview Registry Surface

The first preview entrypoint is a client component, indicated by the "use client" directive at the top of the file. It imports a large set of card modules, including analytics, alerts, booking, file upload, invoice, profile, shortcuts, skeleton loading, typography, usage, visitors, and fitness summary examples. The rendered structure is intentionally wide: an overflow container wraps a min-w-max flex child, which contains a seven-column grid with explicit widths for default and medium breakpoints. This makes the preview behave more like a capture board than a normal page section.

Sources: apps/v4/registry/bases/base/blocks/preview/index.tsx

The grid classes in the first preview show several implementation conventions used by the Base registry previews. A CSS custom property named --gap is initialized with a spacing token and adjusted at larger breakpoints. The container switches between muted and background colors in dark mode. Style-specific variants such as style-lyra and style-mira adjust width and gap behavior, which lets one authored Base preview adapt to different visual styles. The data-slot="capture-target" marker gives downstream capture or preview tooling a stable element to target without coupling to component names.

Sources: apps/v4/registry/bases/base/blocks/preview/index.tsx

The second preview entrypoint follows the same composition model but demonstrates another product vocabulary: account access, balances, contribution history, payments, preferences, transactions, stock performance, savings targets, and upcoming payments. This matters because the Base registry is validated through variety. A component family that only works for one dashboard would be brittle; these previews test whether the same cards, controls, states, typography, spacing, and dark-mode classes remain convincing across finance, media, smart-home, onboarding, and settings-like experiences.

Sources: apps/v4/registry/bases/base/blocks/preview-02/index.tsx

Working with Base Components

When you work with a Base component as an application developer, use the component docs as the entrypoint and the registry preview as a confidence check. The official docs examples show a consistent installation pattern, such as adding accordion with npx shadcn@latest add accordion or manually installing @base-ui/react, copying the component source, and updating import paths. After installation, import from your local component path, for example @/components/ui/accordion, and compose the exported parts in your application tree. The repository metadata tells you which component pages should exist in the Base family; the preview files show whether real combinations still render together.

npx shadcn@latest add accordion
npm install @base-ui/react

A contributor should think in three layers. First, the Base UI primitive layer supplies accessible interaction semantics for components that need them. Second, the shadcn/ui component source defines the local API, slots, class names, and styling defaults that users copy into their projects. Third, preview blocks exercise the components in realistic compositions, including hidden and responsive variants, dark backgrounds, capture targets, and style-specific class modifiers. If a change affects slot naming, composition structure, or layout behavior, update examples and inspect preview surfaces instead of relying only on a single component demo.

Sources: apps/v4/content/docs/components/base/meta.json, apps/v4/registry/bases/base/blocks/preview/index.tsx, apps/v4/registry/bases/base/blocks/preview-02/index.tsx

The most useful review habit is to move from narrow to broad. Start with the component page named in meta.json, confirm the install and usage story still makes sense, then test a direct example, and finally inspect the preview boards that combine many modules. The preview entrypoints are especially useful for catching regressions that do not appear in isolated examples: spacing drift, dark-mode contrast issues, overflow behavior, responsive visibility mistakes, and style-specific width differences. Because both preview files use the same seven-column capture pattern, differences in appearance are more likely to come from component or card changes than from unrelated page layout changes.

Sources: apps/v4/content/docs/components/base/meta.json, apps/v4/registry/bases/base/blocks/preview/index.tsx, apps/v4/registry/bases/base/blocks/preview-02/index.tsx

Compact Reference

Next Steps

If you are installing components, continue from the specific component page, such as Accordion, Alert Dialog, Button, Dialog, Form, or Sidebar, and follow that page’s CLI or manual installation instructions. If you are contributing to the registry, inspect the Base preview boards after making changes that affect layout, theme tokens, slots, or composition. The most productive next read is the broader registry documentation, because it explains how authored registry source becomes generated styles and installable output. From there, compare Base components with the Radix family when deciding which primitive stack best fits a component or example.

Sources: apps/v4/content/docs/components/base/meta.json, apps/v4/registry/bases/base/blocks/preview/index.tsx, apps/v4/registry/bases/base/blocks/preview-02/index.tsx