Guides

Installation

DitherUI is a standard shadcn registry. Register it once in components.json, then every component and block installs with one command, source files and dependencies included.

1Set up shadcn/ui

You need a React project (Next.js, Vite, TanStack Start or similar) with Tailwind CSS and shadcn/ui. Skip this if you already have a components.json. See the shadcn/ui installation guide for framework-specific setup.

$ pnpm dlx shadcn@latest init

2Register DitherUI

Add the @ditherui namespace to components.json. The CLI replaces {name} with the item you ask for and sends your key as a header.

JSONcomponents.json

{
  "registries": {
    "@ditherui": {
      "url": "https://ditherui.dev/r/{name}.json",
      "headers": { "Authorization": "Bearer ${DITHERUI_API_KEY}" }
    }
  }
}

3Add your API key

Free items install without one. For All-Access items, create a key on your profile page and make it available to the CLI as DITHERUI_API_KEY.

Shell.env.local

DITHERUI_API_KEY=ditherui_xxxxxxxx

4Install a component

Every docs page shows its own command. The CLI copies the source into components/ditherui and installs its dependencies, so you own and can edit the files. Pick your package manager; the choice is remembered across the site.

$ pnpm dlx shadcn@latest add @ditherui/switch

Free items also install straight from their URL, with no registration at all.

$ pnpm dlx shadcn@latest add https://ditherui.dev/r/switch.json

5Use it

Import it from where the CLI put it. Prefer not to use the CLI? Open any component page and pick Manual to copy the source, then install the packages it imports (usually motion and radix-ui) yourself.

TSX

import { Switch } from "@/components/ditherui/motion-switch"

export function Example() {
  return <Switch defaultChecked />
}

Troubleshooting

401 Unauthorized
The item is premium. Create an API key on your profile page and set DITHERUI_API_KEY before running the command. Free items never need it.
Unknown registry "@ditherui"
The registries entry is missing from components.json, or it is not valid JSON.
404 Not found
The item name is wrong. Copy the command from the component's page, or browse the names in the registry index.
Missing environment variable
The CLI could not see DITHERUI_API_KEY. Export it in your shell or put it in .env.local in the project root.