Installation

• React 19
• Next.js 15 or later with the App Router, or Vite
• Tailwind CSS v4
• shadcn set up in the project. npx shadcn@latest init creates components.json, the cn helper in lib/utils.ts, the theme variables and class-based dark mode.

Components are published as a shadcn-compatible registry, so the shadcn CLI installs them, along with their npm packages and any shared files they use.

1. Set up shadcn

Run this in your project. Skip it if you already have a components.json.

npx shadcn@latest init

2. Add a component

Pass the component's registry URL. Every component page shows its own command under Installation.

npx shadcn@latest add https://uibrik.com/r/gauge.json

3. Use it

import { Gauge } from "@/components/uibrik/gauge/gauge";

export default function Page() {
  return <Gauge title="Storage" value={64} />;
}

1. Set up the project

Follow shadcn's Vite guide. It adds Tailwind CSS with @tailwindcss/vite, the @/* path alias in tsconfig.json, tsconfig.app.json and vite.config.ts, and runs shadcn init.

2. Add a component

npx shadcn@latest add https://uibrik.com/r/gauge.json

Files land under src/components/uibrik/, since the alias points at src.

Add the registry to components.json once, then install by name instead of by URL.

{
  "registries": {
    "@uibrik": "https://uibrik.com/r/{name}.json"
  }
}

npx shadcn@latest add @uibrik/gauge

The namespace also lets AI assistants find uibrik components. See MCP.

• Each component lands in components/uibrik/<slug>/, relative to your components alias.
• Files several components share land in components/uibrik/_<name>/, e.g. _charts or _shared. Each install includes the ones it needs, so components keep their relative imports.
• Sample media in default props (photos, album covers) loads from uibrik.com. Pass your own through props.
• npm packages, such as motion, install automatically.

No CLI? Copy the files yourself.

1. Install the packages

Each component page lists the packages it needs under Manual installation, with a command to copy.

2. Add the cn helper

Components import cn from @/lib/utils.

npm install clsx tailwind-merge

import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

3. Add the theme tokens

Projects set up with shadcn already have these. Otherwise add them to your global CSS, after @import "tailwindcss";.

@custom-variant dark (&:is(.dark *));

:root {
  --background: #ffffff;
  --foreground: #171717;
  --muted: #f5f5f5;
  --muted-foreground: #737373;
  --border: #e5e5e5;
}

.dark {
  --background: #0a0a0a;
  --foreground: #ededed;
  --muted: #171717;
  --muted-foreground: #a3a3a3;
  --border: #262626;
}

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-border: var(--border);
}

4. Copy the files

The Source blocks on each component page show every file with the path it belongs at. Copy each one there, keeping shared files in their _<name> folders.

A few components use squircle corners. They pull in a squircle registry item: the @squircle/core and @squircle/tailwindcss packages, a CSS import and a small SquircleProvider.

The CLI installs it with the component. Then wrap your app in SquircleProvider once, in the root layout. It registers the paint worklet that draws the curve.

import { SquircleProvider } from "@/components/uibrik/squircle-provider";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <SquircleProvider>{children}</SquircleProvider>
      </body>
    </html>
  );
}

Without the CLI

npm install @squircle/core @squircle/tailwindcss

Copy squircle-provider.tsx from the squircle registry item to components/uibrik/, then add this to your global CSS:

@import "@squircle/tailwindcss";

/* Plain rounded corners until the worklet registers, and while focused.
   Keep it outside any @layer so it wins over the squircle-mask utility. */
html:not([data-squircle]) .squircle-mask,
.squircle-mask:focus-visible {
  mask-image: none;
  border-radius: var(--squircle-border-top-left-radius) var(--squircle-border-top-right-radius)
    var(--squircle-border-bottom-right-radius) var(--squircle-border-bottom-left-radius);
}

Components avoid Next.js-only APIs, so React Router, TanStack Start and Astro (with React) will likely work. They aren't officially supported or tested yet.