Carregando
Aprenda Shadcn UI do zero: instalação, componentes React, Tailwind CSS e TypeScript. Monte um design system acessível passo a passo no Next.js.
Aprenda Shadcn UI do zero: instalação, componentes React, Tailwind CSS e TypeScript. Ideal para montar um design system acessível no Next.js.
Este tutorial do Shadcn UI cobre um sistema copy-paste de componentes React: você roda a CLI, o código vai para o seu repo e você customiza sem vendor lock-in. Com Tailwind e TypeScript no Next.js, o caminho típico é npx shadcn@latest init e depois npx shadcn@latest add no componente desejado.
Diferente de libs monolíticas (ex.: MUI) que empurram dezenas/centenas de KB, o Shadcn copia só o que você adiciona — o custo real depende do que importa. Você dono do código em components/ui, com primitivos Radix ou Base UI (default em projetos novos desde jul/2026).
Você é dono do código. Copie componentes diretamente para seu projeto. Sem black boxes, sem dependências ocultas.
Tecnologias de ponta: Tailwind CSS para styling, Radix UI vs Base UI para acessibilidade, e TypeScript com React para type safety.
Zero runtime overhead. Apenas o CSS e JavaScript que você realmente usa. Bundle size otimizado automaticamente.
Que querem componentes modernos sem vendor lock-in
Buscando design system consistente e customizável
Que precisam de SSR e performance otimizada
Que precisam desenvolver interfaces rapidamente
O custo por componente costuma ficar na casa de poucos KB no seu app (você copia o código). Comparativos absolutos tipo “300KB do MUI vs 1.2KB do Button” variam com tree-shaking e imports — meça no seu bundle.
Você controla 100% do código. Diferente de Chakra UI ou Ant Design, pode modificar qualquer linha. Exemplo: customizar hover states, animations, responsive breakpoints.
Radix UI ou Base UI (default do Shadcn em projetos novos desde jul/2026) como base = acessibilidade nativa. Screen readers, keyboard navigation, ARIA. Exemplo: Modal com focus trap, Dropdown com arrow keys.
Tailwind CSS puro = performance máxima. Sem runtime CSS, sem styled-components overhead. Exemplo: className="bg-blue-500 hover:bg-blue-600" vs styled.div`background: blue`.
Webpack elimina código não usado automaticamente. Import apenas o que precisa. Exemplo: import { Button } from "./ui/button" vs import { Button } from "@mui/material".
Server Components ready. SSR perfeito, hydration otimizada. Exemplo: componentes renderizam no servidor, JavaScript mínimo no cliente.
Desde julho de 2026, projetos novos iniciados com a CLI do Shadcn usam Base UI por padrão. Radix continua suportado — inclusive via flag de init quando o time preferir ficar no ecossistema Radix.
Neste tutorial você instala e usa componentes do Shadcn normalmente. A decisão Radix vs Base UI (migração, asChild vs render, árvore de decisão) está no comparativo Radix UI vs Base UI.
-b radix no init (confirme a CLI do mês)Setup completo em 3 minutos. Guia definitivo para instalar Shadcn/UI em Next.js, Vite, Remix e outros frameworks React.
Diferente de outras UI libraries, Shadcn/UI não é um pacote NPM tradicional. Você instala uma CLI que copia componentes diretamente para seu projeto, garantindo controle total e zero dependências externas.
# Projeto Next.js com todas as configurações otimizadas
npx create-next-app@latest meu-projeto-shadcn \
--typescript \
--tailwind \
--eslint \
--app \
--src-dir \
--import-alias "@/*"
cd meu-projeto-shadcn# Instala e configura Shadcn/UI automaticamente
npx shadcn@latest init
# Responda as perguntas de configuração:
# ✔ Which style would you like to use? › Default
# ✔ Which color would you like to use as base color? › Slate
# ✔ Would you like to use CSS variables for colors? › yes# Componentes mais usados (instale todos de uma vez)
npx shadcn@latest add button input card dialog
# Ou instale individualmente conforme necessário:
npx shadcn@latest add button
npx shadcn@latest add input
npx shadcn@latest add card
npx shadcn@latest add dialogBiblioteca completa de UI components para React. Cada componente é otimizado para performance, acessibilidade e customização total.
Diferente de Material-UI ou Ant Design, você não está limitado ao design system deles. Cada componente Shadcn/UI pode ser 100% customizado, desde cores até animações e comportamentos.
9 variantes diferentes: default, destructive, outline, secondary, ghost, link. Suporte a loading states, icons, e tamanhos responsivos.
Caminho de produção: npx shadcn@latest add form + schema Zod + React Hook Form. Validação tipada, erros por campo e nested objects/arrays. Use o exemplo de login mais abaixo como template — não só o card.
Modal acessível sobre primitivos headless (Base UI no default 2026; Radix se o projeto optar). Focus trap, ESC, backdrop e nested dialogs — teste a11y no seu tema.
Padrão Shadcn + TanStack Table: sorting, filter, pagination e row selection. Para listas grandes, meça virtualização no seu dataset — não assuma “10k rows” sem profile. Comece pelo exemplo oficial de data-table e adapte colunas ao domínio (SaaS/CRM).
Feedback de mutação (save, erro de API, undo). Em apps novos, o caminho comum é sonner via CLI Shadcn; projetos antigos podem ainda usar o toast legado. Coloque o toaster no layout raiz uma vez.
Command palette como VS Code. Search, keyboard navigation, grupos, e actions customizáveis. Perfeito para dashboards e admin panels.
Button, Input, Label, Textarea, Badge, Avatar, Separator
Form, Select, Checkbox, Radio, Switch, Slider, Calendar
Card, Sheet, Tabs, Accordion, Collapsible, Aspect Ratio
Data Table, Command, Combobox, Date Picker, Charts
Código de produção real. Copie, cole, customize. Zero configuração adicional.
Tutoriais que funcionam de verdade. Cada exemplo roda em produção. Validação real, TypeScript, acessibilidade. Sem "hello world" inútil.
Exemplo real: Formulário de login com validação, loading states, e error handling usando Form + Input + Button.
import { useForm } from "react-hook-form"
import { zodResolver } from "@hookform/resolvers/zod"
import * as z from "zod"
import { Button } from "@/components/ui/button"
import { Input } from "@/components/ui/input"
import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from "@/components/ui/form"
const formSchema = z.object({
email: z.string().email("Email inválido"),
password: z.string().min(6, "Mínimo 6 caracteres")
})
export function LoginForm() {
const form = useForm<z.infer<typeof formSchema>>({
resolver: zodResolver(formSchema)
})
const onSubmit = async (values: z.infer<typeof formSchema>) => {
// Lógica de login aqui
}
return (
<Form {...form}>
<form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
<FormField
control={form.control}
name="email"
render={({ field }) => (
<FormItem>
<FormLabel>Email</FormLabel>
<FormControl>
<Input placeholder="seu@email.com" {...field} />
</FormControl>
<FormMessage />
</FormItem>
)}
/>
<FormField
control={form.control}
name="password"
render={({ field }) => (
<FormItem>
<FormLabel>Senha</FormLabel>
<FormControl>
<Input type="password" {...field} />
</FormControl>
<FormMessage />
</FormItem>
)}
/>
<Button type="submit" className="w-full" disabled={form.formState.isSubmitting}>
{form.formState.isSubmitting ? "Entrando..." : "Entrar"}
</Button>
</form>
</Form>
)
}Controle total sobre design e comportamento. Diferente de outras UI libraries, você pode modificar 100% do código dos componentes.
Vendor lock-in é um problema real. Com Shadcn/UI, você nunca fica preso a decisões de design de terceiros. Cada linha de código está no seu projeto e pode ser modificada.
Apenas CSS Variables. Mude todo seu app alterando 5 linhas de código. Zero JavaScript.
:root {
--background: 0 0% 100%;
--foreground: 222.2 84% 4.9%;
--primary: 222.2 47.4% 11.2%;
--primary-foreground: 210 40% 98%;
--radius: 0.5rem;
}
.dark {
--background: 222.2 84% 4.9%;
--foreground: 210 40% 98%;
--primary: 210 40% 98%;
--primary-foreground: 222.2 47.4% 11.2%;
}Valores HSL são mais fáceis de ajustar. Mude apenas o matiz (H) para criar variações de cor mantendo saturação (S) e luminosidade (L).
Shadcn/UI tem suporte nativo ao dark mode. Use a classe `.dark` no elemento raiz para ativar o tema escuro.
// app/layout.tsx
import { ThemeProvider } from 'next-themes'
export default function RootLayout({ children }) {
return (
<html lang="en" suppressHydrationWarning>
<body>
<ThemeProvider
attribute="class"
defaultTheme="system"
enableSystem
disableTransitionOnChange
>
{children}
</ThemeProvider>
</body>
</html>
)
}import { useTheme } from 'next-themes'
import { Button } from '@/components/ui/button'
import { Moon, Sun } from 'lucide-react'
export function ThemeToggle() {
const { theme, setTheme } = useTheme()
return (
<Button
variant="outline"
size="icon"
onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}
>
<Sun className="h-[1.2rem] w-[1.2rem] rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" />
<Moon className="absolute h-[1.2rem] w-[1.2rem] rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />
</Button>
)
}Modifique as CSS variables na classe `.dark` para personalizar cores do tema escuro.
Menos runtime CSS, tree shaking real e só o código dos componentes que você copia. Meça no seu app — números absolutos variam por build.
Performance mata conversão. 100ms de delay = 1% menos vendas. Shadcn/UI carrega em 0.8s vs 3.2s do Material-UI. Seus usuários ficam, não saem.
// ✅ Só o que você usa
import { Button } from '@/components/ui/button'
// ❌ Tudo vem junto
import * as UI from '@material-ui/core'const Dialog = lazy(() => import('@/components/ui/dialog'))
const DataTable = lazy(() => import('@/components/ui/data-table'))Com Tailwind e TypeScript no projeto, rode `npx shadcn@latest init` e depois `npx shadcn@latest add button` (ou o componente desejado). A CLI gera `components.json` e copia o código para o seu repo — não use o pacote antigo `shadcn-ui@latest`.
Não. É um sistema copy-paste: você dono do código em `components/ui`. Isso permite customizar livremente e evitar black box de versão de design system fechado.
O catálogo oficial cresceu para a faixa de 75+ componentes em 2026 (além de registries da comunidade). Adicione só o que for usar para manter o bundle enxuto.
Os dois. Desde julho de 2026 o default em projetos novos é Base UI; Radix segue suportado. Acessibilidade vem dos primitivos escolhidos — meça no seu app após init.
Sim. O fluxo usual combina CSS variables do tema com `next-themes` (ou equivalente) e a classe `.dark`. O tutorial cobre toggle e persistência sem flash no SSR.
Revisão em agosto de 2026. CLI oficial, contagem de componentes e primitivos (Radix ou Base UI) devem ser conferidos na documentação — este tutorial acompanha o comando npx shadcn@latest.
Default Base UI em 2026, Radix ainda suportado — quando migrar.
Bundle, customização e quando cada lib faz sentido.
Novas features e direção do ecossistema Shadcn.
Utility-first CSS que alimenta o design system do Shadcn.
Base de React para usar componentes Shadcn com confiança.