Toast

Toast presents time-sensitive messages with accessible announcements, stacking, gestures, and animated entry or exit.

Installation

Toast ships with tamagui: there’s nothing extra to install:

import { Toast, toast } from 'tamagui/toast'
Copy

If you’re using the unstyled primitives directly, it’s also published on its own:

yarn
npm
bun
pnpm
Copy
yarn add @tamagui/toast

Native OS toasts are opt-in. By default toasts render as in-app Tamagui views on every platform, so adding Toast to your app never pulls in a native dependency. See Native toasts if you want the real iOS/Android system toast.

Quick start

Toast is a composable component API: you mount the parts, and toast() drives them from anywhere in your app.

import { Button } from 'tamagui/button'
import { Toast, toast } from 'tamagui/toast'

function App() {
  return (
    <Toast position="bottom-right">
      <Toast.Viewport>
        <Toast.List />
      </Toast.Viewport>

      <Button onPress={() => toast('Hello!')}>Show Toast</Button>
    </Toast>
  )
}
Copy

Mount this inside your TamaguiProvider, usually next to your app navigation or root layout. toast() is global, so callers don’t need to be inside <Toast>.

<Toast.List /> renders the default styled toast. Pass renderItem to own the markup completely:

<Toast.List
  renderItem={({ toast: t, index }) => (
    <Toast.Item key={t.id} toast={t} index={index}>
      <Toast.Title>{t.title}</Toast.Title>
      <Toast.Description>{t.description}</Toast.Description>
      <Toast.Close />
    </Toast.Item>
  )}
/>
Copy

Omit renderItem and Toast.List renders the default styled toast content.

Anatomy

<Toast>             {/* Root - context and position */}
  <Toast.Viewport>  {/* Container with portal */}
    <Toast.Item>    {/* Individual toast with stacking/drag */}
      <Toast.Title />
      <Toast.Description />
      <Toast.Close />
      <Toast.Action />
    </Toast.Item>
  </Toast.Viewport>
</Toast>
Copy

API reference

The imperative toast function:

// Basic
toast('Hello world')

// With types
toast.success('Saved!')
toast.error('Failed')
toast.warning('Careful')
toast.info('FYI')
toast.loading('Processing...')

// With options
toast('Message', {
  description: 'More details here',
  duration: 5000,
})

// Dismiss
const id = toast('Hello')
toast.dismiss(id) // dismiss specific
toast.dismiss()   // dismiss all
Copy

For async operations:

toast.promise(saveData(), {
  loading: 'Saving...',
  success: 'Saved!',
  error: 'Failed to save',
})
Copy

The portal container for toasts. Extends View.

Individual toast wrapper with stacking and drag support. Extends View.

Supports render prop for custom content:

<Toast.Item toast={t} index={i}>
  {({ toast, handleClose }) => (
    <YStack>
      <Toast.Title>{toast.title}</Toast.Title>
      <Button onPress={handleClose}>Close</Button>
    </YStack>
  )}
</Toast.Item>
Copy

Styled text for the toast title. Extends SizableText.

Styled text for the toast description. Extends SizableText.

Close button. Extends View.

Action button. Extends View.

Hook to access toast state from a descendant of <Toast>. Most apps should use <Toast.List> for rendering and reach for this hook only when they need custom list control.

const { toasts, expanded, position } = useToasts()
Copy

Features

Multiple toasts stack visually. Hover over the stack to expand and see all toasts.

Toasts can be swiped away. The direction is auto-detected based on position:

• Web: Left/right positioned toasts swipe toward their edge, center toasts swipe horizontally
• Native: All positions swipe vertically (up/down) to avoid conflicting with iOS/Android navigation back gesture

When react-native-gesture-handler is set up via @tamagui/native/setup-gesture-handler, the toast uses native gesture coordination (activeOffsetY, failOffsetX) to prevent ScrollView from scrolling while swiping.

Toasts render as in-app Tamagui views on every platform by default. To use the real iOS/Android system toast instead, install Burnt and import its setup module at your app entry:

yarn
npm
bun
pnpm
Copy
yarn add burnt

import '@tamagui/native/setup-burnt'
Copy

Then opt in on the root:

<Toast native>{/* ... */}</Toast>
Copy

Burnt is resolved lazily, so apps that don’t set it up never load it and never need the native module.

On native, toasts portal to root and automatically respect safe area insets (status bar, Dynamic Island, home indicator) when configured:

import { SafeAreaProvider } from 'react-native-safe-area-context'
import { useSafeAreaInsets } from 'react-native-safe-area-context'
import { TamaguiProvider } from 'tamagui'

function App() {
  return (
    <SafeAreaProvider>
      <AppInner />
    </SafeAreaProvider>
  )
}

function AppInner() {
  const insets = useSafeAreaInsets()
  return (
    <TamaguiProvider config={config} insets={insets}>
      {/* toasts will automatically avoid status bar and home indicator */}
    </TamaguiProvider>
  )
}
Copy

The toast reads insets from TamaguiProvider via useConfiguration().insets, the same mechanism used by other Tamagui components like Slider.

Each part can be styled independently:

<Toast.Item toast={t} index={i} backgroundColor="blue-100" borderRadius="6">
  <Toast.Title color="blue-950" fontWeight="bold">
    {t.title}
  </Toast.Title>
  <Toast.Description color="blue-800">
    {t.description}
  </Toast.Description>
</Toast.Item>
Copy

Migrating from v2

The v2 imperative API (ToastProvider, ToastViewport, useToastController, useToastState) was removed. Replace the provider tree with the composable parts shown above, and call toast() directly instead of going through a controller hook:

// v2
const toast = useToastController()
toast.show('Saved!', { message: 'Your changes are live' })

// v3
toast('Saved!', { description: 'Your changes are live' })
Copy

See the upgrade guide for the full migration.