Tamagui 3 : nouveautés et migration

Les flat style props

C'est le changement que vous verrez en premier. Une prop contient désormais sa valeur de base et toutes ses conditions au même endroit, plus besoin de hoverStyle ou de props media séparées. Les modificateurs s'enchaînent avec des deux-points, par exemple dark:sm:hover.

<View bg="background hover:background-hover" p="4 sm:6" />

const Card = styled(View, {
  bg: 'background hover:background-hover',
  p: '4 sm:6',
  scale: { press: 0.98 },
})
    

La forme texte et la forme objet génèrent le même CSS. Vous pouvez imposer l'une des deux dans votre projet avec settings.styleValueSyntax.

Runtime natif et compilateur

• Runtime de style natif (bêta, optionnel) : @tamagui/native-registry applique les changements de thème directement sur les vues Fabric, sans re-render React. Il faut React Native 0.82+ avec la New Architecture, Nitro Modules et experimental.nativeFastPath.
• Compilateur plus malin : il aplatit maintenant les ternaires imbriqués, les conditions logiques, les spreads statiques, les variantes styled.dynamic() et les chaînes .resolve() quand les valeurs sont connues au build.
• Zero-runtime sur le web (expérimental) : experimental.zeroRuntime: 'report' indique ce qui pourrait être extrait en CSS statique.

Tailwind et React Strict DOM

@tamagui/tailwind exporte des éléments html qui acceptent des classes Tailwind. Elles sont compilées en CSS atomique sur le web et en styles React Native sur mobile.

import { html } from '@tamagui/tailwind'

<html.div className="flex flex-row items-center gap-3 p-4 rounded-lg bg-slate-100" />
    

Autres nouveautés notables

• Config v6 : les clés de thème en plusieurs mots passent en kebab-case (border-color, background-hover).
• Language server : @tamagui/lsp apporte autocomplétion, diagnostics, survol par thème et aperçu des couleurs dans tout éditeur compatible LSP.
• Formulaires : nouvelles primitives Field et Form, avec validation via Zod 4, Valibot ou ArkType.
• Select : sélection multiple avec multiple et nouveau Select.Separator.
• Icônes : npx @tamagui/cli icons add génère uniquement les icônes utilisées. Le package Lucide intégré (environ 1700 icônes) est supprimé.
• Outillage : @tamagui/cli/vite et @tamagui/cli/metro remplacent les plugins de bundler séparés.

Breaking changes

• Les tokens $true sont remplacés par des tailles nommées de xs à xl (par défaut md), et le token stepping disparaît.
• Les demi-tokens changent de nom : $0.5 devient 0-5.
• Props supprimées : focusable (utilisez tabIndex), fullscreen, themeInverse (utilisez theme="inverse").
• Hooks et API supprimés : useProps, usePropsAndStyle, styleable et defaultProps dans createTamagui.
• Sheet.Frame est séparé en Sheet.Container et Sheet.Background.
• onDidAnimate est remplacé par onTransition.

Comment migrer vers Tamagui 3

Le CLI fait l'essentiel du travail. Lancez d'abord le codemod en mode rapport pour voir ce qu'il va modifier.

# Nouveau projet
yarn dlx @tamagui/cli setup

# Projet existant (utilisez --from v1 si vous êtes encore en v1)
yarn dlx @tamagui/cli migrate --from v2
yarn dlx tamagui check
yarn dlx @tamagui/codemod-flat-values --write --report flat-values-report.md ./src
    

Ajoutez ensuite tamagui check --strict à votre CI. Si vous utilisez les safe areas natives, placez SafeAreaProvider en dehors de TamaguiProvider.

Faut-il passer à Tamagui 3 ?

Pour un nouveau projet, oui. Pour une app existante, les outils de migration sont solides, mais la suppression des tokens et des props touche beaucoup de fichiers : prévoyez une branche dédiée. Le runtime natif est encore en bêta, vous pouvez donc passer à Tamagui 3 maintenant et l'activer plus tard. Vous découvrez la librairie ? Commencez par notre guide qu'est-ce que Tamagui et comment l'utiliser.