Configuração do shadcn/ui
Instale, configure e personalize o tema do shadcn/ui - copie e cole componentes construídos sobre Radix UI e Tailwind CSS.
//
Busque em todas as páginas da documentação
Instale, configure e personalize o tema do shadcn/ui - copie e cole componentes construídos sobre Radix UI e Tailwind CSS.
🤖 Read the SystemsArchitect.io Blog for over 100+ cloud architecture articles 🔥
Cartão de receita de referência rápida - pronto para copiar e colar.
# Inicialize o shadcn no seu projeto
npx shadcn@latest init
# Adicione componentes específicos
npx shadcn@latest add button
npx shadcn@latest add input
npx shadcn@latest add card
# Adicione múltiplos de uma vez
npx shadcn@latest add button input card dialog form// components.json - gerado pelo init
{
"$schema": "https://ui.shadcn.com/schema.json",
"style": "new-york",
"tailwind": {
"config": "",
"css": "app/globals.css",
"baseColor": "zinc",
"cssVariables": true
},
"aliases": {
"components": "@/components",
"utils": "@/lib/utils"
}
}// lib/utils.ts - a utilidade cn
import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";
export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs));
}Quando usar isso: No início de qualquer projeto Next.js ou React onde você deseja componentes de UI polidos e acessíveis com controle total sobre o código-fonte.
/* app/globals.css - tema shadcn com variáveis CSS */
@import "tailwindcss";
@theme inline {
--color-background: var(--background);
--color-foreground: var(--foreground);
--color-primary: var(--primary);
--color-primary-foreground: var(--primary-foreground);
--color-secondary: var(--secondary);
--color-secondary-foreground: var(--secondary-foreground);
--color-muted: var(--muted);
--color-muted-foreground: var(--muted-foreground);
--color-accent: var(--accent);
--color-accent-foreground: var(--accent-foreground);
--color-destructive: var(--destructive);
--color-border: var(--border);
--color-input: var(--input);
--color-ring: var(--ring);
--radius-sm: calc(var(--radius) - 4px);
--radius-md: calc(var(--radius) - 2px);
--radius-lg: var(--radius);
--radius-xl: calc(var(--radius) + 4px);
}
@layer base {
:root {
--background: oklch(1 0 0);
--foreground: oklch(0.145 0 0);
--primary: oklch(0.205 0 0);
--primary-foreground: oklch(0.985 0 0);
--secondary: oklch(0.97 0 0);
--secondary-foreground: oklch(0.205 0 0);
--muted: oklch(0.97 0 0);
--muted-foreground: oklch(0.556 0 0);
--accent: oklch(0.97 0 0);
--accent-foreground: oklch(0.205 0 0);
--destructive: oklch(0.577 0.245 27.325);
--border: oklch(0.922 0 0);
--input: oklch(0.922 0 0);
--ring: oklch(0.708 0 0);
--radius: 0.625rem;
}
.dark {
--background: oklch(0.145 0 0);
--foreground: oklch(0.985 0 0);
--primary: oklch(0.985 0 0);
--primary-foreground: oklch(0.205 0 0);
--secondary: oklch(0.269 0 0);
--secondary-foreground: oklch(0.985 0 0);
--muted: oklch(0.269 0 0);
--muted-foreground: oklch(0.708 0 0);
--accent: oklch(0.269 0 0);
--accent-foreground: oklch(0.985 0 0);
--destructive: oklch(0.577 0.245 27.325);
--border: oklch(0.269 0 0);
--input: oklch(0.269 0 0);
--ring: oklch(0.439 0 0);
}
}// app/layout.tsx
import { ThemeProvider } from "next-themes";
import "@/app/globals.css";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en" suppressHydrationWarning>
<body className="bg-background text-foreground antialiased">
<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
{children}
</ThemeProvider>
</body>
</html>
);
}// Demonstração rápida usando componentes shadcn
import { Button } from "@/components/ui/button";
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";
export function LoginCard() {
return (
<Card className="w-[350px]">
<CardHeader>
<CardTitle>Login</CardTitle>
<CardDescription>Insira suas credenciais para continuar.</CardDescription>
</CardHeader>
<CardContent className="space-y-4">
<div className="space-y-2">
<Label htmlFor="email">Email</Label>
<Input id="email" type="email" placeholder="voce@exemplo.com" />
</div>
<div className="space-y-2">
<Label htmlFor="password">Senha</Label>
<Input id="password" type="password" />
</div>
<Button className="w-full">Entrar</Button>
</CardContent>
</Card>
);
}O que isso demonstra:
ThemeProvider do next-themescn() para mesclar nomes de classescomponents/ui/ e são totalmente editáveiscn() mescla nomes de classes com clsx e resolve conflitos do Tailwind com tailwind-mergeCores de tema personalizadas:
/* Use o gerador de temas shadcn em ui.shadcn.com/themes */
:root {
--primary: oklch(0.5 0.2 260); /* azul personalizado */
--destructive: oklch(0.5 0.2 25); /* vermelho personalizado */
}Adicionando um componente com dependências:
# Alguns componentes instalam automaticamente suas dependências
npx shadcn@latest add dialog
# Isso instala @radix-ui/react-dialog e o componente DialogConfiguração de aliases de caminho:
// tsconfig.json
{
"compilerOptions": {
"paths": {
"@/*": ["./*"]
}
}
}// a utilidade cn é totalmente tipada
import { cn } from "@/lib/utils";
cn("bg-red-500", undefined, false, "text-white");
// retorna "bg-red-500 text-white"
// As props dos componentes estendem os tipos Radix
// ex: Button estende React.ButtonHTMLAttributes<HTMLButtonElement>
import { Button, type ButtonProps } from "@/components/ui/button";
function MyButton(props: ButtonProps) {
return <Button variant="outline" {...props} />;
}Não é um pacote - é código-fonte - npm install shadcn está errado. Correção: Use npx shadcn@latest add <component> para copiar componentes para o seu projeto.
Compatibilidade com Tailwind v4 - shadcn/ui suporta Tailwind v4. Certifique-se de executar o npx shadcn@latest init mais recente, que gera o CSS compatível com v4.
Variáveis CSS devem ser definidas - Se você pular a configuração das variáveis CSS, os componentes serão renderizados sem cores. Correção: Certifique-se de que seu globals.css inclua os blocos completos de variáveis :root e .dark.
Caminho de importação cn() - Os componentes importam de @/lib/utils. Se o seu alias for diferente, atualize components.json e execute init novamente.
Atualizações de componentes - Como os componentes são copiados, eles não se atualizam automaticamente. Correção: Reexecute npx shadcn@latest add <component> para obter a versão mais recente (mas isso sobrescreverá suas alterações).
| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| Radix UI (puro) | Você quer primitivos sem opiniões sobre estilização | Você quer componentes pré-estilizados e prontos para uso |
| Headless UI | Você usa Tailwind mas prefere uma biblioteca de primitivos diferente | Você quer o ecossistema completo do shadcn |
| MUI / Chakra UI | Você quer uma biblioteca de componentes totalmente empacotada | Você quer controle total sobre o código-fonte do componente |
| Mantine | Você quer uma biblioteca de componentes React "batteries-included" | Você usa Tailwind para estilização |
Não. shadcn/ui copia o código-fonte do componente para o seu projeto. Use npx shadcn@latest add <component>, não npm install shadcn.
components.json com as configurações do projetolib/utils.ts com a utilidade cn()globals.css para tematizaçãocn() combina clsx (mesclagem condicional de classes) com tailwind-merge (resolução de conflitos do Tailwind). Ele garante que as substituições de className funcionem corretamente nos componentes shadcn.
Em components/ui/ por padrão. Cada componente é um arquivo-fonte totalmente editável, não uma dependência do node_modules.
Edite as variáveis CSS em globals.css sob :root (claro) e .dark (escuro). Use o gerador de temas em ui.shadcn.com/themes para predefinições rápidas.
As variáveis CSS são definidas duas vezes - uma em :root para o modo claro e outra em .dark para o modo escuro. Use next-themes com attribute="class" para alternar a classe .dark.
npx shadcn@latest add button input card dialog formAs variáveis CSS estão faltando. Certifique-se de que globals.css inclua os blocos completos de variáveis :root e .dark gerados por npx shadcn@latest init.
Reexecutar npx shadcn@latest add <component> sobrescreve o arquivo. Faça backup de suas personalizações antes de atualizar, ou use controle de versão.
import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";
export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs));
}ClassValue aceita strings, arrays, objetos, undefined, null e booleanos.
import { Button, type ButtonProps } from "@/components/ui/button";
function MyButton(props: ButtonProps) {
return <Button variant="outline" {...props} />;
}As props dos componentes estendem seus tipos subjacentes do Radix ou elemento HTML.
Revisado por Chris St. John·Última atualização: 16 de jul. de 2026
🤖 Read the SystemsArchitect.io Blog for over 100+ cloud architecture articles 🔥