O que é o Shadcn/UI

O Shadcn/UI é uma coleção de componentes React prontos para copiar e colar no seu projeto. Diferente de uma biblioteca tradicional instalada via npm, você pega o código dos componentes e os adiciona diretamente ao seu projeto - ou seja, eles são seus, você pode modificar como quiser.

Lançado por Shadcn (pseudónimo do criador), o projeto explodiu em popularidade em 2023 e hoje é uma das referências mais usadas no ecossistema React. A proposta é simples: componentes bonitos, acessíveis e sem a rigidez de uma dependência de terceiros no bundle.

A base técnica sempre foi o Radix UI, uma biblioteca de primitivas headless (sem estilo) focada em acessibilidade. Mas isso mudou com a atualização mais recente.

Como funciona a mudança para Base UI

O Base UI é uma biblioteca de componentes headless desenvolvida pela equipe do MUI (Material UI). Ele resolve os mesmos problemas do Radix - comportamento acessível de dropdowns, dialogs, tooltips, etc. - mas com uma arquitetura diferente e foco em performance e flexibilidade.

A equipe do Shadcn/UI anunciou no changelog que os novos componentes gerados pelo CLI agora usam Base UI como primitiva padrão. Isso significa que ao rodar npx shadcn@latest add button, o componente gerado vai importar do @base-ui-components/react em vez do @radix-ui/react-*.

A mudança é gradual: componentes existentes instalados antes da atualização continuam funcionando com Radix. Novos componentes adicionados após a mudança usam Base UI.

⚠️
Atenção

Se você tem um projeto com Shadcn/UI instalado, os componentes já existentes não são migrados automaticamente. Apenas novos componentes adicionados via CLI vão usar Base UI.

Principais recursos e diferenciais do Base UI

O Base UI traz alguns avanços em relação ao Radix que motivaram a troca:

  • Performance melhorada: menor overhead de re-renders em componentes controlados como Select e Combobox
  • API mais consistente: padrão de composição mais uniforme entre todos os componentes
  • Suporte a animações CSS: o Base UI tem suporte nativo a transições CSS, facilitando animações de entrada e saída sem depender de bibliotecas extras
  • Manutenção ativa pela MUI: time grande com histórico de manutenção consistente no ecossistema React
  • TypeScript moderno: tipos mais precisos e inferência melhor

O Radix continua sendo uma excelente opção, mas o Base UI resolve algumas dores que desenvolvedores reportavam há tempo, especialmente com animações e performance em listas longas.

Como começar: atualizando seu projeto

Se você tem um projeto novo ou quer usar os novos componentes, o processo é direto. Inicialize com npx shadcn@latest init e adicione componentes com npx shadcn@latest add dialog. O CLI já configura Base UI automaticamente.

Para projetos existentes que querem migrar componentes antigos para Base UI, a recomendação da equipe é recriar o componente via CLI e ajustar as customizações que você já tinha.

💡
Dica

Antes de migrar, verifique quais componentes do seu projeto importam de @radix-ui/*. Execute grep -r @radix-ui src/ no terminal para mapear o trabalho necessário.

A instalação do Base UI é feita automaticamente pelo CLI do Shadcn. Você não precisa adicionar a dependência manualmente.

Exemplo prático: Dialog com Base UI

O uso do componente no JSX continua quase idêntico ao anterior. A mudança está na implementação interna do componente, não na API que você usa no seu código. A grande vantagem é que sua interface de uso não muda. Se você já usava Shadcn/UI, o padrão de composição é o mesmo. A mágica acontece por baixo dos panos.

Ao adicionar Dialog via CLI, o componente gerado vai usar os primitivos do Base UI internamente mas expor a mesma API de composição que você já conhece: DialogTrigger, DialogContent, DialogHeader e DialogTitle.

Para a maioria dos devs, essa transição será transparente - o componente funciona igual, o código JSX que você escreve é o mesmo.

Comparação com alternativas

O Radix UI é mais maduro, tem documentação extensa e uma comunidade enorme. Se você tem um projeto rodando bem com Radix, não há motivo urgente para migrar. A maioria dos componentes comuns (Button, Badge, Card) nem usa primitivas headless - a diferença fica restrita a componentes interativos.

O Headless UI da Tailwind Labs é outra alternativa popular, mas com suporte a menos componentes que Base UI e Radix. Para quem usa Tailwind puro, é uma opção válida para casos simples.

O Base UI brilha em animações CSS nativas e tem uma API de composição mais previsível em componentes mais complexos como Combobox e Select com busca. Para projetos novos, já faz sentido começar com ele.

🚀
Pro tip

Se você usa Shadcn/UI em vários projetos, manter uma versão atualizada do seu template base com os novos componentes Base UI economiza tempo. Crie um repositório de referência e sincronize entre projetos.

Pontos positivos e limitações

A mudança para Base UI é positiva no geral, mas tem pontos de atenção. No lado positivo: animações CSS nativas funcionam sem configuração extra, a performance em Selects com muitos itens melhorou visivelmente, e o suporte a TypeScript está mais preciso.

As limitações existem: a documentação do Base UI ainda é menor que a do Radix, a comunidade é mais nova (menos respostas no Stack Overflow), e alguns componentes do Radix ainda não têm equivalente completo no Base UI. A migração de projetos grandes pode ser trabalhosa se você customizou muito os internos dos componentes.

Projetos que dependem de plugins ou integrações feitas especificamente para Radix precisam verificar compatibilidade antes de migrar.

Casos de uso reais

Para um projeto novo com Next.js: simplesmente rode o CLI e use os componentes gerados. Você vai ter Base UI por padrão sem precisar pensar nisso.

Para um time migrando um SaaS existente: a estratégia mais segura é migrar componente por componente, começando pelos menos customizados. Componentes como Dialog e Tooltip costumam ser mais simples de migrar que Select e Combobox.

Para um dev freelancer que faz projetos para clientes: manter dois templates (um com Radix para projetos em manutenção, um com Base UI para projetos novos) é uma estratégia razoável por enquanto.

Para open source contributors: o Base UI é uma boa oportunidade de contribuição - documentação em português, exemplos e issues são bem-vindos.

Dicas e boas práticas

💡
Dica

Mantenha um components.json versionado no seu projeto. Ele registra exatamente quais componentes Shadcn você adicionou e com quais configurações - facilita auditorias e migrações futuras.

💡
Dica

Use o comando npx shadcn@latest diff para ver o que mudou nos componentes desde que você os adicionou. Isso facilita aplicar updates sem sobrescrever suas customizações.

🔴
Cuidado

Nunca rode npx shadcn@latest add em um componente já customizado sem antes salvar suas modificações. O CLI pode sobrescrever o arquivo com a versão padrão.

🚀
Pro tip

Para projetos em produção, trave as versões do @base-ui-components/react e do Shadcn CLI no package.json. Updates de primitivas headless podem ter breaking changes sutis.

Vale a pena migrar?

Para projetos novos: sim, use Base UI por padrão. O CLI já faz isso, então você nem precisa se preocupar - é a opção padrão a partir de agora.

Para projetos existentes em produção: não há urgência. Radix UI segue com suporte e os componentes funcionam. Migre quando for conveniente, componente por componente, ou quando precisar adicionar novos componentes interativos.

O próximo passo prático: acesse o changelog oficial do Shadcn/UI em ui.shadcn.com/docs/changelog, veja quais componentes já foram atualizados para Base UI e avalie o impacto no seu projeto específico.