Toast API - React Magma

Toast components use the Alert component internally for its content and styles. Any props that can be passed to an Alert can be passed to a Toast component.

Toast messages can only be 1 or 2 lines long and have a max-width of 600px. If your message is longer than that, please shorten it or use a different component.

Basic Usage

Toasts are used to display non-critical information to users. For critical messages, designers should consider a different way of presenting the information, such as using the Alert component within the context of the UI.

Developers should always use the Announce component to wrap Toasts so that the content can be properly announced to screen readers. More below under Accessibility Considerations.

import React from 'react';

import { Button, Toast, Announce } from 'react-magma-dom';

export function Example() {
  const [showToast, setShowToast] = React.useState(false);

  function handleClick() {
    setShowToast(true);
  }

  function handleDismiss() {
    setShowToast(false);
  }

  return (
    <>
      <Button onClick={handleClick}>Show Default Toast</Button>
      <Announce>
        {showToast && <Toast onDismiss={handleDismiss}>Default Toast</Toast>}
      </Announce>
    </>
  );
}

Variants

Variants for toasts include info, success, warning, and danger, with info being the default value.

It is strongly recommended that warning and danger toasts do not auto-dismiss, so that users have time to process the information in them.

import React from 'react';

import {
  Announce,
  Button,
  ButtonGroup,
  Toast,
  ToastsContainer,
  AlertVariant,
} from 'react-magma-dom';

export function Example() {
  const [showToast, setShowToast] = React.useState(false);
  const [showToast2, setShowToast2] = React.useState(false);
  const [showToast3, setShowToast3] = React.useState(false);
  const [showToast4, setShowToast4] = React.useState(false);

  function handleClick() {
    setShowToast(true);
  }
  function handleDismiss() {
    setShowToast(false);
  }

  function handleClick2() {
    setShowToast2(true);
  }
  function handleDismiss2() {
    setShowToast2(false);
  }

  function handleClick3() {
    setShowToast3(true);
  }
  function handleDismiss3() {
    setShowToast3(false);
  }

  function handleClick4() {
    setShowToast4(true);
  }
  function handleDismiss4() {
    setShowToast4(false);
  }

  return (
    <ToastsContainer>
      <ButtonGroup>
        <Button onClick={handleClick}>Show Success Toast</Button>
        <Announce>
          {showToast && (
            <Toast
              id="toast1"
              onDismiss={handleDismiss}
              variant={AlertVariant.success}
            >
              This is a success toast
            </Toast>
          )}
        </Announce>

        <Button onClick={handleClick2}>Show Warning Toast</Button>
        <Announce>
          {showToast2 && (
            <Toast
              id="toast2"
              variant={AlertVariant.warning}
              onDismiss={handleDismiss2}
              disableAutoDismiss
            >
              This is is a warning toast
            </Toast>
          )}
        </Announce>
      </ButtonGroup>
      <br />
      <ButtonGroup>
        <Button onClick={handleClick3}>Show Danger Toast</Button>
        <Announce>
          {showToast3 && (
            <Toast
              id="toast3"
              variant={AlertVariant.danger}
              onDismiss={handleDismiss3}
              disableAutoDismiss
            >
              This is a danger toast
            </Toast>
          )}
        </Announce>

        <Button onClick={handleClick4}>Show Info Toast</Button>
        <Announce>
          {showToast4 && (
            <Toast
              id="toast4"
              variant={AlertVariant.info}
              onDismiss={handleDismiss4}
            >
              This is an info toast
            </Toast>
          )}
        </Announce>
      </ButtonGroup>
    </ToastsContainer>
  );
}

Accessibility Considerations

Toasts are brief interruptions, so users must be notified when they appear. Use the Announce component, which uses the aria-live attribute, and place the toast’s display logic inside it.

Visually, toasts appear at the bottom left, but their DOM placement affects tab order—structure your markup accordingly.

import React from 'react';

import { Button, Announce, Toast } from 'react-magma-dom';

export function Example() {
  const [showToast, setShowToast] = React.useState(false);

  function handleButtonClick() {
    setShowToast(true);
  }

  function handleToastDismiss() {
    setShowToast(false);
  }

  return (
    <>
      <Button onClick={handleButtonClick}>Show Toast in Announce</Button>
      <Announce>
        {showToast && (
          <Toast dismissible onDismiss={handleToastDismiss}>
            Dismissible Toast
          </Toast>
        )}
      </Announce>
    </>
  );
}

Toasts Container (handling multiple toasts)

To handle multiple toasts, add the ToastsContainer component around all of the content that will contain the toasts. This may be the entire application. The first toast will appear at the bottom of the screen, the next toast will appear just above it, and so on. There is no limit to the number of toasts that may be added. However if the number of toasts exceeds the amount of space on the screen, layout issues might occur. Try to limit the number of toasts appearing on screen at once as much as possible.

import React from 'react';

import {
  Announce,
  Button,
  ButtonColor,
  Toast,
  ToastsContainer,
  AlertVariant,
  ButtonGroup,
} from 'react-magma-dom';

export function Example() {
  const [showToast, setShowToast] = React.useState(false);
  const [showToast2, setShowToast2] = React.useState(false);
  const [showToast3, setShowToast3] = React.useState(false);

  function handleClick() {
    setShowToast(true);
  }
  function handleDismiss() {
    setShowToast(false);
  }

  function handleClick2() {
    setShowToast2(true);
  }
  function handleDismiss2() {
    setShowToast2(false);
  }

  function handleClick3() {
    setShowToast3(true);
  }
  function handleDismiss3() {
    setShowToast3(false);
  }

  return (
    <ToastsContainer>
      <ButtonGroup>
        <Button onClick={handleClick}>Show Toast</Button>
        <Announce>
          {showToast && (
            <Toast
              id="toast1"
              onDismiss={handleDismiss}
              variant={AlertVariant.success}
            >
              Toast 1
            </Toast>
          )}
        </Announce>

        <Button onClick={handleClick2} color={ButtonColor.secondary}>
          Show Toast 2
        </Button>
        <Announce>
          {showToast2 && (
            <Toast id="toast2" onDismiss={handleDismiss2}>
              This is the second toast which is longer than either toast one or
              three
            </Toast>
          )}
        </Announce>

        <Button onClick={handleClick3} color={ButtonColor.danger}>
          Show Toast 3
        </Button>
        <Announce>
          {showToast3 && (
            <Toast
              disableAutoDismiss
              id="toast3"
              variant={AlertVariant.danger}
              onDismiss={handleDismiss3}
            >
              Toast three
            </Toast>
          )}
        </Announce>
      </ButtonGroup>
    </ToastsContainer>
  );
}

Bottom Offset

The ToastsContainer component takes an optional bottomOffset prop, that indicates the additional number of pixels from the bottom the toasts will render. This is useful in cases where toasts are intended to display above a component, such as a toolbar.

import React from 'react';

import { Button, Toast, ToastsContainer, Announce } from 'react-magma-dom';

export function Example() {
  const [showToast, setShowToast] = React.useState(false);

  function handleClick() {
    setShowToast(true);
  }
  function handleDismiss() {
    setShowToast(false);
  }

  return (
    <ToastsContainer bottomOffset={100}>
      <Button onClick={handleClick}>Show Toast with Bottom Offset</Button>
      <Announce>
        {showToast && (
          <Toast onDismiss={handleDismiss}>
            Toast Container has bottomOffset of 100
          </Toast>
        )}
      </Announce>
    </ToastsContainer>
  );
}

Toast Duration

The toastDuration prop can be used to set the number of milliseconds that the toast will remain on the screen before it auto-dismisses. This can be useful to set a longer duration for more lengthy toasts. It is recommended that the minimum toastDuration is 4000ms. The default is 5000.

import React from 'react';

import { Button, Toast, Announce } from 'react-magma-dom';

export function Example() {
  const [showToast, setShowToast] = React.useState(false);

  function handleClick() {
    setShowToast(true);
  }
  function handleDismiss() {
    setShowToast(false);
  }

  return (
    <>
      <Button onClick={handleClick}>Show Toast</Button>
      <Announce>
        {showToast && (
          <Toast toastDuration={10000} onDismiss={handleDismiss}>
            Slow Toast
          </Toast>
        )}
      </Announce>
    </>
  );
}

Disable Auto Dismiss

import React from 'react';

import { Button, Toast, Announce } from 'react-magma-dom';

export function Example() {
  const [showToast, setShowToast] = React.useState(false);

  function handleClick() {
    setShowToast(true);
  }
  function handleDismiss() {
    setShowToast(false);
  }

  return (
    <>
      <Button onClick={handleClick}>Show Toast</Button>
      <Announce>
        {showToast && (
          <Toast disableAutoDismiss onDismiss={handleDismiss}>
            Non-Auto Hiding Dismissible Toast
          </Toast>
        )}
      </Announce>
    </>
  );
}

Mouse Events

When you hover over the Toast the timer is paused. Once the mouse leaves the Toast the timer is will continue running.

import React from 'react';

import { Button, Toast, Announce } from 'react-magma-dom';

export function Example() {
  const [showToast, setShowToast] = React.useState(false);
  const [toastContent, setToastContent] = React.useState(
    'Default Toast Content'
  );

  function handleClick() {
    setShowToast(true);
  }
  function handleDismiss() {
    setShowToast(false);
  }

  function handleMouseEnter() {
    setToastContent('Mouse is hovering toast');
  }
  function handleMouseLeave() {
    setToastContent('Mouse has stopped hovering toast');
  }

  return (
    <>
      <Button onClick={handleClick}>Show Toast</Button>
      <Announce>
        {showToast && (
          <Toast
            onDismiss={handleDismiss}
            onMouseEnter={handleMouseEnter}
            onMouseLeave={handleMouseLeave}
          >
            {toastContent}
          </Toast>
        )}
      </Announce>
    </>
  );
}

Custom Styles

Custom styles can be added to a toast using two different props. The containerStyle prop controls the style for the toast container itself, which includes the component's positioning and z-index. The alertStyle prop controls the style for the internal alert component, which includes the element's background, border-radius, and fade animation.

import React from 'react';

import { Button, Toast, Announce } from 'react-magma-dom';

export function Example() {
  const [showToast, setShowToast] = React.useState(false);

  function handleClick() {
    setShowToast(true);
  }
  function handleDismiss() {
    setShowToast(false);
  }

  return (
    <>
      <Button onClick={handleClick}>Show Toast</Button>
      <Announce>
        {showToast && (
          <Toast
            alertStyle={{ border: '4px dotted yellow' }}
            containerStyle={{ left: 'auto', right: '20px', bottom: '150px' }}
            onDismiss={handleDismiss}
          >
            Toast with custom styles
          </Toast>
        )}
      </Announce>
    </>
  );
}

isInverse

import React from 'react';

import {
  Announce,
  Button,
  ButtonGroup,
  Card,
  Toast,
  ToastsContainer,
  AlertVariant,
} from 'react-magma-dom';

export function Example() {
  const [showToast, setShowToast] = React.useState(false);
  const [showToast2, setShowToast2] = React.useState(false);
  const [showToast3, setShowToast3] = React.useState(false);
  const [showToast4, setShowToast4] = React.useState(false);

  function handleClick() {
    setShowToast(true);
  }
  function handleDismiss() {
    setShowToast(false);
  }

  function handleClick2() {
    setShowToast2(true);
  }
  function handleDismiss2() {
    setShowToast2(false);
  }

  function handleClick3() {
    setShowToast3(true);
  }
  function handleDismiss3() {
    setShowToast3(false);
  }

  function handleClick4() {
    setShowToast4(true);
  }
  function handleDismiss4() {
    setShowToast4(false);
  }

  return (
    <Card isInverse style={{ padding: '8px' }}>
      <ToastsContainer>
        <ButtonGroup>
          <Button onClick={handleClick} isInverse>
            Show Success Inverse Toast
          </Button>
          <Announce>
            {showToast && (
              <Toast
                id="toast1"
                onDismiss={handleDismiss}
                variant={AlertVariant.success}
                isInverse
              >
                This is a success toast
              </Toast>
            )}
          </Announce>

          <Button onClick={handleClick2} isInverse>
            Show Warning Inverse Toast
          </Button>
          <Announce>
            {showToast2 && (
              <Toast
                id="toast2"
                variant={AlertVariant.warning}
                onDismiss={handleDismiss2}
                isInverse
              >
                This is is a warning toast
              </Toast>
            )}
          </Announce>
        </ButtonGroup>
        <br />
        <ButtonGroup>
          <Button onClick={handleClick3} isInverse>
            Show Danger Toast Inverse
          </Button>
          <Announce>
            {showToast3 && (
              <Toast
                id="toast3"
                variant={AlertVariant.danger}
                onDismiss={handleDismiss3}
                isInverse
              >
                This is a danger toast
              </Toast>
            )}
          </Announce>

          <Button onClick={handleClick4} isInverse>
            Show Info Toast Inverse
          </Button>
          <Announce>
            {showToast4 && (
              <Toast
                id="toast4"
                variant={AlertVariant.info}
                onDismiss={handleDismiss4}
                isInverse
              >
                This is an info toast
              </Toast>
            )}
          </Announce>
        </ButtonGroup>
      </ToastsContainer>
    </Card>
  );
}

Testing

Passing in the testId prop will pass the testId to the internal Alert element.

<Toast testId="toast-id" onDismiss="{()" =""> {}}>This is a toast</Toast>

ToastsContainer Props

bottomOffset

Description

Number of additional pixels from bottom of screen

Type

number

Default

Toast Props

This component uses forwardRef. The ref is applied to the outer div element.

All of the global HTML attributes can be provided as props and will be applied to the wrapping div element that gets rendered.

additionalContent

Type

React.ReactNode

Default

alertStyle

Description

CSS properties for the alert component within the toast container

Type

CSSProperties

Default

children

Required

Description

The content of the component

Type

ReactNode | undefined

Default

closeAriaLabel

Type

string

Default

containerStyle

Description

CSS properties for the component container

Type

CSSProperties

Default

disableAutoDismiss

Description

If true, the component will persist until dismissed by the user

Type

boolean

Default

false

forceDismiss

Type

function

Default

hasTimerRing

Type

boolean

Default

Type

string

Default

isDismissed

Type

boolean

Default

isDismissible

Type

boolean

Default

isExiting

Type

boolean

Default

isInverse

Description

If true, the component will have inverse styling to better appear on a dark background

Type

boolean

Default

false

isPaused

Type

boolean

Default

isToast

Type

boolean

Default

onDismiss

Required

Description

Action that fires when the close button is clicked (required when dismissible is true)

Type

function

Default

onMouseEnter

Description

Action that fires when the mouse enters the component

Type

function

Default

onMouseLeave

Description

Action that fires when the mouse leaves the component

Type

function

Default

toastDuration

Description

Number of milliseconds the toast displays before it closes

Type

number

Default

5000

variant

Description

The variant of the toast, indicating its function in the UI

Type

enum, one of:
AlertVariant.danger
AlertVariant.info
AlertVariant.success
AlertVariant.warning

Default

AlertVariant.info

On this page

Design

Components

Intro

API

Patterns

Data Visualization

Toast

Basic Usage

Variants

Accessibility Considerations

Toasts Container (handling multiple toasts)

Bottom Offset

Toast Duration

Disable Auto Dismiss

Mouse Events

Custom Styles

isInverse

Testing

ToastsContainer Props

Toast Props