Instalación

Configura NachUI a mano en Next.js, Vite, TanStack Start o React Router. Instala Tailwind CSS v4, agrega los helpers y los tokens del tema, y copia los componentes que necesites.

NachUI es React y Tailwind CSS sin más, así que funciona en cualquier proyecto con React 19. El CLI todavía está en desarrollo, por eso por ahora la configuración es manual. Lleva unos minutos y se hace una sola vez.

Requisitos previos

Antes de comenzar, asegúrate de que tu proyecto tenga:

React 19+
Tailwind CSS v4
TypeScript (recomendado, el código fuente está escrito en TypeScript)
Node.js 20+

No depende de Next.js

Muchos componentes empiezan con 'use client'. Esa línea es una directiva de React, no algo propio de Next.js. Los frameworks que usan React Server Components (como el App Router de Next.js) la leen para saber qué archivos corren en el navegador. En el resto, como Vite, TanStack Start o React Router, es un string que el bundler ignora. Puedes dejarla en cualquier setup.

Los componentes solo importan de react, react-dom, motion, clsx, tailwind-merge y class-variance-authority. No usan router, ni cargador de fuentes, ni APIs de ningún framework.

Instalación paso a paso

Configura tu framework con Tailwind CSS v4

Elige tu framework. Si ya tienes un proyecto con Tailwind CSS v4 funcionando, pasa al siguiente paso y solo fíjate dónde está tu hoja de estilos principal.

Crea la app con TypeScript, Tailwind CSS, el App Router y una carpeta src/:

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

Tailwind CSS v4 ya viene conectado a través de @tailwindcss/postcss, así que no hace falta instalar nada más.

Carpeta de código: src/
Hoja de estilos principal: src/app/globals.css

Si tu proyecto existente todavía usa Tailwind CSS v3, actualízalo primero con npx @tailwindcss/upgrade.

Instala las dependencias

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

Estas librerías se usan para:

motion: animaciones y transiciones
clsx: construir clases de forma condicional
tailwind-merge: combinar clases de Tailwind sin conflictos
class-variance-authority: variantes de los componentes

Los iconos no necesitan ningún paquete extra. Los componentes traen sus propios SVG, y el set de iconos de NachUI, que es opcional, es un archivo por icono que copias igual que un componente. También sirve cualquier otra librería de iconos, porque todos los componentes los reciben por props.

Agrega el helper `cn`

Dentro de tu carpeta de código, crea el helper que usan todos los componentes para combinar clases:

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}

Agrega los tokens de movimiento

Junto a cn, crea el archivo que guarda el vocabulario de animación. Cada componente que se mueve lee sus springs y variantes de acá, así toda la librería comparte un mismo material físico y lo ajustas en un solo lugar:

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>;

Tres springs cubren todo. snappy es para hover, press y toggles, smooth para paneles, menús y collapsibles, y gentle para las superficies grandes como los diálogos. Los elementos flotantes abren desde el lado de su trigger y se van más rápido de lo que llegaron.

Agrega los helpers de estado, overlays y posicionamiento

En lib/ viven tres archivos más, y solo los necesitas cuando agregas un componente que los importa:

use-controllable-state.ts permite que un componente funcione de las dos maneras: le pasas value u open y lo controlas tú, o no los pasas y él maneja su propio estado. La mayoría de los componentes con estado lo usan.
overlay.ts tiene lo que comparten los diálogos, sheets, drawers, menús y toasts: el bloqueo del scroll, el focus trap y la pila de capas abiertas, para que Escape cierre solo la que está arriba.
floating.ts ubica popovers, tooltips, menús y selects junto a su trigger. Los pasa al otro lado cuando no hay lugar, los mantiene dentro de la pantalla y los renderiza al final de la página para que un padre con overflow: hidden no los corte.

Si un archivo que pegas importa ../lib/use-controllable-state, ../lib/overlay o ../lib/floating, copia ese helper en src/lib/, junto a cn.ts. La CLI lo hace por ti.

Agrega los tokens del tema

Reemplaza el contenido de tu hoja de estilos principal (la que anotaste en el primer paso) por lo siguiente. Si tu archivo ya tiene su propia línea @import 'tailwindcss', conserva la tuya y pega todo lo demás debajo.

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}

Este es el tema por defecto. Cada color es una variable tuya, así que puedes cambiarlo más adelante sin tocar ningún componente. En Theming se explica cómo funcionan los tokens.

Organiza las carpetas

Los componentes se importan entre sí y a los helpers con rutas relativas, como ../lib/cn o ../components/button. Si mantienes esta estructura dentro de tu carpeta de código, cada archivo que pegues funciona tal cual:

src

components

button.tsx

card.tsx

dialog.tsx

...

hybrids

lib

cn.ts

motion.ts

floating.ts

overlay.ts

use-controllable-state.ts

components/: elementos de UI y de layout
ai/: elementos de IA
hybrids/: híbridos, que combinan elementos de UI y de IA
lib/: el helper cn, los tokens de movimiento y los helpers compartidos

Si prefieres otra estructura, como components/ui/, también funciona. Solo actualiza los imports al principio de cada archivo que pegues para que apunten a tus carpetas, por ejemplo @/lib/cn en Next.js o ~/lib/cn en React Router.

Agrega tu primer componente

Abre la página del componente que quieres, por ejemplo Button.
Copia el código desde la pestaña Manual.
Pégalo en la carpeta que corresponde, en este caso src/components/button.tsx.
Si la página indica dependencias extra, instálalas.
Impórtalo y úsalo:

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

Algunos componentes usan otros. Cuando un archivo importa algo como ./label o ../components/dialog, copia ese componente también.

Modo oscuro

El tema oscuro se activa cuando el elemento <html> tiene la clase dark. Alterna esa clase de la forma en que tu app maneje el cambio de tema.

Próximos pasos

Recorre la galería de componentes para ver todo lo disponible
Lee Theming para adaptar los tokens a tu marca
Mira la página del CLI para ver hacia dónde va la instalación automática

¿Encontraste algo que mejorar?

¿Notaste un error, tipografía o detalle faltante en esta página? Ayúdanos a mejorar la documentación abriendo un issue en GitHub.

Crear un Issue

AnteriorHybrids

SiguienteTematización

No depende de Next.js

Los componentes solo importan de react, react-dom, motion, clsx, tailwind-merge y class-variance-authority. No usan router, ni cargador de fuentes, ni APIs de ningún framework.

Instalación paso a paso

Configura tu framework con Tailwind CSS v4

Elige tu framework. Si ya tienes un proyecto con Tailwind CSS v4 funcionando, pasa al siguiente paso y solo fíjate dónde está tu hoja de estilos principal.

Crea la app con TypeScript, Tailwind CSS, el App Router y una carpeta src/:

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

Tailwind CSS v4 ya viene conectado a través de @tailwindcss/postcss, así que no hace falta instalar nada más.

Carpeta de código: src/
Hoja de estilos principal: src/app/globals.css

Si tu proyecto existente todavía usa Tailwind CSS v3, actualízalo primero con npx @tailwindcss/upgrade.

Instala las dependencias

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

Estas librerías se usan para:

motion: animaciones y transiciones
clsx: construir clases de forma condicional
tailwind-merge: combinar clases de Tailwind sin conflictos
class-variance-authority: variantes de los componentes

Agrega el helper `cn`

Dentro de tu carpeta de código, crea el helper que usan todos los componentes para combinar clases:

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}

Agrega los tokens de movimiento

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>;

Agrega los helpers de estado, overlays y posicionamiento

En lib/ viven tres archivos más, y solo los necesitas cuando agregas un componente que los importa:

use-controllable-state.ts permite que un componente funcione de las dos maneras: le pasas value u open y lo controlas tú, o no los pasas y él maneja su propio estado. La mayoría de los componentes con estado lo usan.
overlay.ts tiene lo que comparten los diálogos, sheets, drawers, menús y toasts: el bloqueo del scroll, el focus trap y la pila de capas abiertas, para que Escape cierre solo la que está arriba.
floating.ts ubica popovers, tooltips, menús y selects junto a su trigger. Los pasa al otro lado cuando no hay lugar, los mantiene dentro de la pantalla y los renderiza al final de la página para que un padre con overflow: hidden no los corte.

Si un archivo que pegas importa ../lib/use-controllable-state, ../lib/overlay o ../lib/floating, copia ese helper en src/lib/, junto a cn.ts. La CLI lo hace por ti.

Agrega los tokens del tema

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}

Este es el tema por defecto. Cada color es una variable tuya, así que puedes cambiarlo más adelante sin tocar ningún componente. En Theming se explica cómo funcionan los tokens.

Organiza las carpetas

src

components

button.tsx

card.tsx

dialog.tsx

...

hybrids

lib

cn.ts

motion.ts

floating.ts

overlay.ts

use-controllable-state.ts

components/: elementos de UI y de layout
ai/: elementos de IA
hybrids/: híbridos, que combinan elementos de UI y de IA
lib/: el helper cn, los tokens de movimiento y los helpers compartidos

Agrega tu primer componente

Abre la página del componente que quieres, por ejemplo Button.

Copia el código desde la pestaña Manual.

Pégalo en la carpeta que corresponde, en este caso src/components/button.tsx.

Si la página indica dependencias extra, instálalas.

Impórtalo y úsalo:

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

Algunos componentes usan otros. Cuando un archivo importa algo como ./label o ../components/dialog, copia ese componente también.

Instalación

No depende de Next.js

Instalación paso a paso

Configura tu framework con Tailwind CSS v4

Instala las dependencias

Agrega el helper cn

Agrega los tokens de movimiento

Agrega los helpers de estado, overlays y posicionamiento

Agrega los tokens del tema

Organiza las carpetas

Agrega tu primer componente

Modo oscuro

Próximos pasos

¿Encontraste algo que mejorar?

Instalación

No depende de Next.js

Instalación paso a paso

Configura tu framework con Tailwind CSS v4

Instala las dependencias

Agrega el helper cn

Agrega los tokens de movimiento

Agrega los helpers de estado, overlays y posicionamiento

Agrega los tokens del tema

Organiza las carpetas

Agrega tu primer componente

Modo oscuro

Próximos pasos

¿Encontraste algo que mejorar?

Agrega el helper `cn`

Agrega el helper `cn`