Toast

A toast is a modal overlay that displays alerts or notifications, crucial for user updates.

Installation

API Reference

Important Note

This is the documentation for gluestack-ui v2 (beta). For @gluestack-ui/themed (stable) documentation, refer to gluestack-ui v1.

This is an illustration of Toast component.

action

variant

function Example() {
  const toast = useToast()
  const [toastId, setToastId] = React.useState(0)
  const handleToast = () => {
    if (!toast.isActive(toastId)) {
      showNewToast()
    }
  }
  const showNewToast = () => {
    const newId = Math.random()
    setToastId(newId)
    toast.show({
      id: newId,
      placement: "top",
      duration: 3000,
      render: ({ id }) => {
        const uniqueToastId = "toast-" + id
        return (
          <Toast nativeID={uniqueToastId} action="muted" variant="solid">
            <ToastTitle>Hello!</ToastTitle>
            <ToastDescription>
              This is a customized toast message.
            </ToastDescription>
          </Toast>
        )
      },
    })
  }
  return (
    <Button onPress={handleToast}>
      <ButtonText>Press Me</ButtonText>
    </Button>
  )
}

Installation

CLI

Manual

Run the following command:

npx gluestack-ui add toast

Step 1: Install the following dependencies:

npm i @gluestack-ui/toast

Step 2: Copy and paste the following code into your project.

"use client"
import React from "react"
import { createToast, createToastHook } from "@gluestack-ui/toast"
import { Text, View, Platform } from "react-native"
import { tva } from "@gluestack-ui/nativewind-utils/tva"
import { cssInterop } from "nativewind"
import { Motion, AnimatePresence } from "@legendapp/motion"
import {
  withStyleContext,
  useStyleContext,
} from "@gluestack-ui/nativewind-utils/withStyleContext"
import { withStyleContextAndStates } from "@gluestack-ui/nativewind-utils/withStyleContextAndStates"
import type { VariantProps } from "@gluestack-ui/nativewind-utils"

export const useToast = createToastHook(Motion.View, AnimatePresence)
const SCOPE = "TOAST"
export const UIToast = createToast({
  Root:
    Platform.OS === "web"
      ? withStyleContext(View, SCOPE)
      : withStyleContextAndStates(View, SCOPE),
  Title: Text,
  Description: Text,
})

cssInterop(Motion.View, { className: "style" })
cssInterop(UIToast, { className: "style" })
cssInterop(UIToast.Title, { className: "style" })
cssInterop(UIToast.Description, { className: "style" })

const toastStyle = tva({
  base: "p-4 m-1 rounded-md gap-1 web:pointer-events-auto shadow-hard-5 border-outline-100",
  variants: {
    action: {
      error: "bg-error-800",
      warning: "bg-warning-700",
      success: "bg-success-700",
      info: "bg-info-700",
      muted: "bg-secondary-700",
    },

    variant: {
      solid: "",
      outline: "border bg-background-0",
    },
  },
})

const toastTitleStyle = tva({
  base: "text-typography-0 font-medium font-body tracking-md text-left",
  variants: {
    isTruncated: {
      true: "",
    },
    bold: {
      true: "font-bold",
    },
    underline: {
      true: "underline",
    },
    strikeThrough: {
      true: "line-through",
    },
    size: {
      "2xs": "text-2xs",
      xs: "text-xs",
      sm: "text-sm",
      md: "text-base",
      lg: "text-lg",
      xl: "text-xl",
      "2xl": "text-2xl",
      "3xl": "text-3xl",
      "4xl": "text-4xl",
      "5xl": "text-5xl",
      "6xl": "text-6xl",
    },
  },
  parentVariants: {
    variant: {
      solid: "",
      outline: "",
    },
    action: {
      error: "",
      warning: "",
      success: "",
      info: "",
      muted: "",
    },
  },
  parentCompoundVariants: [
    {
      variant: "outline",
      action: "error",
      class: "text-error-800",
    },
    {
      variant: "outline",
      action: "warning",
      class: "text-warning-800",
    },
    {
      variant: "outline",
      action: "success",
      class: "text-success-800",
    },
    {
      variant: "outline",
      action: "info",
      class: "text-info-800",
    },
    {
      variant: "outline",
      action: "muted",
      class: "text-background-800",
    },
  ],
})

const toastDescriptionStyle = tva({
  base: "font-normal font-body tracking-md text-left",
  variants: {
    isTruncated: {
      true: "",
    },
    bold: {
      true: "font-bold",
    },
    underline: {
      true: "underline",
    },
    strikeThrough: {
      true: "line-through",
    },
    size: {
      "2xs": "text-2xs",
      xs: "text-xs",
      sm: "text-sm",
      md: "text-base",
      lg: "text-lg",
      xl: "text-xl",
      "2xl": "text-2xl",
      "3xl": "text-3xl",
      "4xl": "text-4xl",
      "5xl": "text-5xl",
      "6xl": "text-6xl",
    },
  },
  parentVariants: {
    variant: {
      solid: "text-typography-50",
      outline: "text-typography-900",
    },
  },
})

type IToastProps = React.ComponentProps<typeof UIToast> & {
  className?: string
} & VariantProps<typeof toastStyle>

export const Toast = React.forwardRef<
  React.ElementRef<typeof UIToast>,
  IToastProps
>(({ className, variant = "solid", action = "muted", ...props }, ref) => {
  return (
    <UIToast
      ref={ref}
      className={toastStyle({ variant, action, class: className })}
      context={{ variant, action }}
      {...props}
    />
  )
})

type IToastTitleProps = React.ComponentProps<typeof UIToast.Title> & {
  className?: string
} & VariantProps<typeof toastTitleStyle>

export const ToastTitle = React.forwardRef<
  React.ElementRef<typeof UIToast.Title>,
  IToastTitleProps
>(({ className, size = "md", ...props }, ref) => {
  const { variant: parentVariant, action: parentAction } =
    useStyleContext(SCOPE)
  return (
    <UIToast.Title
      ref={ref}
      {...props}
      className={toastTitleStyle({
        size,
        class: className,
        parentVariants: {
          variant: parentVariant,
          action: parentAction,
        },
      })}
    />
  )
})

type IToastDescriptionProps = React.ComponentProps<
  typeof UIToast.Description
> & {
  className?: string
} & VariantProps<typeof toastDescriptionStyle>

export const ToastDescription = React.forwardRef<
  React.ElementRef<typeof UIToast.Description>,
  IToastDescriptionProps
>(({ className, size = "md", ...props }, ref) => {
  const { variant: parentVariant } = useStyleContext(SCOPE)
  return (
    <UIToast.Description
      ref={ref}
      {...props}
      className={toastDescriptionStyle({
        size,
        class: className,
        parentVariants: {
          variant: parentVariant,
        },
      })}
    />
  )
})

Step 3: Update the import paths to match your project setup.

API Reference

To use this component in your project, include the following import statement in your file.

import { useToast, Toast } from "@/components/ui/toast"

export default () => (
  <Toast>
    <ToastTitle />
    <ToastDescription />
  </Toast>
)

Component Props

This section provides a comprehensive reference list for the component props, detailing descriptions, properties, types, and default behavior for easy project integration.

Toast

It inherits all the properties of React Native's View component.

Prop	Type	Default	Description
duration	number or null	5000	The delay before the toast hides (in milliseconds). If set to null, toast will never dismiss.
onCloseComplete	()=>{}	-	Callback function to run side effects after the toast has closed.
placement	'top'\| 'top right' \| 'top left' \| 'bottom' \| 'bottom left' \| 'bottom right'	bottom	Position of toast on the web page.
render?: (props: any)	ReactNode	-	Renders a toast component
avoidKeyboard	bool	false	If true and the keyboard is opened, the Toast will move up equivalent to the keyboard height.
containerStyle	ViewStyle	-	Container style object for the toast.

ToastTitle

Contains all Text related layout style props and actions. It inherits all the properties of React Native's Text component.

ToastDescription

Contains all Text related layout style props and actions. It inherits all the properties of React Native's Text component.

Accessibility

We have outlined the various features that ensure the Toast component is accessible to all users, including those with disabilities. These features help ensure that your application is inclusive and meets accessibility standards.Adheres to the WAI-ARIA design pattern.

Keyboard

Tab + Enter: Triggers the toast's action.

VoiceOver: When the toast is focused, the screen reader will announce the toast's title.

Props

Toast component is created using View component from react-native. It extends all the props supported by React Native View and the props mentioned below.

Toast

Name	Value	Default
action	error \| warning \| success \| info \| attention	attention
variant	solid \| outline \| accent	solid

Examples

The Examples section provides visual representations of the different variants of the component, allowing you to quickly and easily determine which one best fits your needs. Simply copy the code and integrate it into your project.

Toast in note talking platform

function Example() {
  const toast = useToast()
  const [toastId, setToastId] = React.useState(0)
  const handleToast = () => {
    if (!toast.isActive(toastId)) {
      showNewToast()
    }
  }
  const showNewToast = () => {
    const newId = Math.random()
    setToastId(newId)
    toast.show({
      id: newId,
      placement: "top",
      duration: 3000,
      render: ({ id }) => {
        const uniqueToastId = "toast-" + id
        return (
          <Toast
            action="error"
            variant="outline"
            nativeID={uniqueToastId}
            className="p-4 gap-6 border-error-500 w-full shadow-hard-5 max-w-[443px] flex-row justify-between"
          >
            <HStack space="md">
              <Icon as={HelpCircleIcon} className="stroke-error-500 mt-0.5" />
              <VStack space="xs">
                <ToastTitle className="font-semibold text-error-500">
                  Error!
                </ToastTitle>
                <ToastDescription size="sm">
                  Something went wrong.
                </ToastDescription>
              </VStack>
            </HStack>
            <HStack className="min-[450px]:gap-3 gap-1">
              <Button variant="link" size="sm" className="px-3.5 self-center">
                <ButtonText>Retry</ButtonText>
              </Button>
              <Pressable onPress={() => toast.close(id)}>
                <Icon as={CloseIcon} />
              </Pressable>
            </HStack>
          </Toast>
        )
      },
    })
  }
  return (
    <Button onPress={handleToast}>
      <ButtonText>Press Me</ButtonText>
    </Button>
  )
}

function Example() {
  const toast = useToast()
  return (
    <Button
      onPress={() => {
        toast.show({
          placement: "top",
          render: ({ id }) => {
            const toastId = "toast-" + id
            return (
              <Toast
                nativeID={toastId}
                className="p-4 gap-3 w-full sm:min-w-[386px] bg-background-0 shadow-hard-2 flex-row"
              >
                <Avatar>
                  <AvatarFallbackText>JS</AvatarFallbackText>
                  <AvatarImage
                    source={{
                      uri: "https://s3-alpha-sig.figma.com/img/cc35/9a95/ecf9cba1881effe726061fc6f4809371?Expires=1721001600&Key-Pair-Id=APKAQ4GOSFWCVNEHN3O4&Signature=Pyj83N4SzedRQj~mtWMGxuhBcBMcuGc6ppsgWMnKDu2iEEcD-NQaE2WHgwqq6k7uHxzBd~gecQN2HXDrkVTlxvryARvD8Ai5RkaicN8OdqqHojHdmT8y1Q1IPKjSf0HxHA0EgkkTS8RLqRXBwrXV6IaGsVKNxche92mdvCt0llYhzeQO0xLYOYIDUiOXONpcpP72QgRMZLbU3Ep2thUnwl6VuxFiphQPOKkLLUEeGhQF5KDQB71NG09Ypq2V3okej6dtPb0eo~IunDKiFIfDUwrj~2fD6Y~JRrVhmSIXloZlAPwCd37NwzT-Jl8pR4JIWqF4dRigx67HOSUExrezJg__",
                    }}
                  />
                </Avatar>
                <VStack className="w-full">
                  <HStack className="justify-between w-full">
                    <Heading
                      size="sm"
                      className="text-typography-950 font-semibold"
                    >
                      Jacob Steve
                    </Heading>
                    <Text size="sm" className="text-typography-500">
                      2m ago
                    </Text>
                  </HStack>
                  <Text size="sm" className="text-typography-500">
                    commented on your photo
                  </Text>
                </VStack>
              </Toast>
            )
          },
        })
      }}
    >
      <ButtonText>Show Toast</ButtonText>
    </Button>
  )
}

Software update toast

function Example() {
  const toast = useToast()
  const [toastId, setToastId] = React.useState(0)
  const handleToast = () => {
    if (!toast.isActive(toastId)) {
      showNewToast()
    }
  }
  const showNewToast = () => {
    const newId = Math.random()
    setToastId(newId)
    toast.show({
      id: newId,
      placement: "top",
      duration: 3000,
      render: ({ id }) => {
        const uniqueToastId = "toast-" + id
        return (
          <Toast
            nativeID={uniqueToastId}
            className="p-4 gap-4 w-full max-w-[386px] bg-background-0 shadow-hard-2 flex-row"
          >
            <Box className="h-11 w-11 items-center justify-center hidden min-[400px]:flex bg-background-50">
              {/* RefreshCw is imported from 'lucide-react-native' */}
              <Icon
                as={RefreshCw}
                size="xl"
                className="stroke-background-800"
              />
            </Box>
            <VStack space="xl">
              <VStack space="xs">
                <HStack className="justify-between">
                  <ToastTitle className="text-typography-900 font-semibold">
                    Update available
                  </ToastTitle>
                  <Pressable onPress={() => toast.close(id)}>
                    <Icon as={CloseIcon} className="stroke-background-500" />
                  </Pressable>
                </HStack>
                <ToastDescription className="text-typography-700">
                  A new software version is available for download.
                </ToastDescription>
              </VStack>
              <ButtonGroup className="gap-3 flex-row">
                <Button
                  action="secondary"
                  variant="outline"
                  size="sm"
                  className="flex-grow"
                >
                  <ButtonText>Not now</ButtonText>
                </Button>
                <Button size="sm" className="flex-grow">
                  <ButtonText>Update</ButtonText>
                </Button>
              </ButtonGroup>
            </VStack>
          </Toast>
        )
      },
    })
  }
  return (
    <Button onPress={handleToast}>
      <ButtonText>Press Me</ButtonText>
    </Button>
  )
}

Message sent toast

function Example() {
  const toast = useToast()
  return (
    <Button
      onPress={() => {
        toast.show({
          placement: "top",
          render: ({ id }) => {
            const toastId = "toast-" + id
            return (
              <Toast
                nativeID={toastId}
                className="px-5 py-3 gap-4 shadow-soft-1 items-center flex-row"
              >
                {/* Send is imported from 'lucide-react-native' */}
                <Icon
                  as={Send}
                  size="xl"
                  className="fill-typography-100 stroke-none"
                />
                <Divider
                  orientation="vertical"
                  className="h-[30px] bg-outline-200"
                />
                <ToastTitle size="sm">Message sent successfully</ToastTitle>
              </Toast>
            )
          },
        })
      }}
    >
      <ButtonText>Show Toast</ButtonText>
    </Button>
  )
}

Toast

Installation

Run the following command:

Step 1: Install the following dependencies:

Step 2: Copy and paste the following code into your project.

Step 3: Update the import paths to match your project setup.

API Reference

Component Props

Toast

ToastTitle

ToastDescription

Accessibility

Keyboard

Screen Reader

Props

Toast

Examples

Toast in note talking platform

Social media notification

Software update toast

Message sent toast