Toast

The toast component is used to give feedback to users after an action has taken place.

View sourceView theme source@chakra-ui/toast

Import

import { useToast } from '@chakra-ui/react';

Usage

The toast will close itself when the close button is clicked, or after a timeout.

Toasts can be configured to appear at either the top or the bottom of an application window, and it is possible to have more than one toast onscreen at a time.

function ToastExample() { const toast = useToast(); return ( <Button onClick={() => toast({ title: 'Account created.', description: "We've created your account for you.", status: 'success', duration: 9000, isClosable: true, }) } > Show Toast </Button> ); }

function ToastExample() {
  const toast = useToast();
  return (
    <Button
      onClick={() =>
        toast({
          title: 'Account created.',
          description: "We've created your account for you.",
          status: 'success',
          duration: 9000,
          isClosable: true,
        })
      }
    >
      Show Toast
    </Button>
  );
}

Make sure to call useToast at least one component level below the <ChakraProvider> because it needs access to the current theme.

Custom component

Display a custom component instead of the default Toast UI.

function CustomToastExample() { const toast = useToast(); return ( <Button onClick={() => toast({ position: 'bottom-left', render: () => ( <Box color='white' p={3} bg='blue.500'> Hello World </Box> ), }) } > Show Toast </Button> ); }

function CustomToastExample() {
  const toast = useToast();
  return (
    <Button
      onClick={() =>
        toast({
          position: 'bottom-left',
          render: () => (
            <Box color='white' p={3} bg='blue.500'>
              Hello World
            </Box>
          ),
        })
      }
    >
      Show Toast
    </Button>
  );
}

Closing Toasts

Toasts can be closed imperatively, individually (via the close instance method) or all together (via the closeAll instance method).

function ClosingToastExample() { const toast = useToast(); const toastIdRef = React.useRef(); function close() { if (toastIdRef.current) { toast.close(toastIdRef.current); } } function closeAll() { // you may optionally pass an object of positions to exclusively close // keeping other positions opened // e.g. `{ positions: ['bottom'] }` toast.closeAll(); } function addToast() { toastIdRef.current = toast({ description: 'some text' }); } return ( <Wrap> <Button onClick={addToast} type='button'> Toast </Button> <Button onClick={close} type='button' variant='outline'> Close last toast </Button> <Button onClick={closeAll} type='button' variant='outline'> Close all toasts </Button> </Wrap> ); }

function ClosingToastExample() {
  const toast = useToast();
  const toastIdRef = React.useRef();

  function close() {
    if (toastIdRef.current) {
      toast.close(toastIdRef.current);
    }
  }

  function closeAll() {
    // you may optionally pass an object of positions to exclusively close
    // keeping other positions opened
    // e.g. `{ positions: ['bottom'] }`
    toast.closeAll();
  }

  function addToast() {
    toastIdRef.current = toast({ description: 'some text' });
  }

  return (
    <Wrap>
      <Button onClick={addToast} type='button'>
        Toast
      </Button>

      <Button onClick={close} type='button' variant='outline'>
        Close last toast
      </Button>

      <Button onClick={closeAll} type='button' variant='outline'>
        Close all toasts
      </Button>
    </Wrap>
  );
}

Updating Toasts

Toasts' options can be updated, by passing an id and the new options to the update instance method.

function UpdatingToastExample() { const toast = useToast(); const toastIdRef = React.useRef(); function update() { if (toastIdRef.current) { toast.update(toastIdRef.current, { description: 'new text' }); } } function addToast() { toastIdRef.current = toast({ description: 'some text' }); } return ( <Stack isInline spacing={2}> <Button onClick={addToast} type='button'> Toast </Button> <Button onClick={update} type='button' variant='outline'> Update last toast </Button> </Stack> ); }

function UpdatingToastExample() {
  const toast = useToast();
  const toastIdRef = React.useRef();

  function update() {
    if (toastIdRef.current) {
      toast.update(toastIdRef.current, { description: 'new text' });
    }
  }

  function addToast() {
    toastIdRef.current = toast({ description: 'some text' });
  }

  return (
    <Stack isInline spacing={2}>
      <Button onClick={addToast} type='button'>
        Toast
      </Button>

      <Button onClick={update} type='button' variant='outline'>
        Update last toast
      </Button>
    </Stack>
  );
}

Status

You can use status to change the color of your toasts.

function ToastStatusExample() { const toast = useToast(); const statuses = ['success', 'error', 'warning', 'info']; return ( <Wrap> {statuses.map((status, i) => ( <WrapItem key={i}> <Button onClick={() => toast({ title: `${status} toast`, status: status, isClosable: true, }) } > Show {status} toast </Button> </WrapItem> ))} </Wrap> ); }

function ToastStatusExample() {
  const toast = useToast();
  const statuses = ['success', 'error', 'warning', 'info'];

  return (
    <Wrap>
      {statuses.map((status, i) => (
        <WrapItem key={i}>
          <Button
            onClick={() =>
              toast({
                title: `${status} toast`,
                status: status,
                isClosable: true,
              })
            }
          >
            Show {status} toast
          </Button>
        </WrapItem>
      ))}
    </Wrap>
  );
}

Variants

Toast uses the same variants as the Alert component.

function ToastVariantsExample() { const toast = useToast(); const variants = ['solid', 'subtle', 'left-accent', 'top-accent']; return ( <Wrap> {variants.map((variant, i) => ( <WrapItem key={i}> <Button onClick={() => toast({ title: `${variant} toast`, variant: variant, isClosable: true, }) } > Show {variant} toast </Button> </WrapItem> ))} </Wrap> ); }

function ToastVariantsExample() {
  const toast = useToast();
  const variants = ['solid', 'subtle', 'left-accent', 'top-accent'];

  return (
    <Wrap>
      {variants.map((variant, i) => (
        <WrapItem key={i}>
          <Button
            onClick={() =>
              toast({
                title: `${variant} toast`,
                variant: variant,
                isClosable: true,
              })
            }
          >
            Show {variant} toast
          </Button>
        </WrapItem>
      ))}
    </Wrap>
  );
}

Custom container styles

The toast function now exposes a containerStyle property you can use to override the default styles for the toast container.

function Example() { // Via instantiation const toast = useToast({ position: 'top', title: 'Container style is updated', containerStyle: { width: '800px', maxWidth: '100%', }, }); // Or via trigger // Style here will overwrite the entire style above return ( <Button onClick={() => { toast({ containerStyle: { border: '20px solid red', }, }); }} > Click me to show toast with custom container style. </Button> ); }

function Example() {
  // Via instantiation
  const toast = useToast({
    position: 'top',
    title: 'Container style is updated',
    containerStyle: {
      width: '800px',
      maxWidth: '100%',
    },
  });
  // Or via trigger
  // Style here will overwrite the entire style above
  return (
    <Button
      onClick={() => {
        toast({
          containerStyle: {
            border: '20px solid red',
          },
        });
      }}
    >
      Click me to show toast with custom container style.
    </Button>
  );
}

Changing the toast position

Using the position prop you can adjust where your toast will be popup from.

function PositionExample() { const toast = useToast(); const positions = [ 'top', 'top-right', 'top-left', 'bottom', 'bottom-right', 'bottom-left', ]; return ( <Wrap> {positions.map((position, i) => ( <WrapItem key={i}> <Button onClick={() => toast({ title: `${position} toast`, position: position, isClosable: true, }) } > Show {position} toast </Button> </WrapItem> ))} </Wrap> ); }

function PositionExample() {
  const toast = useToast();
  const positions = [
    'top',
    'top-right',
    'top-left',
    'bottom',
    'bottom-right',
    'bottom-left',
  ];

  return (
    <Wrap>
      {positions.map((position, i) => (
        <WrapItem key={i}>
          <Button
            onClick={() =>
              toast({
                title: `${position} toast`,
                position: position,
                isClosable: true,
              })
            }
          >
            Show {position} toast
          </Button>
        </WrapItem>
      ))}
    </Wrap>
  );
}

Preventing Duplicate Toast

In some cases you might need to prevent duplicate of specific toasts. To achieve you need to pass an id and use the toast.isActive method to determine when to call toast(...).

function PreventDuplicateExample() {
  const toast = useToast();
  const id = 'test-toast';
  return (
    <Button
      onClick={() => {
        if (!toast.isActive(id)) {
          toast({
            id,
            title: 'Hey! You can create a duplicate toast',
          });
        }
      }}
    >
      Click me!
    </Button>
  );
}

Standalone Toasts

Use createStandaloneToast to create toasts from outside of your React Components.

🚨 If you're using a custom theme, you must pass it in the arguments to createStandaloneToast. If you don't, the default theme will be applied, causing the font size of your page to shift when the toast is open.

import * as ReactDOM from 'react-dom/client';
import { createStandaloneToast } from '@chakra-ui/toast';

const { ToastContainer, toast } = createStandaloneToast();

// render the ToastContainer in your React root
const rootElement = document.getElementById('root');
ReactDOM.createRoot(yourRootElement).render(
  <>
    <App />
    <ToastContainer />
  </>
);

toast({
  title: 'An error occurred.',
  description: 'Unable to create user account.',
  status: 'error',
  duration: 9000,
  isClosable: true,
});

Props

colorScheme

Description

Color Schemes for useToast are not implemented in the default theme. You can extend the theme to implement them.

Type

string

containerStyle

Description

Optional style overrides for the container wrapping the toast component.

Type

StyleProps

description

Description

The description of the toast

Type

ReactNode

duration

Description

The delay before the toast hides (in milliseconds) If set to null, toast will never dismiss.

Type

number | null

Default

5000 ( = 5000ms )

icon

Description

A custom icon that will be displayed by the toast.

Type

ReactNode

id

Description

The id of the toast. Mostly used when you need to prevent duplicate. By default, we generate a unique id for each toast

Type

ToastId

isClosable

Description

If true, toast will show a close button

Type

boolean

onCloseComplete

Description

Callback function to run side effects after the toast has closed.

Type

(() => void)

position

Description

The placement of the toast

Type

ToastPosition

Default

"bottom"

render

Description

Render a component toast component. Any component passed will receive 2 props: id and onClose.

Type

((props: RenderProps) => ReactNode)

size

Description

Sizes for useToast are not implemented in the default theme. You can extend the theme to implement them.

Type

string

status

Description

The status of the toast.

Type

"info" | "warning" | "success" | "error" | "loading"

title

Description

The title of the toast

Type

ReactNode

variant

Description

Variants for useToast are not implemented in the default theme. You can extend the theme to implement them.

Type

string