Installation

Shelf UI components are designed for React projects using Tailwind CSS v4 and TypeScript. Follow the steps below to get set up.

Prerequisites

Make sure your project has the following:

Shelf UI also depends on shared utilities from shadcn/ui. If you don't have shadcn set up yet, initialize it first:

terminal

npx shadcn@latest init

terminal

pnpm dlx shadcn@latest init

terminal

yarn dlx shadcn@latest init

terminal

bunx shadcn@latest init

Add registry

Add the Shelf UI registry to your components.json:

components.json

{
  "registries": {
    "@shelf-ui": "https://shelf-ui.vercel.app/r/{name}.json"
  }
}

Add components

Option 1: shadcn CLI (recommended)

terminal

npx shadcn@latest add @shelf-ui/dropzone

terminal

pnpm dlx shadcn@latest add @shelf-ui/dropzone

terminal

yarn dlx shadcn@latest add @shelf-ui/dropzone

terminal

bunx shadcn@latest add @shelf-ui/dropzone

Option 2: Direct URL

Add components by passing the registry URL directly:

terminal

npx shadcn@latest add https://shelf-ui.vercel.app/r/dropzone.json

terminal

pnpm dlx shadcn@latest add https://shelf-ui.vercel.app/r/dropzone.json

terminal

yarn dlx shadcn@latest add https://shelf-ui.vercel.app/r/dropzone.json

terminal

bunx shadcn@latest add https://shelf-ui.vercel.app/r/dropzone.json

Option 3: Manual installation

Copy the component source directly from its docs page into your project and install the required dependencies listed on that page.

Each component page includes the full source and a list of peer dependencies required. The shadcn CLI handles this automatically in Options 1 and 2.

Project structure

After adding components, your project will look like this:

project structure

components/
├── shelf-ui/
│   └── dropzone.tsx          # Shelf UI component
├── ui/
│   ├── button.tsx            # shadcn/ui primitive
│   └── ...
hooks/
│   └── use-file-upload.ts    # Shelf UI hook
└── ...

Components in shelf-ui/ are Shelf UI primitives. Components in ui/ are shared shadcn/ui primitives that Shelf UI components may depend on.

Usage

Import and use components directly:

app/page.tsx

import { Dropzone } from "@/components/shelf-ui/dropzone";
import {
  FileCard,
  FileCardActions,
  FileCardIcon,
  FileCardInfo,
} from "@/components/shelf-ui/file-card";

export default function Page() {
  return (
    <>
      {/* Simple component — use props */}
      <Dropzone
        onDrop={(files) => console.log(files)}
        accept={["image/*", ".pdf"]}
        maxSize={10 * 1024 * 1024}
      />

      {/* Compound component — compose sub-components */}
      <FileCard>
        <FileCardIcon type="pdf" />
        <FileCardInfo name="report.pdf" size="2.4 MB" />
        <FileCardActions>
          <Button size="icon">
            <Download />
          </Button>
        </FileCardActions>
      </FileCard>
    </>
  );
}

See individual component pages for detailed usage, props, and examples.

On this page