shadcn/ui est passé de Radix à Base UI

Si votre application shadcn/ui tourne sur Radix, vous n’avez pas besoin de migrer. Base UI est désormais l’option par défaut pour les nouveaux projets, mais Radix reste entièrement pris en charge, les mises à jour sont livrées pour les deux bibliothèques, et l’équipe shadcn continue d’utiliser Radix dans ses propres applications en production.

Le changement a eu lieu le 3 juillet 2026. Une grande partie de la couverture médiatique depuis lors a laissé entendre qu’une réécriture était à prévoir, ce qui n’est pas ce que dit le changelog.

Deux questions déterminent la suite : devez-vous agir, et combien coûte une migration si vous en choisissez une ? Ce coût se divise entre les changements que le compilateur détecte et ceux qu’il ne détecte pas, et c’est dans la seconde catégorie que réside le risque.

Ce qui a changé le 3 juillet 2026

Les nouveaux projets shadcn/ui utilisent désormais Base UI par défaut, et rien d’autre n’a changé pour un projet existant. Trois éléments ont évolué. L’exécution de npx shadcn init sélectionne Base UI sauf indication contraire, shadcn/create place Base UI en tête de sa liste, et la documentation des composants vous amène désormais sur l’onglet Base UI, avec un onglet Radix juste à côté. Radix lui-même n’est pas déprécié.

Conserver Radix sur un nouveau projet ne demande qu’un seul flag :

pnpm dlx shadcn init -b radix

Partout où une CI ou un script de scaffolding appelle shadcn init sans invite interactive en supposant qu’il obtiendra Radix, ajoutez ce flag dès maintenant. La valeur par défaut sous-jacente à ces scripts a changé.

Devez-vous migrer vers les composants shadcn Base UI ?

Non. Le changelog s’engage à livrer chaque mise à jour et chaque nouveau composant sur les deux bibliothèques, la seule exception étant les composants qui existent dans Base UI et n’ont aucun équivalent Radix. Il précise également que le code de production de l’équipe elle-même est toujours sur Radix, sans aucun plan de migration. Une application Radix stable n’est soumise à aucun calendrier imposé, aucune fenêtre de dépréciation, aucune échéance de maintenance. Le reste de cet article s’adresse aux équipes qui choisissent de migrer, non à celles qui y sont contraintes.

Pourquoi la valeur par défaut a-t-elle changé ?

Le changelog avance quatre raisons. La bibliothèque avait atteint une version stable 1.6.0 et dépassait les six millions de téléchargements par semaine. Ses mainteneurs continuent d’ajouter des primitives utiles. L’équipe shadcn s’était déjà standardisée dessus pour toute nouveauté. Et parmi les personnes qui initialisent des projets avec shadcn/create, Base UI l’emportait à raison d’environ deux choix pour un en faveur de Radix.

Ces chiffres sont ceux cités dans le changelog. Base UI a continué à livrer depuis : la version 1.8.0 est sortie le 4 septembre 2026. Le changelog souligne également que Base UI est l’œuvre des mêmes personnes qui ont construit Radix. Le package à installer est @base-ui/react ; l’ancien nom @base-ui-components/react porte un avis de dépréciation sur npm qui redirige vers celui-ci.

Ce qu’une migration change réellement

La moitié de la migration qui casse le build est mécanique : des renommages et des changements de types que le compilateur détecte immédiatement.

Une nuance : la séparation Positioner/Popup s’applique aux popups ancrés tels que Menu, Select, Popover et Tooltip. Dialog n’a pas de Positioner ; il s’agit de Dialog.Backdrop plus Dialog.Popup.

Le changement de callback ressemble à ceci :

// Radix: block closing via the event
onEscapeKeyDown={(event) => event.preventDefault()}

// Base UI: one callback, with a reason and a cancel()
onOpenChange={(open, details) => {
  if (details.reason === "escape-key") {
    details.cancel()
    return
  }
  setOpen(open)
}}

Les types de valeurs changent aussi. Un Select contrôlé renvoie désormais Value | null plutôt qu’une chaîne, ce qui en fait la rupture de build la plus courante :

const [fruit, setFruit] = useState<string | null>(null)

Les valeurs d’Accordion et de Toggle Group sont toujours des tableaux, même en mode sélection unique : value="a" devient donc value={["a"]}.

Les changements qui compilent mais se comportent différemment

La moitié dangereuse de la migration passe la vérification de types sans encombre tout en modifiant malgré tout le comportement à l’exécution. Trois écarts se démarquent :

• Les onglets s’activent manuellement par défaut. Les touches fléchées déplacent le focus entre les triggers sans changer le panneau visible, sauf si vous définissez activateOnFocus sur Tabs.List, dont la valeur par défaut est false. Radix utilisait l’activation automatique par défaut.
• Les éléments checkbox et radio des menus laissent le menu ouvert. closeOnClick vaut false par défaut sur Menu.CheckboxItem et Menu.RadioItem, à l’inverse du close-on-select de Radix. Un Menu.Item simple conserve la valeur par défaut true, si bien que le comportement varie selon le type d’élément.
• NavigationMenu s’ouvre plus vite au survol. Le delay de Base UI vaut 50 ms par défaut ; le delayDuration de Radix vaut 200 ms par défaut. Des menus que les utilisateurs effleuraient sans conséquence s’ouvrent désormais.

Rien de tout cela ne produit d’erreur. Un menu qui reste ouvert après un clic et des onglets qui ignorent les touches fléchées sont invisibles pour la surveillance des erreurs, car rien ne lève d’exception. C’est le session replay qui fait apparaître cette catégorie de régression : vous voyez un utilisateur appuyer sur une touche fléchée, ou cliquer deux fois sur un élément checkbox, et constatez que l’interface ne réagit pas comme il l’attend.

Qui devrait passer à Base UI et qui ne devrait pas ?

Migrez si vous avez besoin de Combobox, Autocomplete ou Number Field, que Radix n’a jamais livrés, ou si vous souhaitez rester aligné sur les nouveaux composants du registry à mesure qu’ils arrivent. Restez sur Radix si votre application est stable et que rien de tout cela ne s’applique ; l’engagement de support est explicite, et une application de production fonctionnelle ne gagne rien à un changement de primitives.

Ne fondez pas votre décision sur des rumeurs de lacunes en matière de composants. Base UI propose Context Menu, Toast et une primitive de hover-card sous le nom de Preview Card, et la documentation Base UI de shadcn couvre les trois.

Comment migrer si vous le décidez

Utilisez le skill officiel, pas un codemod, et avancez progressivement. Le raisonnement se tient. Un codemod ne connaît que la version d’origine d’un fichier : il s’en sort donc avec les composants que vous avez laissés intacts et échoue sur ceux que vous avez modifiés. Le skill lit ce que vous avez réellement, reporte vos modifications, et signale les différences de comportement au lieu de les réécrire en silence.

pnpm dlx skills add shadcn/ui

Demandez ensuite à votre agent de codage de migrer un composant, par exemple migrate accordion to base-ui. Vous pouvez conserver les deux bibliothèques installées simultanément, si bien que le build reste vert entre les étapes. Chaque exécution vérifie les types de ce qu’elle a produit, écrit une note sur ce composant dans un dossier .migration/, et l’enregistre comme un commit distinct sur une branche que vous pouvez jeter. Commencez par les composants feuilles comme button et label avant ceux qui les importent, et lisez la section des changements de comportement de chaque rapport avant de fusionner.

Un avertissement : certains guides suggèrent de repointer components.json vers Base UI et de réajouter chaque composant avec --overwrite. Cela détruit toutes les modifications locales que vous avez apportées à ces fichiers, ce qui est précisément l’échec que le skill vise à éviter.

Où cela vous laisse-t-il

La valeur par défaut a changé ; vos obligations, non. Les applications Radix existantes continuent de fonctionner, les nouveaux projets reçoivent Base UI sauf si vous passez -b radix, et une migration est un projet volontaire dont le coût visible se résume à des renommages et dont le coût caché relève du comportement. Si vous migrez, prévoyez le temps de QA nécessaire pour les écarts silencieux, car c’est là que le compilateur cesse d’aider. Commencez par lire vous-même l’entrée du changelog, puis décidez si Combobox ou l’alignement sur le registry vaut la branche.

FAQ

Base UI est-il prêt pour la production par rapport à Radix ?

Oui. Base UI a livré une version stable 1.0.0 en décembre 2025 sous le package '@base-ui/react' et publie régulièrement depuis, atteignant la version 1.8.0 le 4 septembre 2026. Il est l'œuvre des créateurs de Radix, Floating UI et Material UI, et son équipe indique avoir façonné l'API pour qu'elle ressemble volontairement à celle de Radix, afin que le passage de l'une à l'autre demande moins de travail. L'équipe shadcn utilise également Base UI pour chaque nouveau projet qu'elle démarre.

Toutes les props de valeur sont-elles des tableaux dans Base UI ?

Non. La 'value' d'Accordion est toujours un tableau et celle de Toggle Group est toujours un tableau de chaînes, même en mode sélection unique, mais la 'value' de Tabs reste une valeur unique avec 0 par défaut, et Select est typé comme une valeur unique, un tableau ou null. Encapsulez les valeurs d'Accordion et de Toggle Group dans des tableaux, typez l'état contrôlé de Select comme nullable, et laissez Tabs inchangé.

La migration vers Base UI affecte-t-elle les composants shadcn qui n'ont jamais utilisé Radix ?

Non. Command encapsule cmdk, Sonner est une bibliothèque de toasts autonome, Calendar utilise react-day-picker, Input OTP utilise input-otp, et Charts s'appuie sur recharts. Aucun d'entre eux ne dépend des primitives Radix, une migration de Radix vers Base UI les laisse donc intacts. Seuls les composants dont les primitives venaient de Radix, comme Dialog, Menu, Select, Tabs et Popover, nécessitent des modifications.

Le skill de migration shadcn nécessite-t-il pnpm ?

Non. Le changelog documente l'installation du skill pour pnpm, npm, yarn et bun ; 'npx skills add shadcn/ui' est donc un équivalent valide basé sur npm de la commande pnpm. Après l'installation, le skill s'exécute via votre agent de codage, qui migre un composant à la fois et produit du code vérifié au niveau des types, un rapport par composant dans le répertoire '.migration', et un commit par composant, quel que soit le gestionnaire de packages.