Toast ​

The toast component is a non-disruptive message that appears at the top of the interface to provide a quick, at-a-glance feedback on the outcome of an action. Toasts are often used to confirm that an action has been completed successfully or to inform users of a change in state.

Usage ​

<script lang="ts" setup>
import { useToastNotifications } from '@returnless/focus-ui';

const {
  initializeNotificationHandlers,
  emitToastNotificationEvent,
  emitToastNotificationEvents,
  toastNotifications,
  closeToastNotification,
} = useToastNotifications();

const TOAST_MESSAGE_DURATION = 5_000;

const notifications = ref([{
  message: 'This is a toast message',
  duration: TOAST_MESSAGE_DURATION,
}]);

onMounted(() => {
  initializeNotificationHandlers();
});

watch(notifications, (newValue): void => {
  if (newValue) {
    setTimeout(() => {
      emitToastNotificationEvents(newValue);
    });
  }
}, { immediate: true });

function closeToast(toastNotification: ToastNotification): void {
  closeToastNotification(toastNotification);
}

function addToast(): void {
  emitToastNotificationEvent({
    message: 'This is a new toast message',
    duration: TOAST_MESSAGE_DURATION,
  });
}
</script>

Best practices ​

Toast should:

• Be used for short messages to confirm an action.
• Not go over 3 words.
• Rarely be used for error messages.
• Be used for success messages.
• Be used only for non-critical errors that are relevant at the moment and can be explained in 3 words. For example, if there's an internet connection issue, the toast would say, "No internet connection."
• Avoid using toasts for error messages. Always try to use a banner to prominently inform users about persistent errors.

Content guidelines ​

Toast messages should be:

• Short and affirmative.
• Written in the pattern of {noun + verb}.

Toast with action ​

Only include an action in toast if the same action is available elsewhere o n the page. For example:

• If users need to reload a section, offer the call to action [Reload] in the toast. If they miss the toast message, they can also refresh the entire page.
• If users delete an image, offer the option to [Undo] the deletion. If they miss it in the toast message, they can still retrieve it from somewhere else.

Actions should:

• Keep the action label short, preferably 1 verb.
• Not have actions, like Cancel, for dismissing toast. The X to dismiss is already included in the component.
• Be used with a duration of at least 10,000 milliseconds for accessibility. This gives users enough time to read the message and take action.

Accessibility ​

The content of the toast component is implemented as an ARIA live region using aria-live"assertive". When the toast appears, screen readers will interrupt any announcement a screen reader is currently making.

Avoid using toast for critical information that users need to act on immediately. Toast might be difficult for users with low vision or low dexterity to access because it:

• Disappears automatically.
• Can't be easily accessed with the keyboard.
• Might appear outside the proximity of the user's current focus.

Toast with action ​

Make sure that users can also accomplish the action in the toast another way, since the toast action may be difficult to access for some users. If the toast action is not available somewhere else on the page, for example a retry action that reloads a section, it should have a fallback action, for example a browser refresh.

Toast with action should persist for at least 10,000 milliseconds to give users enough time to read the message and act on it.