Toast

tsx

Installation

Note that @tamagui/toast is the only UI package not included by default in tamagui. The reason for this is that Metro would force you to install the native burnt dependency, and that would mean tamagui wouldn't work with Expo Go and would require a native install step no matter if you used Toast or not. This is due to a limitation in Metro.

To install toast:

bash

yarn add @tamagui/toast burnt

Then, if targeting native, rebuild your React Native app. React Native requires sub-dependencies with native dependencies always be hoisted to your apps package.json and Toast relies on the amazing Burnt library by Fernando Rojo to provide its native functionality.

We're open to a refactor that moves the burnt dependency into a sub-path like @tamagui/toast/burnt and forces setup through there, that likely fixes the Metro issue and allow us to include it by default.

Anatomy

tsx

<ToastProvider>
  <Toast>
    <Toast.Title />
    <Toast.Description />
    <Toast.Action />
    <Toast.Close />
  </Toast>

  <ToastViewport />
</ToastProvider>

API Reference

ToastProvider

Your toasts should be wrapped within a ToastProvider. This is usually done at the root of your application.

<PropsTable data={[ { name: 'label', required: false, type: 'string', description: An author-localized label for each toast. Used to help screen reader users associate the interruption with a toast., default: 'Notification', }, { name: 'duration', required: false, type: 'number', description: Time in milliseconds that each toast should remain visible for. This could be overwritten at the toast level as well., default: 5000, }, { name: 'swipeDirection', required: false, type: 'SwipeDirection', description: Direction of pointer swipe that should close the toast., default: 'right', }, { name: 'swipeThreshold', required: false, type: 'number', description: Distance in pixels that the swipe must pass before a close is triggered., default: 50, }, { name: 'id', required: false, type: 'string', default: 'A unique generated ID', }, { name: 'native', required: false, type: 'boolean | ToastNativePlatform | ToastNativePlatform[]', description: Will show a native toast if is true or is set to the current platform. On iOS, it wraps \SPIndicator` and `SPAlert`. On Android, it wraps `ToastAndroid`. On web, it wraps Notification API. Mobile's native features are handled by `burnt`., }, { name: burntOptions, required: false, type: Omit<BurntToastOptions, 'title' | 'message' | 'duration'>, description: Options for the burnt package if you're using native toasts on mobile, }, { name: notificationOptions, required: false, type: NotificationOptions, description: Options for the notification API if you're using native toasts on web`, }, ]} />

ToastViewport

The portal for toasts to be directed to. Should be used inside ToastProvider. Beyond Stack Props, adds:

Contains the Title, Description, Action and Close component. Should be used inside ToastProvider. Extends Stack and adds:

Toast.Title

Should be used inside Toast. Extends SizableText, adding:

Toast.Description

Should be used inside Toast. Extends SizableText, adding:

Toast.Close

Should be used inside Toast. Extends Stack. You can pass asChild to this component and use a custom <Button> inside.

Toast.Action

Should be used inside Toast. Extends Stack. You can pass asChild to this component and use a custom <Button> inside.

useToastController

Used to control the display of toasts. Should be used inside ToastProvider.

useToastState

Used to render out your toast contents. Should be used inside ToastProvider. Doesn't take in anything and returns ToastData.

tsx

const CurrentToast = () => {
  const toast = useToastState()

  // don't show any toast if no toast is present or it's handled natively
  if (!toast || toast.isHandledNatively) {
    return null
  }

  return (
    <Toast key={toast.id} duration={toast.duration} viewport={toast.viewport}>
      <Toast.Title>{toast.title}</Toast.Title>
      <Toast.Description>{toast.message}</Toast.Description>
    </Toast>
  )
}

Examples

Position the viewport

To position the viewport on native toasts:

iOS (burnt): Supports top or bottom placements. Adjustable by passing from to burntOptions:

tsx

<ToastProvider burntOptions={{ from: 'bottom' }}>

Android (burnt): Not supported.
Web (Notification API): Not supported.

To position the viewport on custom toasts:

You should change the positioning of your <ToastViewport>. For instance, if you want them to appear from top right:

tsx

<ToastViewport flexDirection="column-reverse" top={0} right={0} />

Or for bottom center:

tsx

<ToastViewport flexDirection="column" bottom={0} left={0} right={0} />

<Notice theme="blue"> When using multiple toasts, you can change the order of toasts by setting `flexDirection` to `column` or `column-reverse`. Or even have them stack horizontally using `row` or `row-reverse`. </Notice>

Mobile safe area

To show toasts inside device's safe area, install react-native-safe-area-context if you haven't, wrap your app inside <SafeAreaProvider>, and then use the safe area insets to position the viewport inside the safe area.

tsx

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

const SafeToastViewport = () => {
  const { left, top, right } = useSafeAreaInsets()
  return (
    <ToastViewport flexDirection="column-reverse" top={top} left={left} right={right} />
  )
}

Different viewports

To send toasts to different viewports, you can set up different viewports:

tsx

const App = () => {
  return (
    <ToastProvider>
      <ToastViewport />
      <ToastViewport name="viewport-custom" />
    </ToastProvider>
  )
}

And then, use the viewport's name on the toasts.

tsx

const MyComponent = () => {
  return <Toast /> // default viewport
}

const MyComponent2 = () => {
  return <Toast viewportName="viewport-custom" />
}

Custom data

Just pass your custom data to the second parameter of the show() method.

const toastController = useToastController()
toastController.show('Title', { myPreset: 'error' }) // or toastController.show("Title", { customData: { myPreset: 'error' } })

then, when showing the toast, you can retrieve them like so:

const toastState = useToastState()
toastState.myPreset // or toastState.customData.myPreset

To add TypeScript auto-completion for your custom fields, you can use TS module augmentation:

declare module '@tamagui/toast' {
  interface CustomData {
    myPreset: 'error' | 'success' | 'warning'
  }
}

Without hooks

You can also use toasts without the hooks.

<Notice>You can't use native toasts this way.</Notice>

Single Toast

tsx

export default () => {
  const [open, setOpen] = React.useState(false)
  const timerRef = React.useRef(0)

  React.useEffect(() => {
    return () => clearTimeout(timerRef.current)
  }, [])

  return (
    <YStack ai="center">
      <Button
        onPress={() => {
          setOpen(false)
          window.clearTimeout(timerRef.current)
          timerRef.current = window.setTimeout(() => {
            setOpen(true)
          }, 150)
        }}
      >
        Single Toast
      </Button>
      <Toast
        onOpenChange={setOpen}
        open={open}
        animation="100ms"
        enterStyle={{ x: -20, opacity: 0 }}
        exitStyle={{ x: -20, opacity: 0 }}
        opacity={1}
        x={0}
      >
        <Toast.Title>Subscribed!</Toast.Title>
        <Toast.Description>We'll be in touch.</Toast.Description>
      </Toast>
    </YStack>
  )
}

Multiple Toasts

<Notice> To use multiple toasts, you should pass `multipleToasts` to your `ToastViewport`. Otherwise there'll be issues when swipe-dismissing or animating toasts. </Notice>

tsx

export default () => {
  const [savedCount, setSavedCount] = React.useState(0)

  return (
    <YStack ai="center">
      <Button
        onPress={() => {
          setSavedCount((old) => old + 1)
        }}
      >
        Show toast
      </Button>
      {[...Array(savedCount)].map((_, index) => (
        <Toast
          key={index}
          animation="100ms"
          enterStyle={{ x: -20, opacity: 0 }}
          exitStyle={{ x: -20, opacity: 0 }}
          opacity={1}
          x={0}
        >
          <Toast.Title>Subscribed!</Toast.Title>
          <Toast.Description>We'll be in touch.</Toast.Description>
        </Toast>
      ))}
    </YStack>
  )
}