Get started
Install uilab-core, connect the UI Lab registry and add components and blocks to your project.
UI Lab ships in two parts:
| Part | What it is | How you get it |
|---|---|---|
| Components | Primitives such as Button, Dialog and Table, built on Base UI | The uilab-core npm package. Import them, don't copy them. |
| Blocks | Higher-level pieces such as Data Table, Data Grid and Tour | The UI Lab shadcn registry. The CLI copies the source into your project so you can change it. |
Blocks are built from uilab-core components, so set up the package first, then the registry.
Starting a new project
The quickest start is a template that already has everything below set up:
npx gitpick https://github.com/ailab-core/uilab/tree/main/examples/template-vite-tanstack-router [your_project_name]
cd [your_project_name]
npm install
npm run devOur projects use TanStack Router or TanStack Start. Some blocks, such as Data Table, need TanStack Router.
Manual setup
Your project needs React 19, TypeScript, Tailwind CSS v4 and an @/* path alias pointing at your source folder.
Install uilab-core
npm install uilab-core cn tw-animate-css lucide-reactImport the styles
Add the styles to your main CSS file, after Tailwind:
@import "tailwindcss";
@import "tw-animate-css";
@import "uilab-core/styles.css";
@import "uilab-core/default.css";
/* Make sure to add this too for themes */
@custom-variant dark (&:is(.dark *));default.css is the theme. See Styling to change the brand color, radius and fonts.
Use a component
import { Button } from "uilab-core"
export function Save() {
return <Button>Save</Button>
}That's all you need for components. Continue below to use blocks.
Registry setup
Blocks are installed with the shadcn CLI from the UI Lab registry at https://ui.ailab.mn/r.
Add a components.json
The CLI reads components.json at your project root to know where to put files. Create it, or add the registries entry if you already have one:
{
"$schema": "https://ui.shadcn.com/schema.json",
"style": "base-mira",
"rsc": false,
"tsx": true,
"tailwind": {
"config": "",
"css": "src/styles.css",
"baseColor": "neutral",
"cssVariables": true
},
"iconLibrary": "lucide",
"aliases": {
"components": "@/components",
"ui": "@/components/ui",
"lib": "@/lib",
"hooks": "@/hooks",
"utils": "@/lib/utils"
},
"registries": {
"@uilab-core": "https://ui.ailab.mn/r/{name}.json"
}
}Point tailwind.css at the CSS file from the manual setup. The aliases decide where block files go and how their imports are rewritten.
Add a block
npx shadcn@latest add @uilab-core/data-tableThe CLI copies the block's files into your project, installs its npm dependencies and adds any blocks it depends on. Data Table, for example, lands in components/data-table/, hooks/ and lib/:
import { DataTable } from "@/components/data-table/data-table"
import { useDataTable } from "@/hooks/use-data-table"You can add several at once: npx shadcn@latest add @uilab-core/data-grid @uilab-core/tour.
Available items
| Name | Install |
|---|---|
| Data Table | @uilab-core/data-table |
| Data Grid | @uilab-core/data-grid |
| Tour | @uilab-core/tour |
| Confirmation Dialog | @uilab-core/confirmation |
| Sonner | @uilab-core/sonner |
| Form Dialog, Form Sheet | @uilab-core/form-dialog, @uilab-core/form-sheet |
| Currency Input | @uilab-core/currency-input |
Each block page lists any provider or setup it needs. For example, Confirmation needs ConfirmationProvider around your app.
Updating a block
Block files are yours after you install them. To pull the latest version, preview what would change, then overwrite:
npx shadcn@latest add @uilab-core/data-table --dry-run
npx shadcn@latest add @uilab-core/data-table --overwrite--overwrite replaces your local copy, so commit or back up your changes first.
TypeScript support
All components are written in TypeScript and include complete type definitions:
import { Button, type ButtonProps } from "uilab-core"
function MyButton(props: ButtonProps) {
return <Button {...props} />
}Framework compatibility
uilab-core and the blocks are client components. They work in any React app, including TanStack Router and TanStack Start.
React Server Components are not supported yet. Calling cn from a server component logs an error that it must run in a client component.