āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā ā š shadcn/components/blocks.md ā āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
Contribute components to the blocks library.
We are inviting the community to contribute to the blocks library. Share your components and blocks with other developers and help build a library of high-quality, reusable components.
We'd love to see all types of blocks: applications, marketing, products, and more.
Setup your workspace
Fork the repository
Copygit clone https://github.com/shadcn-ui/ui.git
Create a new branch
Copygit checkout -b username/my-new-block
Install dependencies
Copypnpm install
Start the dev server
Copypnpm www:dev
Add a block
A block can be a single component (eg. a variation of a ui component) or a complex component (eg. a dashboard) with multiple components, hooks, and utils.
Create a new block
Create a new folder in the apps/www/registry/new-york/blocks directory. Make sure the folder is named in kebab-case and under new-york.
Copyapps
āāā www
āāā registry
āāā new-york
āāā blocks
āāā dashboard-01
Note: The build script will take care of building the block for the default style.
Add your block files
Add your files to the block folder. Here is an example of a block with a page, components, hooks, and utils.
Copydashboard-01
āāā page.tsx
āāā components
āāā hello-world.tsx
āāā example-card.tsx
āāā hooks
āāā use-hello-world.ts
āāā lib
āāā format-date.ts
Note: You can start with one file and add more files later.
Add your block to the registry
Add your block definition to registry-blocks.tsx
To add your block to the registry, you need to add your block definition to registry-blocks.ts.
This follows the registry schema at https://ui.shadcn.com/schema/registry-item.json.
apps/www/registry/registry-blocks.tsx
Copyexport 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/components/example-card.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"],
},
]
Make sure you add a name, description, type, registryDependencies, dependencies, files, and categories. We'll go over each of these in more detail in the schema docs (coming soon).
Run the build script
Copypnpm registry:build
Note: you do not need to run this script for every change. You only need to run it when you update the block definition.
View your block
Once the build script is finished, you can view your block at http://localhost:3333/blocks/[CATEGORY] or a full screen preview at http://localhost:3333/view/styles/new-york/dashboard-01.
Build your block
You can now build your block by editing the files in the block folder and viewing the changes in the browser.
If you add more files, make sure to add them to the files array in the block definition.
Publish your block
Once you're ready to publish your block, you can submit a pull request to the main repository.
Run the build script
Copypnpm registry:build
Capture a screenshot
Copypnpm registry:capture
Note: If you've run the capture script before, you might need to delete the existing screenshots (both light and dark) at apps/www/public/r/styles/new-york and run the script again.
Submit a pull request
Commit your changes and submit a pull request to the main repository.
Your block will be reviewed and merged. Once merged it will be published to the website and available to be installed via the CLI.
Categories
The categories property is used to organize your block in the registry.
Add a category
If you need to add a new category, you can do so by adding it to the registryCategories array in apps/www/registry/registry-categories.ts.
apps/www/registry/registry-categories.ts
Copyexport const registryCategories = [
// ...
{
name: "Input",
slug: "input",
hidden: false,
},
]
Guidelines
Here are some guidelines to follow when contributing to the blocks library.
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā