---
title: Toast | UI
description: Toast displays alerts on top of an overlay.
pageTitle: Toast
pageDescription: Toast displays alerts on top of an overlay.
showHeader: true
---

import { Meta } from '@storybook/addon-docs';

<Meta title="components/Feedback/Toast" />

import { Toast, useToast } from './Toast';
import { transformedCode } from '../../../utils';
import {
  AppProvider,
  CodePreview,
  Table,
  Text,
  InlineCode,
} from '@gluestack/design-system';

import { styled } from '@dank-style/react';
import { View, Pressable } from 'react-native';

import Wrapper from '../../Wrapper';

# Installation

This command copies the `Toast` component to your project.

```jsx
npx install @gluestack-ui add toast
```

## Import

```jsx
// import the component and the hook from your component folder
import { useToast, Toast } from 'components';
```

<br />

# Basic

<AppProvider>
  <CodePreview
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
function App() {
  const ToastExample = () => {
  const toast = useToast();
  return (
      <Pressable
        onPress={() => {
          toast.show({
            placement: "top",
            render: ({ id }) => {
              return (
                <Toast nativeId={id}>
                  <Toast.Title>Hello World Toast {id}</Toast.Title>
                </Toast>
              );
            },
          });
        }}
      >
        <Text>Press Me</Text>
      </Pressable>
  );
};
    return <Wrapper><ToastExample /></Wrapper>;
  };
`,
      scope: {
        View,
        Wrapper,
        Toast,
        useToast,
        Text,
        Pressable,
      },
      argsType: {},
    }}
  />
</AppProvider>
<br />

## Anatomy

```jsx
export default () => (
  <Toast>
    <Toast.Text />
  </Toast>
);
```

## API Reference

### Toast

It inherits all the properties of React Native's [View](https://reactnative.dev/docs/view#props) component.

<AppProvider>
  <Table>
    <Table.THead>
      <Table.TR>
        <Table.TH>
          <Table.TText>Prop</Table.TText>
        </Table.TH>
        <Table.TH>
          <Table.TText>Type</Table.TText>
        </Table.TH>
        <Table.TH>
          <Table.TText>Default</Table.TText>
        </Table.TH>
        <Table.TH>
          <Table.TText>Description</Table.TText>
        </Table.TH>
      </Table.TR>
    </Table.THead>
    <Table.TBody>
      <Table.TR>
        <Table.TD>
          <Table.TText>
            <InlineCode>duration</InlineCode>
          </Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>number or null</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>5000</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>{`The delay before the toast hides (in milliseconds). If set to null, toast will never dismiss.`}</Table.TText>
        </Table.TD>
      </Table.TR>
      <Table.TR>
        <Table.TD>
          <Table.TText>
            <InlineCode>onCloseComplete</InlineCode>
          </Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>{`()=>{}`}</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>-</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>{`Callback function to run side effects after the toast has closed.`}</Table.TText>
        </Table.TD>
      </Table.TR>
      <Table.TR>
        <Table.TD>
          <Table.TText>
            <InlineCode>placement</InlineCode>
          </Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>{`'top'| 'top-right' | 'top-left' | 'bottom' | 'bottom-left' | 'bottom-right'`}</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>bottom</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>{`you can choose the placement to render the toast`}</Table.TText>
        </Table.TD>
      </Table.TR>
      <Table.TR>
        <Table.TD>
          <Table.TText>
            <InlineCode>render?: (props: any)</InlineCode>
          </Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>ReactNode</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>-</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>{`Render a component toast component`}</Table.TText>
        </Table.TD>
      </Table.TR>
      <Table.TR>
        <Table.TD>
          <Table.TText>
            <InlineCode>accessibilityAnnouncement</InlineCode>
          </Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>string</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>-</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>{`The text to be announced by a screen reader when the Toast opens.`}</Table.TText>
        </Table.TD>
      </Table.TR>
      <Table.TR>
        <Table.TD>
          <Table.TText>
            <InlineCode>accessibilityLiveRegion</InlineCode>
          </Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>{`'none' | 'polite' | 'assertive'`}</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>none</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>{`Determines the 'accessibility announcement tone'`}</Table.TText>
        </Table.TD>
      </Table.TR>
      <Table.TR>
        <Table.TD>
          <Table.TText>
            <InlineCode>avoidKeyboard</InlineCode>
          </Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>bool</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>false</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>{`If true and the keyboard is opened, the Toast will move up equivalent to the keyboard height.`}</Table.TText>
        </Table.TD>
      </Table.TR>
    </Table.TBody>
  </Table>
</AppProvider>

### Toast.Title

Contains all Text related layout style props and actions.
It inherits all the properties of React Native's [Text](https://reactnative.dev/docs/text#props) component.

### Toast.Description

Contains all Text related layout style props and actions.
It inherits all the properties of React Native's [Text](https://reactnative.dev/docs/text#props) component.

## Accessibility

### Keyboard

- setting the accessibilityLabel and accessibilityHint

### Screen Reader

- VoiceOver: accessible and accessibilityLabel props to describe the input's purpose
- `accessibilityTraits` and `accessibilityHint` for the various states of the input, such as "double tap to edit"

## Dependencies

- `@gluestack-ui/utils`
- `@gluestack-ui/hooks`
- `@gluestack-ui/overlay`
- `@gluestack-ui/transitions`
- `@react-native-aria/focus`
- `react-native-svg`
- `@gluestack-ui/react-native-aria`

# Advanced

## Customizing the Toast

We have a function called `createToast` which can be used to create a custom toast component. This function takes in a configuration object which contains the styled components that you want to use for the Input. You can refer [dank.style](https://dank.style/) for more information on how to use styled components.

### Usage

```jsx
// import the styles
import {
  Root,
  Title,
  Description,
} from '../components/core/toast/styled-components';

// import the createToast function
import { createToast, createToastHook } from '@gluestack-ui/toast';

// Understanding the API
const Toast = createToast({
  Root,
  Title,
  Description,
});

const useToast = createToastHook(Toast);

// Using the toast component
export default () => {
  const toast = useToast();
  return (
    <Button
      {...props}
      onPress={() => {
        toast.show({
          placement: placement,
          render: ({ id }) => {
            return (
              <Toast nativeId={id}>
                <Toast.Title>Hello World Toast {id}</Toast.Title>
              </Toast>
            );
          },
        });
      }}
    >
      <Button.Text>Press Me</Button.Text>
    </Button>
  );
};
```

Default styling of all these components can be found in the `components/core/toast` file. For reference, you can view the [source code](https://github.com/gluestack/gluestack-ui/blob/development/example/storybook/src/components/Toast/index.tsx) of the styled `Toast` components.