Instalação, Tailwind, TypeScript e design system Shadcn UI tutorial: instale e use componentes React
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.
React UI Components + Tailwind CSS Shadcn UI tutorial: instale e use componentes React
Aprenda Shadcn UI do zero: instalação, componentes React, Tailwind CSS e TypeScript. Ideal para montar um design system acessível no Next.js.
Shadcn/UI mata vendor lock-in
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.
Por que isso é importante
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).
Copy & Paste
Você é dono do código. Copie componentes diretamente para seu projeto. Sem black boxes, sem dependências ocultas.
Stack Moderna
Tecnologias de ponta: Tailwind CSS para styling, Radix UI vs Base UI para acessibilidade, e TypeScript com React para type safety.
Performance
Zero runtime overhead. Apenas o CSS e JavaScript que você realmente usa. Bundle size otimizado automaticamente.
Ideal para quem?
✅ Desenvolvedores React
Que querem componentes modernos sem vendor lock-in
✅ Teams Frontend
Buscando design system consistente e customizável
✅ Projetos Next.js
Que precisam de SSR e performance otimizada
✅ Startups & Agencies
Que precisam desenvolver interfaces rapidamente
Por que Shadcn/UI domina o mercado? 5 motivos que fazem desenvolvedores escolherem Shadcn/UI em 2026
Bundle Size Mínimo
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.
Zero Vendor Lock-in
Você controla 100% do código. Diferente de Chakra UI ou Ant Design, pode modificar qualquer linha. Exemplo: customizar hover states, animations, responsive breakpoints.
Acessibilidade WCAG 2.1
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.
CSS-in-JS Free
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`.
Tree Shaking Perfeito
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".
Next.js 15+ Otimizado
Server Components ready. SSR perfeito, hydration otimizada. Exemplo: componentes renderizam no servidor, JavaScript mínimo no cliente.
Base UI como default em 2026 — e quando ficar no Radix
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.
Quando ficar em Radix mesmo em 2026
- App estável em produção sem dor de primitivo — oficial: não precisa migrar
- Time já tem design system/internals em cima de Radix — migre só com motivo
- Novo projeto com opt-in explícito: flag
-b radixno init (confirme a CLI do mês)
Instalação Shadcn/UI 2026
Setup completo em 3 minutos. Guia definitivo para instalar Shadcn/UI em Next.js, Vite, Remix e outros frameworks React.
Por que isso é importante
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.
Setup Next.js 15+ com App Router
# 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✅ Incluído automaticamente:
- • TypeScript configurado
- • Tailwind CSS + PostCSS
- • ESLint + Prettier
- • App Router (Next.js 13+)
- • Path aliases (@/*)
🚀 Alternativas populares:
- • Vite: npm create vite@latest
- • Remix: npx create-remix@latest
- • Gatsby: npx create-gatsby
- • T3 Stack: npm create t3-app@latest
Inicializar Shadcn/UI CLI
# 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📁 Arquivos criados:
- • `components.json` (config)
- • `lib/utils.ts` (helpers)
- • `globals.css` (CSS variables)
- • `components/ui/` (pasta componentes)
⚙️ Configurações aplicadas:
- • Tailwind config atualizado
- • CSS variables para temas
- • TypeScript paths configurados
- • Utilitários cn() instalados
Adicionar Componentes Essenciais
# 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 dialog🎯 Essenciais:
- • button
- • input
- • card
- • dialog
- • badge
📋 Formulários:
- • form
- • select
- • checkbox
- • radio-group
- • textarea
🎨 Avançados:
- • dropdown-menu
- • popover
- • toast
- • sheet
- • tabs
75+ Componentes React Prontos
Biblioteca completa de UI components para React. Cada componente é otimizado para performance, acessibilidade e customização total.
Por que isso é importante
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.
Button
9 variantes diferentes: default, destructive, outline, secondary, ghost, link. Suporte a loading states, icons, e tamanhos responsivos.
Form + Zod + React Hook Form
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.
Dialog
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.
Data Table (produção)
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).
Toast / Sonner
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
Command palette como VS Code. Search, keyboard navigation, grupos, e actions customizáveis. Perfeito para dashboards e admin panels.
Todos os 75+ Componentes
Básicos:
Button, Input, Label, Textarea, Badge, Avatar, Separator
Formulários:
Form, Select, Checkbox, Radio, Switch, Slider, Calendar
Layout:
Card, Sheet, Tabs, Accordion, Collapsible, Aspect Ratio
Avançados:
Data Table, Command, Combobox, Date Picker, Charts
Copy-Paste e Funciona
Código de produção real. Copie, cole, customize. Zero configuração adicional.
Por que isso é importante
Tutoriais que funcionam de verdade. Cada exemplo roda em produção. Validação real, TypeScript, acessibilidade. Sem "hello world" inútil.
Formulário de Login Completo
Exemplo real: Formulário de login com validação, loading states, e error handling usando Form + Input + Button.
📦 Componentes necessários:
💡 Features incluídas:
- • Validação em tempo real com Zod
- • Loading state no botão durante submit
- • Error handling com mensagens customizadas
- • TypeScript safety completo
- • Acessibilidade WCAG 2.1
🔧 Código do componente:
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>
)
}Customização Avançada Shadcn/UI
Controle total sobre design e comportamento. Diferente de outras UI libraries, você pode modificar 100% do código dos componentes.
Por que isso é importante
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.
Temas em 5 Linhas de Código
🎨 Troque cores em segundos:
Apenas CSS Variables. Mude todo seu app alterando 5 linhas de código. Zero JavaScript.
📁 globals.css simplificado:
: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%;
}🚀 Temas em 30 segundos:
Tema Azul:
Tema Verde:
Tema Roxo:
💡 Dica Pro:
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).
Dark mode com ThemeProvider
🌙 Como implementar:
Shadcn/UI tem suporte nativo ao dark mode. Use a classe `.dark` no elemento raiz para ativar o tema escuro.
📦 Instalar next-themes:
🔧 Provider setup:
// 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>
)
}🎛️ Theme Toggle Component:
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>
)
}✅ Vantagens:
- • System preference detection
- • No flash durante carregamento
- • Persistência entre sessões
- • SSR compatible
🎨 Customização:
Modifique as CSS variables na classe `.dark` para personalizar cores do tema escuro.
Performance e tamanho de bundle
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.
Por que isso é importante
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.
Bundle 12x Menor
📊 Comparação real:
⚡ Tree Shaking Real:
// ✅ Só o que você usa
import { Button } from '@/components/ui/button'
// ❌ Tudo vem junto
import * as UI from '@material-ui/core'🎯 Lazy Loading:
const Dialog = lazy(() => import('@/components/ui/dialog'))
const DataTable = lazy(() => import('@/components/ui/data-table'))React 19 Ready
🚀 Features modernas:
- Server Components nativo
- Concurrent Rendering otimizado
- Suspense para data fetching
- Zero runtime CSS
📈 Métricas reais:
💡 Otimizações que funcionam:
- • React.memo em componentes pesados
- • Virtualization para listas 1000+ items
- • Code splitting automático por rota
- • Tailwind purge remove CSS não usado
Perguntas frequentes
Como instalar o Shadcn UI no Next.js?
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`.
Shadcn UI é uma biblioteca npm tradicional?
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.
Quantos componentes o Shadcn tem?
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.
Shadcn usa Radix ou Base UI?
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.
Shadcn UI funciona com dark mode?
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.
Fontes
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.
Leituras relacionadas para continuar
Radix UI vs Base UI no Shadcn
Default Base UI em 2026, Radix ainda suportado — quando migrar.
Shadcn vs Material UI
Bundle, customização e quando cada lib faz sentido.
Roadmap Shadcn UI
Novas features e direção do ecossistema Shadcn.
Guia Tailwind CSS
Utility-first CSS que alimenta o design system do Shadcn.
React Hooks definitivo
Base de React para usar componentes Shadcn com confiança.