GitHub
Install
Stacks
Headings
Text
Native
Z-Index

Native UI

Optional native integrations for better performance and UX

Native Integrations

Tamagui components work great out of the box, but several offer optional native integrations for improved performance and platform-native UX. All native integrations are opt-in - components work without them, just with slightly different behavior.

@tamagui/native Package

The @tamagui/native package provides setup utilities for native integrations. Import the setup modules at your app’s entry point, before any Tamagui imports.

yarn add @tamagui/native

@tamagui/native is a light setup package. When you use one of its optional integrations, make sure the matching native dependency is installed in your app as well, such as react-native-gesture-handler, react-native-teleport, zeego, or burnt. In a monorepo, install those native packages in the parent app or workspace root rather than a leaf package.

Portal

Native portals preserve React context - the default implementation on native uses a JS-based approach that breaks React context, or requires you to hoist data awkwardly. With native portals, your custom contexts (navigation, app state) work inside Sheet, Dialog, Popover, and other portaled content.

Setup

 
yarn add react-native-teleport
// App.tsx - before any Tamagui imports

import '@tamagui/native/setup-teleport'

See Portal docs for full details.

Gesture Handler

Native gesture handling - powers two features:

  1. Press events - onPress uses RNGH for more reliable press detection with proper gesture coordination. Matches RN Pressable semantics where only the innermost pressable fires (no double-firing with nested buttons).

  2. Sheet gestures - makes sheets feel smoother and not get confused with scrollable content during drags.

Setup

 
yarn add react-native-gesture-handler
// App.tsx - before any Tamagui imports

import '@tamagui/native/setup-gesture-handler'

import { GestureHandlerRootView } from 'react-native-gesture-handler'



export default function App() {

  return (

    <GestureHandlerRootView style={{ flex: 1 }}>{/* Your app */}</GestureHandlerRootView>

  )

}

Selective Features

If you only want RNGH for specific features, use the configurable setup:

import { setupGestureHandler } from '@tamagui/native/setup-gesture-handler'



// only use RNGH for sheets, not press events

setupGestureHandler({ pressEvents: false, sheet: true })



// only use RNGH for press events, not sheets

setupGestureHandler({ pressEvents: true, sheet: false })

Press Event Behavior

With RNGH enabled, onPress follows RN Pressable semantics:

  • Nested pressables - only the innermost fires (no event bubbling)
  • Web parity - onPress calls stopPropagation() automatically
  • Use onClick on web if you need standard DOM event bubbling

This aligns to the React Native default behavior of Pressable.

PressBoundary

If you need a non-Tamagui native wrapper to block a parent Tamagui pressable, use PressBoundary from @tamagui/native/gesture-handler.

This is useful when mixing Tamagui pressables with React Native Pressable, custom native wrappers, or other components that don’t use Tamagui’s native press ownership automatically.

import { PressBoundary } from '@tamagui/native/gesture-handler'

import { Pressable } from 'react-native'



export function AvatarLink() {

  return (

    <PressBoundary debugName="AvatarLink">

      <Pressable onPress={() => {}}>

        {/* your content */}

      </Pressable>

    </PressBoundary>

  )

}

PressBoundary only coordinates with Tamagui’s native press ownership. It does not monkey-patch React Native bubbling semantics in general.

Native Menu.Trigger and ContextMenu.Trigger already do this automatically, so you should not need extra wrappers or empty onPress handlers around them.

See Sheet docs for full details.

Menu & ContextMenu

Native menus - renders platform-native context menus instead of custom overlays. Uses iOS’s native menu API for haptics, blur effects, and system integration.

Setup

 
yarn add zeego @react-native-menu/menu react-native-ios-context-menu react-native-ios-utilities sf-symbols-typescript
// App.tsx - before any Tamagui imports

import '@tamagui/native/setup-zeego'

Then use the native prop:

<Menu native>{/* menu content */}</Menu>

See Menu docs and ContextMenu docs for full details.

Toast

Native toasts - uses platform-native toast implementations:

  • iOS: SPIndicator (system-style indicators)
  • Android: ToastAndroid
  • Web: Notification API

Setup

 
yarn add burnt
// App.tsx - before any Tamagui imports

import '@tamagui/native/setup-burnt'

Then use the native prop on ToastProvider:

<Toast.Provider native>{/* your app */}</Toast.Provider>

See Toast docs for full details.

LinearGradient

Native gradients - uses expo-linear-gradient for high-performance native gradient rendering.

Setup

 
yarn add expo-linear-gradient
// App.tsx - before any Tamagui imports

import '@tamagui/native/setup-expo-linear-gradient'

See LinearGradient docs for full details.

Previous

Text

Next

Z-Index

Edit this page on GitHub.