Toast <Beta />

<Description>Use to show feedback to user interactions</Description>

tsx

Installation

Run the following command:

yarn add @tamagui/toast burnt

then, 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.

Usage

To display the toast natively, you should either pass an array of native platforms (native: ["ios", "web"]), a single platform or true for all platforms.

tsx

import { Button } from 'tamagui' // or '@tamagui/button'
import { Toast, ToastProvider, useToast } from '@tamagui/toast'

export default () => (
  <ToastProvider native={['mobile']}>
    <CurrentToast />
    <MyPage />
    <ToastViewport />
  </ToastProvider>
)

const CurrentToast = () => {
  const { currentToast } = useToast()

  // only show the component if it's present and not handled by native toast
  if (!currentToast || currentToast.isHandledNatively) return null
  return (
    <Toast key={currentToast.id}>
      <Toast.Title>{currentToast.title}</Toast.Title>
      <Toast.Description>{currentToast.message}</Toast.Description>
    </Toast>
  )
}

const MyPage = () => {
  const { show } = useToast()

  return (
    <Button onPress={() => show('Done!', { message: 'Form submitted successfully.' })}>
      Show Toast
    </Button>
  )
}

API

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:

Toast

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.

Toast.Description

Should be used inside Toast. Extends SizableText.

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.

useToast

Should be used inside ToastProvider.

FAQ

How to change the placement of toasts?

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.

Non-native 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>

How to show non-native toasts within safe area on mobile?

Install react-native-safe-area-context if you haven't, wrap your app inside <SafeAreaProvider>, and 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} />
  )
}

Can I send toasts to different toast viewports?

Yes, but you will have to name them and then reference the viewport name on the <Toast> component. for instance:

tsx

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

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

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

How can I have more control over toasts?

You will have to opt-out of the native toasts and only use custom ones. Here are some examples:

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>
  )
}