Tamagui v2 brings Config v5 and new components
Tamagui v2 is out. Its announcement, written for the first release candidate, describes the migration from v1 as moderate. Most of the removals are deprecated APIs, and the release aligns more closely with web standards and modern React Native.
Config and styles
The default configuration moves to Config v5. It adds gray, orange, pink, purple, teal and neutral palettes built on Radix Colors v3, along with these additions:
- Opacity tokens such as
$color01and$background01 - Shadow tokens
$shadow1through$shadow6 - Height-based media queries and a
$pointerTouchquery $smthrough$xxlbreakpoints that match Tailwind CSS- A
createV5Themehelper for customizing themes
New style props include backgroundImage, boxShadow, filter, mixBlendMode, isolation, boxSizing, borderCurve, cursor, textShadow, border and outline. position now accepts fixed, which is converted to absolute on native.
Components
A new Menu component renders native platform menus on iOS and Android, and the new ContextMenu works like it, opening on right-click on web or long-press on native. Input has been rewritten so it takes web-standard attributes such as type="email". Image uses <img>-style attributes and supports adapters like expo-image.
Sheet, Button, ListItem and Select were rewritten internally. Button now has about 60% less code. Switch, Checkbox, ToggleGroup.Item and Tabs.Tab share consistent activeStyle and activeTheme props. Dialog, Popover, Sheet and Tooltip support a scope prop, which lets a single instance mounted at the app root serve triggers placed anywhere in the tree.
Some components now have headless variants that provide hooks like useSwitch and useTabs. A new @tamagui/react-native-web-lite package is also available.
Animations
A Motion animation driver has been added. The announcement calls it still somewhat experimental. The Reanimated driver now supports worklets and the new avoidReRenders path. @tamagui/animations-moti is deprecated in favor of @tamagui/animations-reanimated.
Other animation changes:
- An
animatedByprop lets each component choose its animation driver. loadAnimationDriverenables lazy loading of drivers.- All drivers support transition delays.
- Separate
enterandexittransitions can be set. - Pseudo-style props accept their own
transition.
Native, compiler and CLI
Portal components can use true native portals via react-native-teleport with import '@tamagui/native/setup-teleport'. Sheet can optionally integrate with react-native-gesture-handler. Pointer events now work cross-platform.
The compiler's theme optimization is now on by default. New CLI commands include tamagui build, tamagui generate, tamagui generate-css, tamagui generate-prompt and tamagui check. The @tamagui/core bundle has shrunk by about 32%, from roughly 37KB to 25KB gzipped.
Breaking changes
Tamagui 2 requires React Native 0.81+, React 19+ and TypeScript 5+, with New Architecture support. Other breaking changes include:
- The
animationprop is renamed totransition. Stack,spaceandspaceDirectionare removed.- React Native accessibility props are replaced by web-standard equivalents such as
aria-label. - Tabs
activationModenow defaults to'manual'. - Group now requires
Group.Item.
Testing and plans
The team rebuilt its testing setup around Playwright, Vitest, Jest + Detox and Maestro. Every Playwright UI test runs once for each of the four animation drivers. The team plans to deprecate a number of APIs in 2.1 ahead of 3.0, and says 3.0 will follow more quickly than this major release did.
Example
// Config with multiple drivers up front
createTamagui({
animations: {
default: cssDriver,
spring: reanimatedDriver,
},
})
// Select per-component - compiler can optimize knowing the driver
<View animatedBy="spring" transition="bouncy" />
Links
Source: tamagui.dev