Toast

A toast is a short message on a surface card that hides itself after six seconds. Wrap the app in ToastProvider, then call addToast({ variant, message }) from useToast anywhere under it, as on the web. See the web Toast for the same component in the browser.

Setup

Put ToastProvider inside ThemeProvider, around the rest of the app. It draws the toasts above everything in it, stacked at the bottom of the screen with the newest last.

App.tsx

import { Column, Text, ThemeProvider, ToastProvider } from "@once-ui-system/native";

export default function App() {
return (
  <ThemeProvider>
    <ToastProvider>
      <Column fill background="page" padding="20">
        <Text>Your app</Text>
      </Column>
    </ToastProvider>
  </ThemeProvider>
);
}

Add a toast

variant sets the icon: success, danger, warning or info. Each toast has a close button.

SaveButton.tsx

import { Button, useToast } from "@once-ui-system/native";

export function SaveButton() {
const { addToast } = useToast();
return (
  <Button
    label="Save"
    onPress={() => addToast({ variant: "success", message: "Changes saved" })}
  />
);
}

Action and duration

action adds an element before the close button, such as an undo button. duration is in milliseconds; Infinity keeps the toast until it is closed.

ArchiveButton.tsx

import { Button, useToast } from "@once-ui-system/native";

export function ArchiveButton() {
const { addToast } = useToast();
return (
  <Button
    label="Archive"
    variant="secondary"
    onPress={() =>
      addToast({
        variant: "info",
        message: "Conversation archived",
        action: <Button size="s" variant="tertiary" label="Undo" onPress={() => {}} />,
        duration: 10000,
      })
    }
  />
);
}

A single toast

Toast also renders on its own, where you place it. It hides itself after duration and calls onClose. Without onClose it has no close button.

OfflineNotice.tsx

import { Toast } from "@once-ui-system/native";

export function OfflineNotice() {
return (
  <Toast variant="warning" duration={Infinity} showIcon>
    You are offline. Changes will sync later.
  </Toast>
);
}

Differences from the web

useToast throws outside a ToastProvider.
Toasts sit above the home indicator when the safe-area insets are passed to ThemeProvider, as shown on the overview.
A danger toast is announced right away; the others wait for the screen reader to finish.

API reference

useToast

Field	Type	Description
addToast	(toast: ToastOptions) => void	Shows a toast.
removeToast	(id: string) => void	Hides a toast by its id.
toasts	(ToastOptions & { id: string })[]	The toasts on screen.

ToastOptions

Prop	Type	Default	Description
variant	"success" \| "danger" \| "warning" \| "info"		Sets the icon and how it is announced. Required.
message	ReactNode		The text. Required.
action	ReactNode		An element before the close button.
duration	number	6000	Milliseconds before the toast hides itself. Infinity keeps it.

Prop	Type	Default	Description
variant	"success" \| "danger" \| "warning" \| "info"		Sets the icon and how it is announced. Required.
children	ReactNode		The text. Required.
showIcon	boolean	true	Shows the variant's icon.
onClose	() => void		Shows a close button. Also called when the toast hides itself.
action	ReactNode		An element before the close button.
duration	number	6000	Milliseconds before the toast hides itself. Infinity keeps it.
style	ViewStyle		Style for the card.

ToastProvider

Prop	Type	Default	Description
children	ReactNode		The app. Required.