Pular para o conteúdo
Tutorial 2026

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.

Tutorial Gratuito

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.

75+
Componentes React
100%
TypeScript
0kb
Runtime
A11y
Acessível
shadcn-example.tsx
// Instale qualquer componente com um comando npx shadcn@latest add button // Use imediatamente no seu projeto import { Button } from '@/components/ui/button' export default function App() { return ( <div className="space-x-2"> <Button variant="default">Primary</Button> <Button variant="outline">Outline</Button> <Button variant="ghost">Ghost</Button> </div> ) }

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 radix no 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.

1

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
2

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
3

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.

npx shadcn@latest add button

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.

npx shadcn@latest add form

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.

npx shadcn@latest add dialog

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).

npx shadcn@latest add table

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.

npx shadcn@latest add sonner

Command

Command palette como VS Code. Search, keyboard navigation, grupos, e actions customizáveis. Perfeito para dashboards e admin panels.

npx shadcn@latest add command

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:

npx shadcn@latest add form input button label

💡 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:
--primary: 221.2 83.2% 53.3%;
Tema Verde:
--primary: 142.1 76.2% 36.3%;
Tema Roxo:
--primary: 262.1 83.3% 57.8%;
💡 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:

npm install 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:

Shadcn/UI Button2.1kb
Material-UI Button15.2kb
Ant Design Button23.8kb

⚡ 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:

First Contentful Paint0.8s
Largest Contentful Paint1.2s
Cumulative Layout Shift0.02

💡 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.

ui.shadcn.com/docschangelogTailwind CSS docs.

Domine React e Tailwind CSS

Aprenda desenvolvimento frontend moderno com nossos cursos especializados