Getting Started

This guide walks you through browsing, previewing, and installing blocks from Shadcn Blocks in your project.

Prerequisites

Our blocks are built with React, Tailwind CSS, and shadcn/ui — the same stack you’re already using. They work seamlessly in any React + Tailwind project, including Next.js, Astro, Remix, Vite, and more.

To install blocks via the CLI, your project needs:

A components.json file — Configures how the shadcn CLI installs components (paths, styles, aliases)
A globals.css file — Contains the CSS variables that power theming

Don’t have these yet? See Project Setup below, or run npx shadcn init to generate them automatically.

Installing Blocks

Browsing Blocks

The Blocks library is the easiest way to browse and install blocks:

Browse blocks - Use filters and search to find blocks
Preview blocks - Click any block to see it in detail
Copy the CLI command - Click the command in the toolbar to copy it
Run in your terminal - Paste and execute the command

Copy & Paste

You can view and copy the source code directly by clicking the Code tab on any block. This lets you manually paste the code into your project.

Limitations of copy & paste:

No automatic dependency installation - You’ll need to manually install any npm packages the block requires
No component dependencies - If the block uses shadcn components (Button, Card, etc.), you’ll need to install those separately

For these reasons, we recommend using the CLI for installation whenever possible.

CLI Command (Recommended)

The CLI command is displayed in the block detail toolbar:

npx shadcn add @shadcnblocks/hero-1

Or with your preferred package manager:

# pnpm
pnpm dlx shadcn add @shadcnblocks/hero-1

# yarn
yarn dlx shadcn add @shadcnblocks/hero-1

# bun
bunx shadcn add @shadcnblocks/hero-1

Tip: Click the dropdown arrow next to the CLI command to change your default package manager. Your preference is saved for future visits.

Pro Blocks & API Authentication

To install Pro and Premium blocks via the CLI, you’ll need to set up API key authentication.

1. Get your API key

Visit your Dashboard → API Keys and create a new key.

2. Add to your environment

# .env
SHADCNBLOCKS_API_KEY=sk_live_your_api_key_here

3. Configure your components.json

Add the registry with authentication headers:

{
  "registries": {
    "@shadcnblocks": {
      "url": "https://shadcnblocks.com/r/{name}",
      "headers": {
        "Authorization": "Bearer ${SHADCNBLOCKS_API_KEY}"
      }
    }
  }
}

Now you can install any pro block:

npx shadcn add @shadcnblocks/hero-125

For full details and troubleshooting, see the shadcn CLI guide.

Why Use the CLI?

The shadcn CLI is the recommended way to install blocks because it:

1. Respects Your `components.json` Configuration

Your components.json defines important settings that the CLI uses:

Style - Which component style variant to use (Vega, Nova, Maia, Lyra, Mira)
Base color - Your project’s color scheme
CSS variables - Whether to use CSS variables for colors
Tailwind config - Path to your Tailwind configuration
Component aliases - Where components should be installed

2. Chooses the Correct UI Library and Style

The CLI automatically selects between Radix UI and Base UI, and applies the correct component style, based on the style property in your components.json:

// components.json
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "radix-vega", // <-- format: {ui-library}-{style-name}
  ...
}

The style value combines the UI library and visual style:

Style	UI Library	Visual Style	Description
`radix-vega`	Radix UI	Vega	The classic shadcn/ui look. Clean, neutral, and familiar.
`radix-nova`	Radix UI	Nova	Reduced padding and margins for compact layouts.
`radix-maia`	Radix UI	Maia	Soft and rounded, with generous spacing.
`radix-lyra`	Radix UI	Lyra	Boxy and sharp. Pairs well with mono fonts.
`radix-mira`	Radix UI	Mira	Compact. Made for dense interfaces.
`base-vega`	Base UI	Vega	Vega style with Base UI primitives.
`base-nova`	Base UI	Nova	Nova style with Base UI primitives.
`base-maia`	Base UI	Maia	Maia style with Base UI primitives.
`base-lyra`	Base UI	Lyra	Lyra style with Base UI primitives.
`base-mira`	Base UI	Mira	Mira style with Base UI primitives.

This ensures blocks use the same primitive library and visual treatment as your existing components, avoiding conflicts and duplicate dependencies.

3. Handles Dependencies Automatically

The Shadcn CLI:

Installs required NPM packages
Adds dependent components (e.g., if a block uses Button, it installs Button too)
Updates your Tailwind config if needed
Respects your project structure

Project Setup

Creating `components.json`

If you don’t have a components.json, create one in your project root:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "radix-vega",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "iconLibrary": "lucide",
  "rtl": false,
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "menuColor": "default",
  "menuAccent": "subtle",
  "registries": {
    "@shadcnblocks":  "https://shadcnblocks.com/r/{name}"
  }
}

Or use the shadcn init command:

npx shadcn init

Or download from our site

You can also generate a components.json in the blocks toolbar.

Open any block
Click components.json to download

This downloads a components.json pre-configured with your selected style.

Setting Up `globals.css`

Your globals.css should include CSS variables for theming. Download our base globals.css file:

Download globals.css

This file includes all the CSS variables needed for shadcn/ui components, including light and dark mode support.

Or download from our site

You can also download a globals.css from the block toolbar by clicking the Tailwind icon. If you have a theme selected, the downloaded file will include that theme’s color variables.

For more details on CSS variables, themes, and Tailwind configuration, see the Theming & Tailwind guide.

Preview Options

Both the Blocks pages and the Explorer offer ways to customize how you preview blocks before installing them.

Theme

Select from pre-made color themes to preview how the block looks with different color schemes. Themes modify CSS variables like --primary, --background, etc.

Blocks pages: Use the theme selector in the toolbar
Explorer: Use the Theme dropdown in the right sidebar

Appearance

Toggle between Light and Dark mode to preview the block in both appearances.

Blocks pages: Click the sun/moon icon in the toolbar
Explorer: Use the Appearance toggle in the right sidebar

Component Style (Pro/Premium)

Preview blocks with different component styles. This is available in the Explorer sidebar:

Style	Description
Vega (Default)	The classic shadcn/ui look. Clean, neutral, and familiar.
Nova	Reduced padding and margins for compact layouts.
Maia	Soft and rounded, with generous spacing.
Lyra	Boxy and sharp. Pairs well with mono fonts.
Mira	Compact. Made for dense interfaces.

When you install a block via CLI, it uses the style defined in your components.json.

Content Pack (Explorer only)

Some blocks support content packs - pre-made content variations with different images, text, and data. Use this to preview how a block looks with realistic content.

Export Config

Download configuration files for your project:

components.json - Click the shadcn icon in the toolbar (or use Export Config in the Explorer sidebar)
globals.css - Click the Tailwind icon in the toolbar (or use Export Config in the Explorer sidebar)

Both downloads are pre-configured with your selected theme and style.

Next Steps

Browse blocks - The classic blocks library
Explorer - Advanced browsing with sidebar options
Component examples - Individual component variations
Templates - Full page templates