Installation

Patch UI requires React 19 and Tailwind CSS v4. The shadcn CLI copies source and installs component dependencies, so there is no Patch UI package to add or version to maintain.

1. Initialize shadcn

Create components.json if the project does not already have one.

$npx shadcn@latest init

Keep the aliases generated by shadcn aligned with where the project stores components, utilities, and CSS.

2. Register Patch UI

Add the Patch UI namespace to components.json.

$npx shadcn@latest registry add @patchui=https://ui.hotfix.jobs/r/{name}.json

This creates the registry mapping used by later @patchui/<name> commands. The equivalent manual configuration is:

{
  "registries": {
    "@patchui": "https://ui.hotfix.jobs/r/{name}.json"
  }
}

3. Add a component

Start with Button to verify the component path and dependency setup.

$npx shadcn@latest add @patchui/button

The command copies the component plus required utilities, shared recipes, npm dependencies, and styles/patch-ui-tokens.css.

4. Import the tokens

Load the copied token file through the project’s Tailwind CSS entry file.

/* app/globals.css */
@import "tailwindcss";
@import "../styles/patch-ui-tokens.css";

Resolve the second path relative to the CSS file. For example, src/app/globals.css commonly needs ../../styles/patch-ui-tokens.css.

You can now import the copied component from the alias configured by shadcn:

import { Button } from "@/components/ui/button";
 
export default function App() {
  return <Button variant="primary">Save changes</Button>;
}

Add more components

Install several registry items in one command when building a complete surface:

$npx shadcn@latest add @patchui/button @patchui/input @patchui/card

Use the all item only when the project expects to use most of the library:

$npx shadcn@latest add @patchui/all

Installing individual items keeps the initial code surface smaller. Registry dependencies are resolved automatically either way.

Light and dark mode

The token file defines both themes. Add the dark class to the document element to activate dark mode.

<html class="dark">

Install Theme Toggle when the application needs system preference detection and persistent user control.

Updating copied components

Run the same add command again when you want to pull a newer registry version, then review the diff before accepting it.

$npx shadcn@latest add @patchui/button

Local source and token changes belong to the consuming project. Keep intentional customizations when reconciling upstream updates.