## Usage

Toasts display temporary feedback notifications at the top right of the user's screen. They are meant to be noticed without disrupting a user's experience or requiring an action to be taken.

First, render the `<Toaster />` component in your app root:

```tsx
// import { Toaster } from '@eds/toast';

function App() {
  return (
    <Core>
      <YourApp />
      <Toaster />
    </Core>
  );
}
```

Then use the `toast` object to show toasts:

```tsx
// import { toast } from '@eds/toast';

toast.success({ message: 'Operation completed successfully' });
toast.error({ message: 'Something went wrong' });
```

<Notice>
  <Text>
    Typically a toast will be initiated in response to an action or completed API request, but for the purposes of
    demonstration, all toasts in this documentation are triggered via a button.
  </Text>
</Notice>

## Tone

Use `toast.success()` for successful actions and `toast.error()` for errors.

```tsx live
<Flex gap="small">
  <Button label="Add positive toast" onClick={() => toast.success({ message: 'Positive message' })} tone="neutral" />
  <Button label="Add critical toast" onClick={() => toast.error({ message: 'Critical message' })} tone="neutral" />
</Flex>
```

## Placement and spacing

In `small` viewports (>= 576px), toast notifications slide in and out from the top right of the screen, with `xsmall` space (0.5rem/8px) between each. New toast notifications should appear at the top of the list, with older notifications being pushed down until they are dismissed.

<Box
  as="img"
  src="/images/toast-placement-spacing-small-viewport.png"
  alt="A toast notification positioned 64px from the top and 32px from the right hand side of a viewport"
  width="100%"
  marginBottom="small"
/>

In `xsmall` viewports (< 576px), the toast notifications slide in and out from the bottom center of the screen.

<Box
  as="img"
  src="/images/toast-placement-spacing-xsmall-viewport.png"
  alt="A toast notification positioned 32px from the bottom of a viewport and with a margin of 16px to each side"
  width="100%"
  marginBottom="small"
/>

## Width

Toaster have a minWidth of 16rem/256px and maxWidth of 25rem/400px.

In `xsmall` viewports, the width of the modal will consume 100% of the container with a 1rem/16px margin on each side.

```tsx live
<Flex gap="small">
  <Button label="Add short message" onClick={() => toast.success({ message: 'Short message' })} tone="neutral" />
  <Button
    label="Add long message"
    onClick={() => toast.success({ message: 'A much longer message that will wrap onto two lines of text' })}
    tone="neutral"
  />
</Flex>
```

## Message

A message is required in order to render a toast. Messages should be strings. It's best to keep messages succinct.

```tsx live
<Button label="Add positive toast" onClick={() => toast.success({ message: 'Positive message' })} tone="neutral" />
```

## Actions

By default, the toast comes with a "dismiss" button in the form of a close icon. You can optionally add an action button which requires `buttonText` and `onClickButton` props to be set. Also available is a link which requires both a `linkText` and `linkHref`.

<Notice>
  <Text>
    Link action should be used when the action takes user to another page. Button action should be used in all other
    scenarios (eg. undoing of the toast action, activating a modal, etc)
  </Text>
</Notice>

```tsx live
<Flex gap="small">
  <Button
    label="Button action example"
    onClick={() =>
      toast.success({
        message: 'Message sent',
        buttonText: 'Undo',
        onClickButton: () => {},
      })
    }
    tone="neutral"
  />
  <Button
    label="Link action example"
    onClick={() =>
      toast.success({
        message: 'Article published',
        linkText: 'See article',
        linkHref: '#',
      })
    }
    tone="neutral"
  />
</Flex>
```

## Auto dismiss

Toasts are set to auto-dismiss after 5 seconds by default, but hovering over a toast prevents this automatic dismissal. Alternatively, users can simply click the close icon to dismiss the toast instantly.

## Deprecated APIs

The `<Toast />` component and `toastMessage` function are deprecated and will be removed in a future version.

**Deprecated:**

```tsx
const [positiveMessage, setPositiveMessage] = useState<symbol>();
const [criticalMessage, setCriticalMessage] = useState<symbol>();

return (
  <>
    <Flex gap="small">
      <Button
        label="Add positive toast"
        onClick={() => setPositiveMessage(toastMessage('Positive message'))}
        tone="neutral"
      />
      <Button
        label="Add critical toast"
        onClick={() => setCriticalMessage(toastMessage('Critical message'))}
        tone="neutral"
      />
    </Flex>

    {positiveMessage && <Toast message={positiveMessage} tone="positive" />}
    {criticalMessage && <Toast message={criticalMessage} tone="critical" />}
  </>
);
```

**Recommended:**

```tsx
<Flex gap="small">
  <Button label="Add positive toast" onClick={() => toast.success({ message: 'Positive message' })} tone="neutral" />
  <Button label="Add critical toast" onClick={() => toast.error({ message: 'Critical message' })} tone="neutral" />
</Flex>
```

A brief notification that doesn't disrupt or require an action.

Toast

Accessibility

Responsive layouts

Tokens

Foundations

a11y

Accordion

Actions

AddressInput

AppLayout

Avatar

Badge

Blanket

Breadcrumbs

BulkActionBar

Button

Card

Checkbox

Core

DateDropdown

DateInput

Divider

EmptyState

Field

Fieldset

FileInput

Filtering

Flex

Grid

Heading

Icon

Illustration

Link

List

Loading

Modal

Notice

PageHeader

Pagination

PhoneInput

Popover

Radio

RailTrack

RichTextEditor

ScrollWrap

SearchInput

SelectDropdown

SelectInput

ShowMore

Table

Tabs

Text

TextAreaInput

TextInput

Toggle

Tooltip

Utils

Utils - NextJS

Components

Forms

Search

Tables

Patterns

Introduction

Product tone and voice

Capitalisation

Date and time

Inclusive design

Content

Welcome to EDS

Start designing

Start developing

Contributing

Releases

The EDS way

Coding style guide

Guide to Pendo

Setting up the EDS repo

Creating a new component

Automated testing

PR and changeset process

Publishing snapshots

Publishing packages

Monorepo tools

Team resources