OpenWikishadcn-ui/ui

Blocks

Purpose and Scope

Blocks are shadcn/ui’s ready-made application sections: larger examples such as dashboards, authentication pages, cards, product surfaces, marketing sections, and other reusable layouts. They are not a separate design system from the rest of the project. The changelog introduces Blocks as responsive, accessible, composable components built with the same principles as the component catalog, and the contributor guide invites the community to share applications, marketing blocks, product blocks, and more. That framing matters when contributing: a block should demonstrate useful product structure while still being easy for another developer to copy, customize, and own in their app.

Sources: apps/v4/content/docs/(root)/_blocks.mdx, apps/v4/content/docs/changelog/2024-03-blocks.mdx

The practical goal of the Blocks workflow is to turn a local example into registry content. A block may be a single component variation or a complex feature area with a page, components, hooks, and utilities. The registry definition then describes how those files should be installed, what other shadcn/ui registry items they need, what npm dependencies they require, and where page-level files should land in the target application. Treat the block folder as the source of the implementation and the registry entry as the install contract consumed by the shadcn tooling.

Sources: apps/v4/content/docs/(root)/_blocks.mdx

Relevant Source Files

  • apps/v4/content/docs/(root)/_blocks.mdx — contributor-facing guide for workspace setup, block folder structure, registry item definition, build command, and local preview URLs.
  • apps/v4/content/docs/changelog/2024-03-blocks.mdx — launch announcement that defines Blocks as open-source, responsive, accessible, composable ready-made components and explains the initial dashboard and authentication focus.
  • apps/v4/registry/bases/aria/blocks/preview/index.tsx — ARIA base preview surface that imports many block preview cards and lays them out in a wide capture grid.
  • apps/v4/registry/bases/base/blocks/preview/index.tsx — base registry preview surface with a parallel block-card grid for the base implementation family.

Contribution Workflow

Start by preparing a repository checkout and a topic branch for the block. The contributor guide shows a simple sequence: clone the repository, create a branch named for the author and block, install dependencies, and start the documentation site development server. This gives you a local environment where the registry content, documentation pages, and block previews can be exercised together instead of developing a block in isolation. The important discipline is to keep the contribution branch focused on one block or closely related set of block changes so review can connect the registry metadata, source files, and rendered preview.

git clone https://github.com/shadcn-ui/ui.git
git checkout -b username/my-new-block
pnpm install
pnpm www:dev

Sources: apps/v4/content/docs/(root)/_blocks.mdx

Create the block as a new kebab-case folder under the new-york block registry tree described by the contributor guide. Kebab-case names such as dashboard-01 become stable registry item names, route fragments, and preview identifiers, so avoid names that encode private project terminology. The docs also note that the build script takes care of building the block for the default style, which lets contributors focus on the canonical source while the registry build process produces the additional style output expected by the site and installer.

apps
└── www
    └── registry
        └── new-york
            └── blocks
                └── dashboard-01

Sources: apps/v4/content/docs/(root)/_blocks.mdx

Block File Structure

A block can start small and grow. The example structure in the guide includes a page.tsx, nested components, a hooks directory, and a lib utility directory. That layout mirrors how real application code is organized, which is useful because Blocks are meant to be copied into working apps rather than consumed as opaque package exports. Page files demonstrate integration, components hold reusable UI, hooks isolate client behavior, and utilities keep formatting or data helpers out of JSX. Contributors should use this structure to make boundaries obvious for downstream users who will customize the copied code.

dashboard-01
└── page.tsx
└── components
    └── hello-world.tsx
    └── example-card.tsx
└── hooks
    └── use-hello-world.ts
└── lib
    └── format-date.ts

Sources: apps/v4/content/docs/(root)/_blocks.mdx

The block source should be self-explanatory enough to survive copying into another application. Because shadcn/ui distributes code rather than hiding implementation behind a package boundary, a good block should use clear component names, ordinary imports, and local helpers that users can edit. The official component docs follow the same copy-and-own model for smaller components: install dependencies, copy code, and update import paths to match the project. Blocks extend that pattern to larger compositions, so a contributor should prefer explicit files and registry dependencies over hidden assumptions.

Sources: apps/v4/content/docs/(root)/_blocks.mdx

Registry Definition and Build

After the files exist, add the block definition to the block registry list. The guide’s example uses the registry item schema and includes the fields reviewers expect: name, author, title, description, type, registryDependencies, dependencies, files, and categories. registryDependencies names other shadcn/ui registry items such as input, button, and card; dependencies names package dependencies such as zod; and each file entry declares a source path plus a registry file type. Page files can also include a target, for example installing a block page at app/dashboard/page.tsx.

export const blocks = [
  {
    name: "dashboard-01",
    author: "shadcn (https://ui.shadcn.com)",
    title: "Dashboard",
    description: "A simple dashboard with a hello world component.",
    type: "registry:block",
    registryDependencies: ["input", "button", "card"],
    dependencies: ["zod"],
    files: [
      {
        path: "blocks/dashboard-01/page.tsx",
        type: "registry:page",
        target: "app/dashboard/page.tsx",
      },
      { path: "blocks/dashboard-01/components/hello-world.tsx", type: "registry:component" },
      { path: "blocks/dashboard-01/hooks/use-hello-world.ts", type: "registry:hook" },
      { path: "blocks/dashboard-01/lib/format-date.ts", type: "registry:lib" },
    ],
    categories: ["dashboard"],
  },
]

Sources: apps/v4/content/docs/(root)/_blocks.mdx

Run the registry build when the block definition changes. The contributor guide is explicit that this does not need to happen for every source edit; it is needed when registry metadata changes. That distinction keeps the edit-preview loop fast while still ensuring generated registry artifacts match the install contract before a contribution is submitted. After a successful build, view the block in its category page or open the full-screen style preview for the item. These preview URLs are part of the contributor workflow because they validate both discoverability and the installed visual result.

pnpm registry:build
http://localhost:3333/blocks/[CATEGORY]
http://localhost:3333/view/styles/new-york/dashboard-01

Sources: apps/v4/content/docs/(root)/_blocks.mdx

Preview Implementation Details

The preview implementations show what the Blocks library optimizes for at scale: many independently authored cards rendered together in a consistent capture surface. Both ARIA and base preview entrypoints are client components that import a catalog of cards such as AnalyticsCard, Invoice, FeedbackForm, FileUpload, StyleOverview, TypographySpecimen, UIElements, and WeeklyFitnessSummary. The exported PreviewExample arranges those cards in a wide grid with horizontal overflow, muted and dark backgrounds, style-specific sizing adjustments, and a data-slot="capture-target" marker used by capture-oriented workflows.

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

The ARIA and base preview files are intentionally parallel. The ARIA preview imports from @/registry/bases/aria/blocks/preview/cards/..., while the base preview imports from @/registry/bases/base/blocks/preview/cards/.... This split lets the site demonstrate equivalent block ideas across different component foundations without changing the high-level preview layout. When adding or adjusting a block family, keep that separation in mind: shared product intent can remain consistent, but implementation details should live in the correct base registry path so users receive the variant they selected.

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

The preview grid also includes performance-conscious layout choices. The snippets show content-visibility:auto, contain-intrinsic-size, explicit wide widths, responsive gap variables, and conditional rendering of UIElements for mobile versus desktop placements. Those details are not incidental decoration; they make a large block gallery practical to render and capture. Contributors building complex blocks should test them in the preview context, not only as isolated pages, because the gallery stresses spacing, dark mode, responsive behavior, and composition with neighboring cards.

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

Publishing and Review Checklist

Before opening a contribution, verify the block matches the Blocks promise from the launch notes: responsive, accessible, composable, open source, and suitable for customization. The initial public focus was dashboards and authentication pages, but the contributor guide explicitly welcomes applications, marketing, products, and other reusable UI. A useful contribution therefore solves a recognizable product problem and exposes understandable code boundaries. If a desired block does not exist yet, the changelog also points to a request workflow where the community can propose, upvote, and build ideas.

Sources: apps/v4/content/docs/(root)/_blocks.mdx, apps/v4/content/docs/changelog/2024-03-blocks.mdx

Use this checklist before publishing a pull request: the folder name is kebab-case, files are placed under the documented block directory, the registry item has all required descriptive and dependency fields, page entries declare the intended target path, pnpm registry:build has been run after metadata changes, and both category and full-screen previews load locally. Also review whether the block can be edited in downstream tools such as v0, because the launch announcement highlights “Edit in v0” as a path for prompting and further generation after users discover a block.

Sources: apps/v4/content/docs/(root)/_blocks.mdx, apps/v4/content/docs/changelog/2024-03-blocks.mdx

Next Steps

If you are contributing a block, begin with the contributor workflow above, then read the registry pages to understand item schema, dependency resolution, and build behavior in more detail. If you are consuming blocks, start from the Blocks library preview, inspect the source, and treat the installed files as application code you are expected to modify. For adjacent workflows, continue to the registry overview for install mechanics, the build-and-publish registry guide for validation, or the Figma and v0 page for design handoff and AI-assisted customization.

Ask a question...