shadcn/ui cambia a Base UI: qué implica

shadcn/ui cambió una decisión que, aunque parece interna, toca varias capas de un proyecto React: ahora su base por defecto deja de ser Radix UI y pasa a ser Base UI. Si usas shadcn/ui para arrancar interfaces rápido, esto no es un detalle menor. Afecta cómo se comportan los componentes, qué tan fácil te resulta personalizar ciertos patrones y cuánto trabajo te puede costar mantener consistencia entre proyectos nuevos y existentes.

La noticia importa porque shadcn/ui no es una librería cerrada que consumes como una caja negra. Su propuesta siempre ha sido más cercana a “copiar y pegar componentes bien armados” que a instalar un paquete y olvidarte. Entonces, cuando cambia la dependencia base, cambian también las piezas que sostienen accesibilidad, manejo de estado, composición y algunos defaults de API. Según la documentación oficial del changelog de shadcn/ui, el nuevo comportamiento por defecto ya apunta a Base UI: changelog oficial.

Qué cambió exactamente

Hasta ahora, muchas de las piezas interactivas de shadcn/ui se apoyaban en Radix UI como base. Eso incluía buena parte del trabajo pesado de accesibilidad y comportamiento para menús, dialogs, popovers, tabs y otros patrones comunes. Con este cambio, el andamiaje por defecto pasa a Base UI, una colección de primitives pensada para cubrir esos mismos casos con una filosofía distinta.

En la práctica, esto significa que cuando generes componentes nuevos con el flujo actual de shadcn/ui, ya no estás partiendo de la misma dependencia base que hace unos meses. No necesariamente cambian todos los componentes de golpe, pero sí cambia el punto de partida. Y ese punto de partida importa porque define props, eventos, estructuras internas y, en algunos casos, el tipo de CSS o de composición que te conviene usar.

Radix UI y Base UI no son lo mismo

Aunque ambos resuelven primitives para React, no conviene tratarlos como equivalentes. Radix UI lleva años siendo una referencia en accesibilidad y componentes sin estilo. Base UI, por su parte, entra con una propuesta más alineada a necesidades actuales de composición y control fino sobre la UI. Si tu equipo ya conoce Radix, no significa que todo se rompa, pero sí que debes leer el cambio como una migración de base, no como un simple update cosmético.

Por qué shadcn/ui hace esto

La respuesta corta es que shadcn/ui busca mantener una base moderna y flexible. Si el ecosistema React cambia, la capa que usa shadcn/ui para construir sus componentes también puede cambiar. Eso le permite al proyecto ajustar defaults, reducir fricción en ciertos casos y alinearse con la evolución de las primitives más usadas en frontend.

Si tú trabajas en producto, la lectura correcta no es “cambió una dependencia y ya”. La lectura correcta es: el contrato implícito de varios componentes puede variar, así que conviene revisar el impacto antes de seguir generando UI a ciegas.

Qué puede cambiar en tu proyecto

El primer impacto suele aparecer en tres frentes: accesibilidad, API y arquitectura. No siempre vas a notar diferencias en la primera pantalla que pruebes, pero sí en casos con interacción compleja, composición avanzada o estilos muy personalizados.

Aquí hay una forma simple de pensarlo: si tu app usa componentes básicos sin mucha personalización, el cambio puede ser casi transparente. Si tu app depende de overrides, wrappers propios o integración con formularios y estados complejos, el riesgo sube. Y si además tu equipo mezcla componentes generados con versiones antiguas y nuevas, la mezcla puede volverse difícil de mantener.

Accesibilidad: el punto que no debes asumir

Si usas shadcn/ui, seguramente te importa que una modal se cierre con Escape, que un menu se navegue con teclado o que un combobox anuncie bien su estado. Eso no se puede dar por hecho solo porque el componente “se ve igual”. Cuando cambias la primitive base, cambian detalles de implementación que afectan foco, semántica y comportamiento esperado.

No significa que Base UI sea peor o mejor por defecto. Significa que, si tu producto depende de accesibilidad consistente, tienes que validar. En equipos serios, eso no se hace con una mirada rápida en el navegador. Se hace probando teclado, lector de pantalla cuando aplique y flujos reales de uso.

API y composición: donde aparecen los dolores

La API de un componente no se rompe solo cuando cambia el nombre de una prop. También se rompe cuando cambia la forma en que anidas subcomponentes, el orden de render o la necesidad de pasar refs y handlers. Si tienes un wrapper propio sobre un componente de shadcn/ui, revisa si ese wrapper sigue siendo válido con la nueva base.

Un ejemplo común: tu equipo puede haber creado un DropdownMenu custom con estilos y lógica para permisos. Si la primitive base cambia, puede que el wrapper siga compilando pero ya no se comporte igual en edge cases, como apertura en mobile, focus trap o interacción con portales.

Cómo te afecta si empiezas un proyecto nuevo

Si estás arrancando un proyecto desde cero, el cambio puede jugar a tu favor, pero solo si no copias patrones viejos por inercia. Base UI como nueva base por defecto te da una línea de partida distinta. Eso puede simplificar ciertos casos y obligarte a repensar otros.

Lo más práctico es que no asumas que el boilerplate que guardaste hace seis meses sigue siendo la mejor opción. Si tu stack actual usa Next.js, Tailwind y shadcn/ui, revisa el componente que vas a generar antes de crear diez pantallas encima de una decisión vieja. En proyectos nuevos, el costo de revisar temprano es bajo. El costo de descubrir el problema cuando ya tienes 40 componentes conectados a formularios, analytics y permisos es bastante mayor.

Qué revisar antes de generar componentes

1. Verifica qué versión del CLI o del flujo de generación estás usando.
2. Confirma si los componentes nuevos salen sobre Base UI o si tu proyecto quedó anclado a una base anterior.
3. Revisa si tu design system depende de clases, data-attributes o estructuras internas específicas.
4. Prueba interacción con teclado en al menos estos casos: dialog, dropdown, popover y tabs.
5. Si usas formularios, valida integración con React Hook Form o la herramienta que tengas.
6. Documenta el patrón elegido para que el equipo no mezcle bases sin querer.

Si trabajas con equipos distribuidos en LatAm, esto también ayuda a evitar un problema típico: cada persona genera componentes en momentos distintos y termina con una mezcla de estilos y patrones. El resultado no suele fallar en build, pero sí en mantenimiento.

Qué hacer en proyectos existentes

Aquí es donde el cambio se vuelve más delicado. Si ya tienes una base montada sobre shadcn/ui con componentes personalizados, el objetivo no es correr a actualizar todo. El objetivo es medir el impacto y decidir qué conviene migrar, qué conviene congelar y qué conviene rehacer.

En proyectos vivos, una migración total suele ser innecesaria si el sistema actual funciona bien. Pero ignorar el cambio también puede salir caro, sobre todo si dependes de nuevas piezas generadas o si el equipo quiere estandarizar componentes a futuro. Lo razonable es separar el problema en capas: lo que ya está en producción, lo que está en desarrollo y lo que todavía no se ha construido.

Estrategia de migración por fases

Una forma práctica de avanzar es esta:

• Congela el comportamiento de los componentes críticos que ya están en producción.
• Identifica qué componentes nuevos se generarán con la nueva base.
• Compara diferencias de API entre versiones viejas y nuevas.
• Ejecuta pruebas de interacción en los flujos más usados.
• Migra primero componentes de bajo riesgo, como badges, tooltips o elementos simples.
• Deja para el final piezas complejas como dialogs, selects o date pickers.

Esta estrategia reduce el riesgo porque no mezclas todo al mismo tiempo. También te permite observar diferencias reales antes de tocar el núcleo del producto. Si tu app tiene usuarios en varios países de Latinoamérica, el impacto de una mala migración puede sentirse rápido: más tickets, más soporte y más tiempo perdido en QA.

Qué componentes revisaría primero

No todos los componentes tienen el mismo peso. Yo empezaría por los que concentran interacción y accesibilidad:

• Dialog y AlertDialog
• DropdownMenu
• Popover
• Tabs
• Select
• Combobox si lo tienes montado con primitives

Estos suelen esconder más complejidad que un botón o una etiqueta. Si algo cambia ahí, el usuario lo nota enseguida: foco perdido, cierre inesperado, teclado que deja de funcionar o un overlay que no respeta el scroll.

Cómo evaluar si el cambio te conviene

No tienes que decidir por intuición. Puedes evaluar el cambio con una lista corta de criterios técnicos y de producto. El punto es saber si te conviene adoptar la nueva base en toda la app o solo en componentes puntuales.

Un criterio útil es el costo de mantenimiento. Si tu equipo ya pasó por varios parches sobre Radix UI para resolver detalles de composición, Base UI puede darte una base más cómoda para ciertos casos. Si en cambio tu sistema ya está muy afinado y documentado, migrar por migrar no te aporta mucho.

Otro criterio es el grado de personalización. Cuanto más dependes de estilos y wrappers propios, más cuidado necesitas. Cuando un componente base cambia, el riesgo no está solo en el render. También está en la forma en que tu equipo entiende y documenta el componente.

Señales de que sí conviene moverte

• Estás arrancando un producto nuevo y todavía no congelaste el design system.
• Tu equipo quiere reducir fricción al crear componentes interactivos.
• Tienes pocos wrappers propios y poca deuda visual.
• Tus pruebas automáticas cubren interacción, no solo snapshots.
• Ya estabas evaluando Base UI por otras razones técnicas.

Señales de que conviene esperar

• Tienes una app en producción con muchos flujos críticos.
• Tu sistema de UI tiene wrappers profundos sobre Radix.
• Tu equipo no tiene cobertura de tests de interacción.
• Hay una fecha de entrega cercana y no sobra tiempo para validar edge cases.
• Ya resolviste accesibilidad y consistencia con la base actual.

Qué revisar en accesibilidad, tests y arquitectura

La parte menos visible del cambio suele ser la más cara. Cuando una base de components cambia, los problemas no siempre aparecen en el primer render. A veces aparecen en el foco inicial, en el tab order, en la interacción con portales o en cómo se montan y desmontan los nodos del DOM.

Por eso, si administras un proyecto serio, conviene revisar tres cosas en paralelo: accesibilidad, tests y arquitectura. Si solo miras el navegador, te puedes quedar corto. Si solo miras el diff de código, también.

Accesibilidad

Prueba los componentes con teclado. No solo Tab y Shift+Tab, también Escape, Enter, Space y flechas donde aplique. Si usas lectores de pantalla en tu equipo de QA o tienes una guía interna, valida que roles y estados sigan siendo coherentes. La documentación oficial de Base UI puede servirte como referencia de comportamiento y APIs: Base UI docs.

Tests

Si usas Testing Library o Playwright, revisa si tus tests dependen de texto exacto, estructura DOM o eventos muy específicos. Un cambio de primitive puede alterar la forma en que se abre un menú o en que se monta un portal. Eso no significa que el componente esté mal; significa que tu test estaba acoplado a una implementación que cambió.

Arquitectura

Si tu app tiene un design system propio, define si Base UI será la nueva base común o solo una opción para componentes nuevos. También conviene documentar qué piezas se permiten personalizar y cuáles no. Sin esa regla, el equipo termina con una mezcla de variantes difíciles de sostener.

Tabla resumen

En resumen, el cambio de base en shadcn/ui no es solo una nota técnica para curiosos. Si tú construyes producto con React, puede tocar accesibilidad, APIs internas y decisiones de arquitectura que ya tenías medio cerradas. La buena noticia es que no tienes que reaccionar con pánico. La mala noticia es que ignorarlo sí te puede salir caro si tu UI depende de componentes complejos.

La decisión razonable es simple: revisa qué partes de tu app dependen de primitives interactivas, valida el comportamiento real y define si vas a adoptar Base UI de forma gradual o si mantienes la base actual en componentes existentes. Si estás empezando un proyecto nuevo, este puede ser un buen momento para ordenar tu sistema de UI desde el inicio. Si ya tienes producción, el cambio merece una evaluación con QA, no solo una actualización de dependencias.