Installation

Set up NachUI by hand in Next.js, Vite, TanStack Start or React Router. Install Tailwind CSS v4, add the shared helpers and theme tokens, then copy the components you need.

NachUI is plain React and Tailwind CSS, so it works in any React 19 project. The CLI is still in progress, so for now the setup is manual. It takes a few minutes and you only do it once.

Prerequisites

Before you begin, make sure your project has:

React 19+
Tailwind CSS v4
TypeScript (recommended, the source is written in it)
Node.js 20+

Not tied to Next.js

Many components start with 'use client'. That line is a React directive, not a Next.js feature. Frameworks that use React Server Components (like the Next.js App Router) read it to know which files run in the browser. Everywhere else, like Vite, TanStack Start or React Router, it is just a string that the bundler ignores. You can keep it in every setup.

The components only import from react, react-dom, motion, clsx, tailwind-merge and class-variance-authority. No router, no font loader and no framework APIs.

Step-by-step installation

Set up your framework with Tailwind CSS v4

Pick your framework. If you already have a project with Tailwind CSS v4 running, skip to the next step and just note where your main stylesheet is.

Create the app with TypeScript, Tailwind CSS, the App Router and a src/ folder:

1npx create-next-app@latest my-app --ts --tailwind --app --src-dir

Tailwind CSS v4 comes already wired through @tailwindcss/postcss, so there is nothing else to install.

Source folder: src/
Main stylesheet: src/app/globals.css

If your existing project still runs Tailwind CSS v3, upgrade it first with npx @tailwindcss/upgrade.

Install the dependencies

npm install motion clsx tailwind-merge class-variance-authority

These libraries are used for:

motion: animations and transitions
clsx: conditional class names
tailwind-merge: merging Tailwind classes without conflicts
class-variance-authority: component variants

Icons need no extra package. The components carry their own SVGs, and the optional NachUI icon set is one file per icon that you copy the same way as a component. Any other icon library works too, since every component takes icons through props.

Add the `cn` helper

Inside your source folder, create the helper every component uses to combine classes:

src/lib/cn.ts

1import { clsx, type ClassValue } from 'clsx';
2import { twMerge } from 'tailwind-merge';
3
4export function cn(...inputs: ClassValue[]) {
5  return twMerge(clsx(inputs));
6}

Add the motion tokens

Next to cn, create the file that holds the animation vocabulary. Every component that moves reads its springs and variants from here, so the whole library shares one physical material and you tune it in one place:

src/lib/motion.ts

1import type { Transition, Variants } from 'motion/react';
2
3const spring = (stiffness: number, damping: number, mass: number): Transition => ({
4  type: 'spring',
5  stiffness,
6  damping,
7  mass,
8});
9
10export const springs = {
11  snappy: spring(550, 22, 0.6),
12  smooth: spring(380, 24, 0.8),
13  gentle: spring(200, 20, 1),
14};
15
16export const still: Transition = { duration: 0 };
17
18export const tap = { scale: 0.94 };
19
20export const reveal: Variants = {
21  hidden: { opacity: 0 },
22  visible: { opacity: 1, transition: { duration: 0.12 } },
23  exit: { opacity: 0, transition: { duration: 0.08 } },
24};
25
26export type FloatingSide = 'top' | 'bottom' | 'left' | 'right';
27
28const ENTER_OFFSET = 10;
29const EXIT_OFFSET = 4;
30
31const towards = (side: FloatingSide, distance: number) => {
32  switch (side) {
33    case 'top':
34      return { y: distance };
35    case 'bottom':
36      return { y: -distance };
37    case 'left':
38      return { x: distance };
39    case 'right':
40      return { x: -distance };
41  }
42};
43
44const floating = (side: FloatingSide): Variants => ({
45  hidden: { opacity: 0, scale: 0.85, filter: 'blur(6px)', ...towards(side, ENTER_OFFSET) },
46  visible: {
47    opacity: 1,
48    scale: 1,
49    filter: 'blur(0px)',
50    x: 0,
51    y: 0,
52    transition: { ...springs.smooth, opacity: { duration: 0.16 }, filter: { duration: 0.2 } },
53  },
54  exit: {
55    opacity: 0,
56    scale: 0.92,
57    filter: 'blur(4px)',
58    ...towards(side, EXIT_OFFSET),
59    transition: { duration: 0.12, ease: 'easeIn' },
60  },
61});
62
63export const floatingVariants: Record<FloatingSide, Variants> = {
64  top: floating('top'),
65  bottom: floating('bottom'),
66  left: floating('left'),
67  right: floating('right'),
68};
69
70export const floatingOrigin: Record<FloatingSide, string> = {
71  top: 'origin-bottom',
72  bottom: 'origin-top',
73  left: 'origin-right',
74  right: 'origin-left',
75};
76
77export const backdrop: Variants = {
78  hidden: { opacity: 0 },
79  visible: { opacity: 1, transition: { duration: 0.25 } },
80  exit: { opacity: 0, transition: { duration: 0.15 } },
81};
82
83export const surface: Variants = {
84  hidden: { opacity: 0, scale: 0.85, y: 16, filter: 'blur(10px)' },
85  visible: {
86    opacity: 1,
87    scale: 1,
88    y: 0,
89    filter: 'blur(0px)',
90    transition: { ...springs.gentle, opacity: { duration: 0.18 }, filter: { duration: 0.25 } },
91  },
92  exit: {
93    opacity: 0,
94    scale: 0.9,
95    y: 12,
96    filter: 'blur(8px)',
97    transition: { duration: 0.16, ease: 'easeIn' },
98  },
99};
100
101const offscreen = (side: FloatingSide, amount: string) => {
102  switch (side) {
103    case 'top':
104      return { y: `-${amount}` };
105    case 'bottom':
106      return { y: amount };
107    case 'left':
108      return { x: `-${amount}` };
109    case 'right':
110      return { x: amount };
111  }
112};
113
114const slide = (side: FloatingSide): Variants => ({
115  hidden: offscreen(side, '100%'),
116  visible: { x: 0, y: 0, transition: springs.gentle },
117  exit: { ...offscreen(side, '110%'), transition: { duration: 0.2, ease: 'easeIn' } },
118});
119
120export const slideVariants: Record<FloatingSide, Variants> = {
121  top: slide('top'),
122  bottom: slide('bottom'),
123  left: slide('left'),
124  right: slide('right'),
125};
126
127export const collapse: Variants = {
128  closed: {
129    height: 0,
130    opacity: 0,
131    transition: { height: springs.snappy, opacity: { duration: 0.1 } },
132  },
133  open: {
134    height: 'auto',
135    opacity: 1,
136    transition: { height: springs.smooth, opacity: { duration: 0.2, delay: 0.04 } },
137  },
138};
139
140export const collapseInner: Variants = {
141  closed: { y: -10, scale: 0.97, filter: 'blur(4px)', transition: { duration: 0.12 } },
142  open: { y: 0, scale: 1, filter: 'blur(0px)', transition: springs.smooth },
143};
144
145export const pop: Variants = {
146  hidden: { opacity: 0, scale: 0.6 },
147  visible: { opacity: 1, scale: 1, transition: { ...springs.snappy, opacity: { duration: 0.1 } } },
148  exit: { opacity: 0, scale: 0.8, transition: { duration: 0.1, ease: 'easeIn' } },
149};
150
151export const cascade = {
152  list: {
153    hidden: {},
154    visible: { transition: { staggerChildren: 0.035, delayChildren: 0.02 } },
155  },
156  item: {
157    hidden: { opacity: 0, y: 8, scale: 0.9, filter: 'blur(4px)' },
158    visible: { opacity: 1, y: 0, scale: 1, filter: 'blur(0px)', transition: springs.snappy },
159  },
160} satisfies Record<string, Variants>;

Three springs cover everything. snappy is for hover, press and toggles, smooth for panels, menus and collapsibles, and gentle for the big surfaces like dialogs. Floating elements open from the side of their trigger and leave faster than they arrived.

Add the state, overlay and floating helpers

Three more files live in lib/, and you only need them once you add a component that imports them:

use-controllable-state.ts lets a component work both ways: you pass value or open and control it, or you leave them out and it keeps its own state. Most stateful components use it.
overlay.ts holds what dialogs, sheets, drawers, menus and toasts share: the scroll lock, the focus trap and the stack of open layers, so Escape only closes the one on top.
floating.ts places popovers, tooltips, menus and selects next to their trigger. It flips them to the other side when there is no room, keeps them inside the screen and renders them at the end of the page so a parent with overflow: hidden can't cut them off.

If a file you paste imports ../lib/use-controllable-state, ../lib/overlay or ../lib/floating, copy that helper into src/lib/ next to cn.ts. The CLI does this for you.

Add the theme tokens

Replace the contents of your main stylesheet (the one you noted in the first step) with the following. If your file already has its own @import 'tailwindcss' line, keep yours and paste everything below it.

1@import 'tailwindcss';
2@custom-variant dark (&:where(.dark, .dark *));
3
4:root {
5  --background: oklch(99.1% 0.003 85);
6  --foreground: oklch(14.5% 0.004 75);
7
8  --card: oklch(100% 0 0);
9  --card-foreground: oklch(14.5% 0.004 75);
10
11  --popover: oklch(100% 0 0);
12  --popover-foreground: oklch(14.5% 0.004 75);
13
14  --surface-muted: oklch(96.5% 0.0045 85);
15
16  --primary: oklch(20.5% 0.005 75);
17  --primary-foreground: oklch(98.5% 0.002 85);
18  --secondary: oklch(96% 0.0045 85);
19  --secondary-foreground: oklch(20.5% 0.005 75);
20  --accent: oklch(96.8% 0.0045 85);
21  --accent-foreground: oklch(20.5% 0.005 75);
22
23  --muted: oklch(94.2% 0.005 85);
24  --muted-foreground: oklch(52% 0.0065 75);
25  --muted-strong: oklch(37% 0.006 75);
26
27  --inverse: oklch(14.5% 0.004 75);
28  --inverse-foreground: oklch(98.5% 0.002 85);
29
30  --border: oklch(91.5% 0.0055 85);
31  --border-interactive: oklch(65% 0.0065 75);
32  --input: oklch(87% 0.0065 85);
33  --ring: oklch(65% 0.0065 75);
34  --rule: oklch(91.5% 0.0055 85);
35
36  --radius: 0.75rem;
37
38  --destructive: oklch(53% 0.16 27.3);
39  --destructive-foreground: oklch(98.5% 0.002 85);
40  --destructive-text: oklch(48% 0.15 27.3);
41  --destructive-surface: oklch(96.5% 0.016 27.3);
42  --destructive-border: oklch(87% 0.068 27.3);
43
44  --warning: oklch(53% 0.108 90.4);
45  --warning-foreground: oklch(98.5% 0.002 85);
46  --warning-text: oklch(48% 0.098 90.4);
47  --warning-surface: oklch(96.5% 0.028 90.4);
48  --warning-border: oklch(87% 0.07 90.4);
49
50  --success: oklch(53% 0.156 135.6);
51  --success-foreground: oklch(98.5% 0.002 85);
52  --success-text: oklch(48% 0.14 135.6);
53  --success-surface: oklch(96.5% 0.028 135.6);
54  --success-border: oklch(87% 0.07 135.6);
55
56  --info: oklch(53% 0.16 260.8);
57  --info-foreground: oklch(98.5% 0.002 85);
58  --info-text: oklch(48% 0.15 260.8);
59  --info-surface: oklch(96.5% 0.016 260.8);
60  --info-border: oklch(87% 0.06 260.8);
61
62  --overlay: oklch(14.5% 0.004 75 / 0.5);
63
64  --elevation-sm: 0 1px 2px oklch(25% 0.01 75 / 0.07);
65  --elevation-md: 0 4px 12px -4px oklch(25% 0.01 75 / 0.11);
66  --elevation-lg: 0 12px 32px -12px oklch(25% 0.01 75 / 0.17);
67
68  --code: oklch(99.1% 0.003 85);
69}
70
71.dark {
72  --background: oklch(14.5% 0 0);
73  --foreground: oklch(98.5% 0 0);
74
75  --card: oklch(21.8% 0 0);
76  --card-foreground: oklch(98.5% 0 0);
77
78  --popover: oklch(23.9% 0 0);
79  --popover-foreground: oklch(98.5% 0 0);
80
81  --surface-muted: oklch(18.2% 0 0);
82
83  --primary: oklch(98.5% 0 0);
84  --primary-foreground: oklch(14.5% 0 0);
85  --secondary: oklch(26.9% 0 0);
86  --secondary-foreground: oklch(98.5% 0 0);
87  --accent: oklch(26.9% 0 0);
88  --accent-foreground: oklch(98.5% 0 0);
89
90  --muted: oklch(26.9% 0 0);
91  --muted-foreground: oklch(71.5% 0 0);
92  --muted-strong: oklch(87% 0 0);
93
94  --inverse: oklch(98.5% 0 0);
95  --inverse-foreground: oklch(14.5% 0 0);
96
97  --border: oklch(26.9% 0 0);
98  --border-interactive: oklch(51% 0 0);
99  --input: oklch(34.8% 0 0);
100  --ring: oklch(98.5% 0 0);
101  --rule: oklch(26.9% 0 0);
102
103  --destructive: oklch(71.1% 0.166 22.2);
104  --destructive-foreground: oklch(14.5% 0 0);
105  --destructive-text: oklch(71.1% 0.166 22.2);
106  --destructive-surface: oklch(20.6% 0.018 18.8);
107  --destructive-border: oklch(27.5% 0.042 20.1);
108
109  --warning: oklch(80% 0.111 78.2);
110  --warning-foreground: oklch(14.5% 0 0);
111  --warning-text: oklch(80% 0.111 78.2);
112  --warning-surface: oklch(22.1% 0.017 79.3);
113  --warning-border: oklch(31.5% 0.035 83.9);
114
115  --success: oklch(76.9% 0.118 148.9);
116  --success-foreground: oklch(14.5% 0 0);
117  --success-text: oklch(76.9% 0.118 148.9);
118  --success-surface: oklch(22.4% 0.025 153.7);
119  --success-border: oklch(32% 0.049 151.2);
120
121  --info: oklch(87% 0 0);
122  --info-foreground: oklch(14.5% 0 0);
123  --info-text: oklch(87% 0 0);
124  --info-surface: oklch(21.8% 0 0);
125  --info-border: oklch(32.1% 0 0);
126
127  --overlay: oklch(0% 0 0 / 0.72);
128
129  --elevation-sm: 0 1px 2px oklch(0% 0 0 / 0.5);
130  --elevation-md: 0 8px 24px -8px oklch(0% 0 0 / 0.65);
131  --elevation-lg: 0 10px 40px -15px oklch(0% 0 0 / 0.8);
132
133  --code: oklch(18.2% 0 0);
134}
135
136@theme inline {
137  --color-background: var(--background);
138  --color-foreground: var(--foreground);
139  --color-card: var(--card);
140  --color-card-foreground: var(--card-foreground);
141  --color-popover: var(--popover);
142  --color-popover-foreground: var(--popover-foreground);
143  --color-surface-muted: var(--surface-muted);
144
145  --color-primary: var(--primary);
146  --color-primary-foreground: var(--primary-foreground);
147  --color-secondary: var(--secondary);
148  --color-secondary-foreground: var(--secondary-foreground);
149  --color-accent: var(--accent);
150  --color-accent-foreground: var(--accent-foreground);
151  --color-muted: var(--muted);
152  --color-muted-foreground: var(--muted-foreground);
153  --color-muted-strong: var(--muted-strong);
154  --color-inverse: var(--inverse);
155  --color-inverse-foreground: var(--inverse-foreground);
156
157  --color-destructive: var(--destructive);
158  --color-destructive-foreground: var(--destructive-foreground);
159  --color-destructive-text: var(--destructive-text);
160  --color-destructive-surface: var(--destructive-surface);
161  --color-destructive-border: var(--destructive-border);
162
163  --color-warning: var(--warning);
164  --color-warning-foreground: var(--warning-foreground);
165  --color-warning-text: var(--warning-text);
166  --color-warning-surface: var(--warning-surface);
167  --color-warning-border: var(--warning-border);
168
169  --color-success: var(--success);
170  --color-success-foreground: var(--success-foreground);
171  --color-success-text: var(--success-text);
172  --color-success-surface: var(--success-surface);
173  --color-success-border: var(--success-border);
174
175  --color-info: var(--info);
176  --color-info-foreground: var(--info-foreground);
177  --color-info-text: var(--info-text);
178  --color-info-surface: var(--info-surface);
179  --color-info-border: var(--info-border);
180
181  --color-border: var(--border);
182  --color-border-interactive: var(--border-interactive);
183  --color-input: var(--input);
184  --color-ring: var(--ring);
185  --color-rule: var(--rule);
186  --color-overlay: var(--overlay);
187  --color-code: var(--code);
188
189  --radius-sm: calc(var(--radius) * 0.5);
190  --radius-md: var(--radius);
191  --radius-lg: calc(var(--radius) * 1.33);
192  --radius-xl: calc(var(--radius) * 1.66);
193  --radius-2xl: calc(var(--radius) * 2);
194
195  --shadow-sm: var(--elevation-sm);
196  --shadow-md: var(--elevation-md);
197  --shadow-lg: var(--elevation-lg);
198}
199
200@utility hide-scrollbar {
201  -ms-overflow-style: none;
202  scrollbar-width: none;
203
204  &::-webkit-scrollbar {
205    display: none;
206  }
207}
208
209@layer base {
210  * {
211    @apply border-border;
212  }
213
214  body {
215    @apply bg-background text-foreground antialiased;
216  }
217}

This is the default theme. Every color is a variable you own, so you can change it later without touching a component. Theming explains how the tokens work.

Organize the folders

Components import each other and the helpers through relative paths, like ../lib/cn or ../components/button. If you keep this layout inside your source folder, every file you paste works as-is:

src

components

button.tsx

card.tsx

dialog.tsx

...

hybrids

lib

cn.ts

motion.ts

floating.ts

overlay.ts

use-controllable-state.ts

components/: UI and layout elements
ai/: AI elements
hybrids/: hybrids, which combine UI and AI elements
lib/: the cn helper, the motion tokens and the shared helpers

If you prefer another layout, like components/ui/, that works too. Just update the imports at the top of each file you paste to point at your folders, for example @/lib/cn in Next.js or ~/lib/cn in React Router.

Add your first component

Open the page of the component you want, for example Button.
Copy the source from the Manual tab.
Paste it into the matching folder, in this case src/components/button.tsx.
If the page lists extra dependencies, install them.
Import it and use it:

1import { Button } from './components/button';
2
3export function App() {
4  return <Button>Deploy</Button>;
5}

Some components use others. When a file imports something like ./label or ../components/dialog, copy that component too.

Dark mode

The dark theme turns on when the dark class is on the <html> element. Toggle that class however your app handles theme switching.

Next steps

Browse the component gallery to see everything available
Read Theming to adapt the tokens to your brand
Follow the CLI page to see where automated installs are heading

Found something to improve?

Notice a bug, typo, or missing detail on this page? Help us make the documentation better by opening a GitHub issue.

Create an Issue

PreviousHybrids

NextTheming

Not tied to Next.js

The components only import from react, react-dom, motion, clsx, tailwind-merge and class-variance-authority. No router, no font loader and no framework APIs.

Step-by-step installation

Set up your framework with Tailwind CSS v4

Pick your framework. If you already have a project with Tailwind CSS v4 running, skip to the next step and just note where your main stylesheet is.

Create the app with TypeScript, Tailwind CSS, the App Router and a src/ folder:

1npx create-next-app@latest my-app --ts --tailwind --app --src-dir

Tailwind CSS v4 comes already wired through @tailwindcss/postcss, so there is nothing else to install.

Source folder: src/
Main stylesheet: src/app/globals.css

If your existing project still runs Tailwind CSS v3, upgrade it first with npx @tailwindcss/upgrade.

Install the dependencies

npm install motion clsx tailwind-merge class-variance-authority

These libraries are used for:

motion: animations and transitions
clsx: conditional class names
tailwind-merge: merging Tailwind classes without conflicts
class-variance-authority: component variants

Add the `cn` helper

Inside your source folder, create the helper every component uses to combine classes:

src/lib/cn.ts

1import { clsx, type ClassValue } from 'clsx';
2import { twMerge } from 'tailwind-merge';
3
4export function cn(...inputs: ClassValue[]) {
5  return twMerge(clsx(inputs));
6}

Add the motion tokens

src/lib/motion.ts

1import type { Transition, Variants } from 'motion/react';
2
3const spring = (stiffness: number, damping: number, mass: number): Transition => ({
4  type: 'spring',
5  stiffness,
6  damping,
7  mass,
8});
9
10export const springs = {
11  snappy: spring(550, 22, 0.6),
12  smooth: spring(380, 24, 0.8),
13  gentle: spring(200, 20, 1),
14};
15
16export const still: Transition = { duration: 0 };
17
18export const tap = { scale: 0.94 };
19
20export const reveal: Variants = {
21  hidden: { opacity: 0 },
22  visible: { opacity: 1, transition: { duration: 0.12 } },
23  exit: { opacity: 0, transition: { duration: 0.08 } },
24};
25
26export type FloatingSide = 'top' | 'bottom' | 'left' | 'right';
27
28const ENTER_OFFSET = 10;
29const EXIT_OFFSET = 4;
30
31const towards = (side: FloatingSide, distance: number) => {
32  switch (side) {
33    case 'top':
34      return { y: distance };
35    case 'bottom':
36      return { y: -distance };
37    case 'left':
38      return { x: distance };
39    case 'right':
40      return { x: -distance };
41  }
42};
43
44const floating = (side: FloatingSide): Variants => ({
45  hidden: { opacity: 0, scale: 0.85, filter: 'blur(6px)', ...towards(side, ENTER_OFFSET) },
46  visible: {
47    opacity: 1,
48    scale: 1,
49    filter: 'blur(0px)',
50    x: 0,
51    y: 0,
52    transition: { ...springs.smooth, opacity: { duration: 0.16 }, filter: { duration: 0.2 } },
53  },
54  exit: {
55    opacity: 0,
56    scale: 0.92,
57    filter: 'blur(4px)',
58    ...towards(side, EXIT_OFFSET),
59    transition: { duration: 0.12, ease: 'easeIn' },
60  },
61});
62
63export const floatingVariants: Record<FloatingSide, Variants> = {
64  top: floating('top'),
65  bottom: floating('bottom'),
66  left: floating('left'),
67  right: floating('right'),
68};
69
70export const floatingOrigin: Record<FloatingSide, string> = {
71  top: 'origin-bottom',
72  bottom: 'origin-top',
73  left: 'origin-right',
74  right: 'origin-left',
75};
76
77export const backdrop: Variants = {
78  hidden: { opacity: 0 },
79  visible: { opacity: 1, transition: { duration: 0.25 } },
80  exit: { opacity: 0, transition: { duration: 0.15 } },
81};
82
83export const surface: Variants = {
84  hidden: { opacity: 0, scale: 0.85, y: 16, filter: 'blur(10px)' },
85  visible: {
86    opacity: 1,
87    scale: 1,
88    y: 0,
89    filter: 'blur(0px)',
90    transition: { ...springs.gentle, opacity: { duration: 0.18 }, filter: { duration: 0.25 } },
91  },
92  exit: {
93    opacity: 0,
94    scale: 0.9,
95    y: 12,
96    filter: 'blur(8px)',
97    transition: { duration: 0.16, ease: 'easeIn' },
98  },
99};
100
101const offscreen = (side: FloatingSide, amount: string) => {
102  switch (side) {
103    case 'top':
104      return { y: `-${amount}` };
105    case 'bottom':
106      return { y: amount };
107    case 'left':
108      return { x: `-${amount}` };
109    case 'right':
110      return { x: amount };
111  }
112};
113
114const slide = (side: FloatingSide): Variants => ({
115  hidden: offscreen(side, '100%'),
116  visible: { x: 0, y: 0, transition: springs.gentle },
117  exit: { ...offscreen(side, '110%'), transition: { duration: 0.2, ease: 'easeIn' } },
118});
119
120export const slideVariants: Record<FloatingSide, Variants> = {
121  top: slide('top'),
122  bottom: slide('bottom'),
123  left: slide('left'),
124  right: slide('right'),
125};
126
127export const collapse: Variants = {
128  closed: {
129    height: 0,
130    opacity: 0,
131    transition: { height: springs.snappy, opacity: { duration: 0.1 } },
132  },
133  open: {
134    height: 'auto',
135    opacity: 1,
136    transition: { height: springs.smooth, opacity: { duration: 0.2, delay: 0.04 } },
137  },
138};
139
140export const collapseInner: Variants = {
141  closed: { y: -10, scale: 0.97, filter: 'blur(4px)', transition: { duration: 0.12 } },
142  open: { y: 0, scale: 1, filter: 'blur(0px)', transition: springs.smooth },
143};
144
145export const pop: Variants = {
146  hidden: { opacity: 0, scale: 0.6 },
147  visible: { opacity: 1, scale: 1, transition: { ...springs.snappy, opacity: { duration: 0.1 } } },
148  exit: { opacity: 0, scale: 0.8, transition: { duration: 0.1, ease: 'easeIn' } },
149};
150
151export const cascade = {
152  list: {
153    hidden: {},
154    visible: { transition: { staggerChildren: 0.035, delayChildren: 0.02 } },
155  },
156  item: {
157    hidden: { opacity: 0, y: 8, scale: 0.9, filter: 'blur(4px)' },
158    visible: { opacity: 1, y: 0, scale: 1, filter: 'blur(0px)', transition: springs.snappy },
159  },
160} satisfies Record<string, Variants>;

Add the state, overlay and floating helpers

Three more files live in lib/, and you only need them once you add a component that imports them:

use-controllable-state.ts lets a component work both ways: you pass value or open and control it, or you leave them out and it keeps its own state. Most stateful components use it.
overlay.ts holds what dialogs, sheets, drawers, menus and toasts share: the scroll lock, the focus trap and the stack of open layers, so Escape only closes the one on top.
floating.ts places popovers, tooltips, menus and selects next to their trigger. It flips them to the other side when there is no room, keeps them inside the screen and renders them at the end of the page so a parent with overflow: hidden can't cut them off.

If a file you paste imports ../lib/use-controllable-state, ../lib/overlay or ../lib/floating, copy that helper into src/lib/ next to cn.ts. The CLI does this for you.

Add the theme tokens

1@import 'tailwindcss';
2@custom-variant dark (&:where(.dark, .dark *));
3
4:root {
5  --background: oklch(99.1% 0.003 85);
6  --foreground: oklch(14.5% 0.004 75);
7
8  --card: oklch(100% 0 0);
9  --card-foreground: oklch(14.5% 0.004 75);
10
11  --popover: oklch(100% 0 0);
12  --popover-foreground: oklch(14.5% 0.004 75);
13
14  --surface-muted: oklch(96.5% 0.0045 85);
15
16  --primary: oklch(20.5% 0.005 75);
17  --primary-foreground: oklch(98.5% 0.002 85);
18  --secondary: oklch(96% 0.0045 85);
19  --secondary-foreground: oklch(20.5% 0.005 75);
20  --accent: oklch(96.8% 0.0045 85);
21  --accent-foreground: oklch(20.5% 0.005 75);
22
23  --muted: oklch(94.2% 0.005 85);
24  --muted-foreground: oklch(52% 0.0065 75);
25  --muted-strong: oklch(37% 0.006 75);
26
27  --inverse: oklch(14.5% 0.004 75);
28  --inverse-foreground: oklch(98.5% 0.002 85);
29
30  --border: oklch(91.5% 0.0055 85);
31  --border-interactive: oklch(65% 0.0065 75);
32  --input: oklch(87% 0.0065 85);
33  --ring: oklch(65% 0.0065 75);
34  --rule: oklch(91.5% 0.0055 85);
35
36  --radius: 0.75rem;
37
38  --destructive: oklch(53% 0.16 27.3);
39  --destructive-foreground: oklch(98.5% 0.002 85);
40  --destructive-text: oklch(48% 0.15 27.3);
41  --destructive-surface: oklch(96.5% 0.016 27.3);
42  --destructive-border: oklch(87% 0.068 27.3);
43
44  --warning: oklch(53% 0.108 90.4);
45  --warning-foreground: oklch(98.5% 0.002 85);
46  --warning-text: oklch(48% 0.098 90.4);
47  --warning-surface: oklch(96.5% 0.028 90.4);
48  --warning-border: oklch(87% 0.07 90.4);
49
50  --success: oklch(53% 0.156 135.6);
51  --success-foreground: oklch(98.5% 0.002 85);
52  --success-text: oklch(48% 0.14 135.6);
53  --success-surface: oklch(96.5% 0.028 135.6);
54  --success-border: oklch(87% 0.07 135.6);
55
56  --info: oklch(53% 0.16 260.8);
57  --info-foreground: oklch(98.5% 0.002 85);
58  --info-text: oklch(48% 0.15 260.8);
59  --info-surface: oklch(96.5% 0.016 260.8);
60  --info-border: oklch(87% 0.06 260.8);
61
62  --overlay: oklch(14.5% 0.004 75 / 0.5);
63
64  --elevation-sm: 0 1px 2px oklch(25% 0.01 75 / 0.07);
65  --elevation-md: 0 4px 12px -4px oklch(25% 0.01 75 / 0.11);
66  --elevation-lg: 0 12px 32px -12px oklch(25% 0.01 75 / 0.17);
67
68  --code: oklch(99.1% 0.003 85);
69}
70
71.dark {
72  --background: oklch(14.5% 0 0);
73  --foreground: oklch(98.5% 0 0);
74
75  --card: oklch(21.8% 0 0);
76  --card-foreground: oklch(98.5% 0 0);
77
78  --popover: oklch(23.9% 0 0);
79  --popover-foreground: oklch(98.5% 0 0);
80
81  --surface-muted: oklch(18.2% 0 0);
82
83  --primary: oklch(98.5% 0 0);
84  --primary-foreground: oklch(14.5% 0 0);
85  --secondary: oklch(26.9% 0 0);
86  --secondary-foreground: oklch(98.5% 0 0);
87  --accent: oklch(26.9% 0 0);
88  --accent-foreground: oklch(98.5% 0 0);
89
90  --muted: oklch(26.9% 0 0);
91  --muted-foreground: oklch(71.5% 0 0);
92  --muted-strong: oklch(87% 0 0);
93
94  --inverse: oklch(98.5% 0 0);
95  --inverse-foreground: oklch(14.5% 0 0);
96
97  --border: oklch(26.9% 0 0);
98  --border-interactive: oklch(51% 0 0);
99  --input: oklch(34.8% 0 0);
100  --ring: oklch(98.5% 0 0);
101  --rule: oklch(26.9% 0 0);
102
103  --destructive: oklch(71.1% 0.166 22.2);
104  --destructive-foreground: oklch(14.5% 0 0);
105  --destructive-text: oklch(71.1% 0.166 22.2);
106  --destructive-surface: oklch(20.6% 0.018 18.8);
107  --destructive-border: oklch(27.5% 0.042 20.1);
108
109  --warning: oklch(80% 0.111 78.2);
110  --warning-foreground: oklch(14.5% 0 0);
111  --warning-text: oklch(80% 0.111 78.2);
112  --warning-surface: oklch(22.1% 0.017 79.3);
113  --warning-border: oklch(31.5% 0.035 83.9);
114
115  --success: oklch(76.9% 0.118 148.9);
116  --success-foreground: oklch(14.5% 0 0);
117  --success-text: oklch(76.9% 0.118 148.9);
118  --success-surface: oklch(22.4% 0.025 153.7);
119  --success-border: oklch(32% 0.049 151.2);
120
121  --info: oklch(87% 0 0);
122  --info-foreground: oklch(14.5% 0 0);
123  --info-text: oklch(87% 0 0);
124  --info-surface: oklch(21.8% 0 0);
125  --info-border: oklch(32.1% 0 0);
126
127  --overlay: oklch(0% 0 0 / 0.72);
128
129  --elevation-sm: 0 1px 2px oklch(0% 0 0 / 0.5);
130  --elevation-md: 0 8px 24px -8px oklch(0% 0 0 / 0.65);
131  --elevation-lg: 0 10px 40px -15px oklch(0% 0 0 / 0.8);
132
133  --code: oklch(18.2% 0 0);
134}
135
136@theme inline {
137  --color-background: var(--background);
138  --color-foreground: var(--foreground);
139  --color-card: var(--card);
140  --color-card-foreground: var(--card-foreground);
141  --color-popover: var(--popover);
142  --color-popover-foreground: var(--popover-foreground);
143  --color-surface-muted: var(--surface-muted);
144
145  --color-primary: var(--primary);
146  --color-primary-foreground: var(--primary-foreground);
147  --color-secondary: var(--secondary);
148  --color-secondary-foreground: var(--secondary-foreground);
149  --color-accent: var(--accent);
150  --color-accent-foreground: var(--accent-foreground);
151  --color-muted: var(--muted);
152  --color-muted-foreground: var(--muted-foreground);
153  --color-muted-strong: var(--muted-strong);
154  --color-inverse: var(--inverse);
155  --color-inverse-foreground: var(--inverse-foreground);
156
157  --color-destructive: var(--destructive);
158  --color-destructive-foreground: var(--destructive-foreground);
159  --color-destructive-text: var(--destructive-text);
160  --color-destructive-surface: var(--destructive-surface);
161  --color-destructive-border: var(--destructive-border);
162
163  --color-warning: var(--warning);
164  --color-warning-foreground: var(--warning-foreground);
165  --color-warning-text: var(--warning-text);
166  --color-warning-surface: var(--warning-surface);
167  --color-warning-border: var(--warning-border);
168
169  --color-success: var(--success);
170  --color-success-foreground: var(--success-foreground);
171  --color-success-text: var(--success-text);
172  --color-success-surface: var(--success-surface);
173  --color-success-border: var(--success-border);
174
175  --color-info: var(--info);
176  --color-info-foreground: var(--info-foreground);
177  --color-info-text: var(--info-text);
178  --color-info-surface: var(--info-surface);
179  --color-info-border: var(--info-border);
180
181  --color-border: var(--border);
182  --color-border-interactive: var(--border-interactive);
183  --color-input: var(--input);
184  --color-ring: var(--ring);
185  --color-rule: var(--rule);
186  --color-overlay: var(--overlay);
187  --color-code: var(--code);
188
189  --radius-sm: calc(var(--radius) * 0.5);
190  --radius-md: var(--radius);
191  --radius-lg: calc(var(--radius) * 1.33);
192  --radius-xl: calc(var(--radius) * 1.66);
193  --radius-2xl: calc(var(--radius) * 2);
194
195  --shadow-sm: var(--elevation-sm);
196  --shadow-md: var(--elevation-md);
197  --shadow-lg: var(--elevation-lg);
198}
199
200@utility hide-scrollbar {
201  -ms-overflow-style: none;
202  scrollbar-width: none;
203
204  &::-webkit-scrollbar {
205    display: none;
206  }
207}
208
209@layer base {
210  * {
211    @apply border-border;
212  }
213
214  body {
215    @apply bg-background text-foreground antialiased;
216  }
217}

This is the default theme. Every color is a variable you own, so you can change it later without touching a component. Theming explains how the tokens work.

Organize the folders

Components import each other and the helpers through relative paths, like ../lib/cn or ../components/button. If you keep this layout inside your source folder, every file you paste works as-is:

src

components

button.tsx

card.tsx

dialog.tsx

...

hybrids

lib

cn.ts

motion.ts

floating.ts

overlay.ts

use-controllable-state.ts

components/: UI and layout elements
ai/: AI elements
hybrids/: hybrids, which combine UI and AI elements
lib/: the cn helper, the motion tokens and the shared helpers

Add your first component

Open the page of the component you want, for example Button.

Copy the source from the Manual tab.

Paste it into the matching folder, in this case src/components/button.tsx.

If the page lists extra dependencies, install them.

Import it and use it:

1import { Button } from './components/button';
2
3export function App() {
4  return <Button>Deploy</Button>;
5}

Some components use others. When a file imports something like ./label or ../components/dialog, copy that component too.

Installation

Not tied to Next.js

Step-by-step installation

Set up your framework with Tailwind CSS v4

Install the dependencies

Add the cn helper

Add the motion tokens

Add the state, overlay and floating helpers

Add the theme tokens

Organize the folders

Add your first component

Dark mode

Next steps

Found something to improve?

Installation

Not tied to Next.js

Step-by-step installation

Set up your framework with Tailwind CSS v4

Install the dependencies

Add the cn helper

Add the motion tokens

Add the state, overlay and floating helpers

Add the theme tokens

Organize the folders

Add your first component

Dark mode

Next steps

Found something to improve?

Add the `cn` helper

Add the `cn` helper