Components Overview
Purpose and Scope
The components section is the front door for the shadcn/ui component catalog. Its job is intentionally simple: show what is new, show the complete catalog, and send readers to the registry directory when the first-party catalog does not contain the component they need. The landing page defines the title as “Components” and describes the section as the place to find all components available in the library, while acknowledging that more components are still being added. That framing matters because shadcn/ui is not presented as a closed widget kit; it is a growing catalog of source components that teams can install, customize, and extend in their own applications.
Sources: apps/v4/content/docs/components/index.mdx
This overview should be read before diving into a specific component such as Button, Dialog, Sidebar, Calendar, Command, or Message Scroller. The catalog is organized around visible documentation pages, not a hidden runtime package API. A reader usually starts from the component index, chooses either the new-component list or the all-component list, then follows a component page for installation, usage, composition, examples, and API notes. When a component page is part of a family such as React Aria, Radix UI, or Base UI, that family name tells you which implementation style and underlying primitives the documentation is grouping together.
Sources: apps/v4/content/docs/components/index.mdx, apps/v4/content/docs/components/aria/meta.json, apps/v4/content/docs/components/radix/meta.json, apps/v4/content/docs/components/base/meta.json
Relevant Source Files
- apps/v4/content/docs/components/index.mdx — Defines the public components landing page with “New Components”, “All Components”, and the registry-directory fallback message.
- apps/v4/content/docs/components/meta.json — Defines the top-level documentation navigation title for the components section.
- apps/v4/content/docs/components/aria/meta.json — Defines the React Aria component family title and its page slugs.
- apps/v4/content/docs/components/radix/meta.json — Defines the Radix UI component family title and its page slugs.
- apps/v4/content/docs/components/base/meta.json — Defines the Base UI component family title and its page slugs.
Catalog Entry Points
The component landing page has two explicit entry points: “New Components” and “All Components”. Both are rendered through ComponentsList, with the new list passing variant="new" and the full list using the default component list. The source does not spell out how the list is computed, but the public documentation contract is clear: the page separates discovery of recent additions from browsing the complete catalog. That split helps both returning users and new adopters. Returning users can quickly scan what changed, while new adopters can treat the all-components view as a catalog map.
Sources: apps/v4/content/docs/components/index.mdx
The final note on the landing page is also part of the workflow: “Can't find what you need? Try the registry directory for community-maintained components.” This establishes a boundary between the first-party docs catalog and the broader registry ecosystem. The first-party component list is the curated path for supported examples and documentation, while the directory is the discovery path for community-maintained components and blocks. When documenting or building with shadcn/ui, keep that distinction in mind: the component catalog explains the official docs surface, and the registry directory expands what can be installed from external maintainers.
Sources: apps/v4/content/docs/components/index.mdx
Component Families
The docs source defines three major family groupings under the components section: React Aria, Radix UI, and Base UI. Each family has its own meta.json title and page list, which means the same component concept can appear under more than one implementation family. For example, common slugs such as accordion, alert-dialog, avatar, button, calendar, command, dialog, dropdown-menu, form, sidebar, sonner, table, tabs, toast, tooltip, and typography appear across the family metadata. This lets the documentation preserve a shared component vocabulary while still separating implementation choices.
Sources: apps/v4/content/docs/components/aria/meta.json, apps/v4/content/docs/components/radix/meta.json, apps/v4/content/docs/components/base/meta.json
The React Aria family is titled “React Aria” and contains a broad list of accessible UI patterns, including form controls, overlays, navigation patterns, chat-oriented pieces, and layout helpers. The list includes newer or more specialized entries such as attachment, bubble, message, message-scroller, native-select, direction, field, input-group, item, marker, and spinner. In practice, this family tells readers that the component documentation is organized around React Aria-style primitives and accessibility patterns. It is the right starting point when the reader wants components whose docs emphasize ARIA behavior, keyboard interaction, and composable application UI.
Sources: apps/v4/content/docs/components/aria/meta.json
The Radix UI family is titled “Radix UI” and closely mirrors the React Aria catalog while adding Radix-specific navigation and menu patterns such as hover-card, menubar, and navigation-menu. Its metadata includes many of the same core building blocks, from accordion and dialog through select, slider, switch, tabs, and tooltip. This overlap is deliberate from a reader’s perspective: a product team may know the component it needs before it chooses the primitive family. The Radix section allows that team to stay in a Radix-oriented documentation track without changing the component names it searches for.
Sources: apps/v4/content/docs/components/radix/meta.json
The Base UI family is titled “Base UI” and also contains the broad catalog, including hover-card, menubar, and navigation-menu. Its page list aligns closely with the Radix UI list, which signals that the docs treat Base UI as another implementation family for the same design-system vocabulary. Readers should not interpret the family lists as unrelated catalogs. They are parallel documentation surfaces for building the same kinds of interfaces: alerts, buttons, calendars, command palettes, dialogs, dropdowns, forms, data tables, sidebars, toasts, and chat components. The family selection changes the implementation context, not the overall product problem being solved.
Sources: apps/v4/content/docs/components/base/meta.json
System-to-Code Mapping
At the source level, this page maps to a small but important documentation structure. The top-level meta.json gives the section its navigation title, while the landing MDX supplies the reader-facing introduction and list placeholders. The family metadata files then enumerate the page slugs that belong to each implementation family. This means that a catalog change is usually reflected by adding, removing, or reordering slugs in family metadata, and by ensuring the landing page can surface the result through its component-list UI. The catalog is therefore maintained as documentation data plus MDX composition, rather than as a single handwritten index page.
Sources: apps/v4/content/docs/components/index.mdx, apps/v4/content/docs/components/meta.json, apps/v4/content/docs/components/aria/meta.json, apps/v4/content/docs/components/radix/meta.json, apps/v4/content/docs/components/base/meta.json
A useful way to read the metadata is as a taxonomy. The top-level section says “Components”. The family roots say “React Aria”, “Radix UI”, and “Base UI”. Under those roots, page slugs provide the stable names readers use in URLs, navigation, search, and internal docs links. Some slugs describe primitive controls, such as checkbox, input, radio-group, select, slider, switch, and textarea. Others describe composed interface regions, such as command, data-table, date-picker, sidebar, navigation-menu, and message-scroller. This taxonomy helps teams decide whether they are looking for a small control, a composed pattern, or a full guide.
Sources: apps/v4/content/docs/components/aria/meta.json, apps/v4/content/docs/components/radix/meta.json, apps/v4/content/docs/components/base/meta.json
| Documentation source | Public role | Notable contract |
|---|---|---|
apps/v4/content/docs/components/index.mdx | Components landing page | Shows New Components, All Components, and the registry directory fallback. |
apps/v4/content/docs/components/meta.json | Section navigation metadata | Titles the top-level section as Components. |
apps/v4/content/docs/components/aria/meta.json | React Aria family metadata | Titles the family as React Aria and lists React Aria component pages. |
apps/v4/content/docs/components/radix/meta.json | Radix UI family metadata | Titles the family as Radix UI and lists Radix-oriented component pages. |
apps/v4/content/docs/components/base/meta.json | Base UI family metadata | Titles the family as Base UI and lists Base UI component pages. |
Reader Workflow
Start with the landing page when you do not yet know the exact component name. The new-components area is the fastest place to discover recent additions, while the all-components area is the broad catalog scan. If you already know the pattern, jump directly to the matching slug in the family you are using. For example, a team building an application shell might look for sidebar, breadcrumb, navigation-menu, and dropdown-menu; a team building forms might look for form, field, input, select, checkbox, and radio-group; a team building AI or chat UI might look for message, message-scroller, bubble, and attachment.
Sources: apps/v4/content/docs/components/index.mdx, apps/v4/content/docs/components/aria/meta.json, apps/v4/content/docs/components/radix/meta.json, apps/v4/content/docs/components/base/meta.json
After choosing a component, read the component page in the context of its family instead of treating every slug as a single universal implementation. The official docs often use component pages to explain composition and behavior, not just installation commands. For instance, the documented data-table approach is framed as a guide for building a custom table with TanStack Table and a basic table component, because real datagrids vary by data source, sorting, filtering, row actions, and selection needs. Similarly, chat-oriented pages such as Message Scroller emphasize interaction behavior, including how streaming content should follow or hold the reader’s scroll position. Those examples reinforce the catalog’s larger pattern: components are starting points for application-specific UI, not immutable black boxes.
Sources: apps/v4/content/docs/components/aria/meta.json
Implementation Details and Maintenance Signals
The family metadata reveals both shared coverage and small family differences. React Aria, Radix UI, and Base UI all include a large common core: disclosure components, feedback components, form inputs, overlays, navigation aids, layout pieces, and data-display patterns. Radix UI and Base UI include hover-card, menubar, and navigation-menu, while the supplied React Aria list does not include those slugs. When adding docs or building internal navigation, this difference should be handled intentionally. A page should appear under the family where it is actually documented, and cross-family assumptions should be verified against the relevant meta.json list.
Sources: apps/v4/content/docs/components/aria/meta.json, apps/v4/content/docs/components/radix/meta.json, apps/v4/content/docs/components/base/meta.json
Because the landing page delegates visual listing to ComponentsList, the MDX remains concise and focused on reader intent. The maintenance responsibility is split: the MDX defines the page structure and fallback message, while metadata files define the navigable catalog. That split is useful for a docs-heavy repository because it keeps the overview readable and lets component additions be represented as data. When reviewing changes to the component catalog, check that the family metadata, component page, and landing-page behavior all agree. If a component is meant to be broadly discoverable, it should not only have a page; it should also appear in the appropriate family list and, when relevant, be eligible for the new-components presentation.
Sources: apps/v4/content/docs/components/index.mdx, apps/v4/content/docs/components/aria/meta.json, apps/v4/content/docs/components/radix/meta.json, apps/v4/content/docs/components/base/meta.json
Next Steps
If you are evaluating shadcn/ui for a project, first choose your implementation family, then open the specific component pages that match your product surface. Use the catalog for first-party documentation and examples, and use the registry directory when your need falls outside the curated list. If you are maintaining documentation, update the relevant family metadata alongside new or changed component pages so navigation remains accurate. Good follow-up pages are the family overviews for ARIA, Radix, and Base components, then focused component pages such as Button, Dialog, Command, Calendar, Sidebar, Sonner, and the forms documentation.
Sources: apps/v4/content/docs/components/index.mdx, apps/v4/content/docs/components/meta.json, apps/v4/content/docs/components/aria/meta.json, apps/v4/content/docs/components/radix/meta.json, apps/v4/content/docs/components/base/meta.json