nav-toast

shadow

A Toast is a subtle notification commonly used in modern applications. It can be used to provide feedback about an operation or to display a system message. The toast appears on top of the app's content, and can be dismissed by the app to resume user interaction with the app.

Presenting

Positioning

Toasts can be positioned at the top, bottom or middle of the viewport. The position can be passed upon creation. The possible values are top, bottom and middle. If the position is not specified, the toast will be displayed at the bottom of the viewport.

Controller

Inline

When using Navify with React or Kdu, nav-toast can also be placed directly in the template through use of the isOpen property. Note that isOpen must be set to false manually when the toast is dismissed; it will not be updated automatically.

React

import React, { useState } from 'react';
import { NavButton, NavToast } from '@navify/react';

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

  return (
    <>
      <NavButton onClick={() => setShowToast(true)}>Show Toast</NavButton>
      <NavToast
        isOpen={showToast}
        onDidDismiss={() => setShowToast(false)}
        message="Hello World!"
        duration={1500}
      />
    </>
  );
}

Kdu

<template>
  <nav-button @click="setOpen(true)">Show Toast</nav-button>
  <nav-toast
    :is-open="isOpenRef"
    @didDismiss="setOpen(false)"
    message="Hello World!"
    :duration="1500"
  ></nav-toast>
</template>

<script lang="ts">
import { NavButton, NavToast } from '@navify/kdu';
import { defineComponent, ref } from 'kdu';

export default defineComponent({
  components: { NavButton, NavToast },
  setup() {
    const isOpenRef = ref(false);
    const setOpen = (state: boolean) => isOpenRef.value = state;
    
    return { isOpenRef, setOpen }
  }
});
</script>

Dismissing

The toast can be dismissed automatically after a specific amount of time by passing the number of milliseconds to display it in the duration of the toast options. If a button with a role of "cancel" is added, then that button will dismiss the toast. To dismiss the toast after creation, call the dismiss() method on the instance.

The following example demonstrates how to use the buttons property to add a button that automatically dismisses the toast when clicked, as well as how to collect the role of the dismiss event.

Icons

An icon can be added next to the content inside of the toast. In general, icons in toasts should be used to add additional style or context, not to grab the user's attention or elevate the priority of the toast. If you wish to convey a higher priority message to the user or guarantee a response, we recommend using an Alert instead.

Theming

Interfaces

ToastButton

interface ToastButton {
  text?: string;
  icon?: string;
  side?: 'start' | 'end';
  role?: 'cancel' | string;
  cssClass?: string | string[];
  handler?: () => boolean | void | Promise<boolean | void>;
}

ToastOptions

interface ToastOptions {
  header?: string;
  message?: string | NavifySafeString;
  cssClass?: string | string[];
  duration?: number;
  buttons?: (ToastButton | string)[];
  position?: 'top' | 'bottom' | 'middle';
  translucent?: boolean;
  animated?: boolean;
  icon?: string;
  htmlAttributes?: { [key: string]: any };

  color?: Color;
  mode?: Mode;
  keyboardClose?: boolean;
  id?: string;

  enterAnimation?: AnimationBuilder;
  leaveAnimation?: AnimationBuilder;
}

Accessibility

Focus Management

Toasts are intended to be subtle notifications and are not intended to interrupt the user. User interaction should not be required to dismiss the toast. As a result, focus is not automatically moved to a toast when one is presented.

Screen Readers

nav-toast has aria-live="polite" and aria-atomic="true" set by default.

aria-live causes screen readers to announce the content of the toast when it is updated. However, since the attribute is set to 'polite', screen readers generally do not interrupt the current task. Developers can customize this behavior by using the htmlAttributes property to set aria-live to 'assertive'. This will cause screen readers to immediately notify the user when a toast is updated, potentially interrupting any previous updates.

aria-atomic="true" is set to ensure that the entire toast is announced as a single unit. This is useful when dynamically updating the content of the toast as it prevents screen readers from announcing only the content that has changed.

Tips

While this is not a complete list, here are some guidelines to follow when using toasts.

• Do not require user interaction to dismiss toasts. For example, having a "Dismiss" button in the toast is fine, but the toast should also automatically dismiss on its own after a timeout period. If you need user interaction for a notification, consider using nav-alert instead.

• Avoid opening multiple toasts in quick succession. If aria-live is set to 'assertive', screen readers may interrupt the reading of the current task to announce the new toast, causing the context of the previous toast to be lost.

• For toasts with long messages, consider adjusting the duration property to allow users enough time to read the content of the toast.

Properties

animated

Description	If true, the toast will animate.
Attribute	animated
Type	boolean
Default	true

buttons

Description	An array of buttons for the toast.
Attribute	undefined
Type	(string ｜ ToastButton)[] ｜ undefined
Default	undefined

color

Description	The color to use from your application's color palette. Default options are: "primary", "secondary", "tertiary", "success", "warning", "danger", "light", "medium", and "dark". For more information on colors, see theming.
Attribute	color
Type	"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string & Record<never, never> ｜ undefined
Default	undefined

cssClass

Description	Additional classes to apply for custom CSS. If multiple classes are provided they should be separated by spaces.
Attribute	css-class
Type	string ｜ string[] ｜ undefined
Default	undefined

duration

Description	How many milliseconds to wait before hiding the toast. By default, it will show until dismiss() is called.
Attribute	duration
Type	number
Default	config.getNumber('toastDuration', 0)

enterAnimation

Description	Animation to use when the toast is presented.
Attribute	undefined
Type	((baseEl: any, opts?: any) => Animation) ｜ undefined
Default	undefined

header

Description	Header to be shown in the toast.
Attribute	header
Type	string ｜ undefined
Default	undefined

htmlAttributes

Description	Additional attributes to pass to the toast.
Attribute	undefined
Type	undefined ｜ { [key: string]: any; }
Default	undefined

icon

Description	The name of the icon to display, or the path to a valid SVG file.
Attribute	icon
Type	string ｜ undefined
Default	undefined

keyboardClose

Description	If true, the keyboard will be automatically dismissed when the overlay is presented.
Attribute	keyboard-close
Type	boolean
Default	false

leaveAnimation

Description	Animation to use when the toast is dismissed.
Attribute	undefined
Type	((baseEl: any, opts?: any) => Animation) ｜ undefined
Default	undefined

message

Description	Message to be shown in the toast.
Attribute	message
Type	NavifySafeString ｜ string ｜ undefined
Default	undefined

mode

Description	The mode determines which platform styles to use.
Attribute	mode
Type	"ios" ｜ "md"
Default	undefined

position

Description	The position of the toast on the screen.
Attribute	position
Type	"bottom" ｜ "middle" ｜ "top"
Default	'bottom'

translucent

Description	If true, the toast will be translucent. Only applies when the mode is "ios" and the device supports backdrop-filter.
Attribute	translucent
Type	boolean
Default	false

Events

Name	Description
navToastDidDismiss	Emitted after the toast has dismissed.
navToastDidPresent	Emitted after the toast has presented.
navToastWillDismiss	Emitted before the toast has dismissed.
navToastWillPresent	Emitted before the toast has presented.

Methods

dismiss

Description	Dismiss the toast overlay after it has been presented.
Signature	dismiss(data?: any, role?: string) => Promise<boolean>

onDidDismiss

Description	Returns a promise that resolves when the toast did dismiss.
Signature	onDidDismiss<T = any>() => Promise<OverlayEventDetail<T>>

onWillDismiss

Description	Returns a promise that resolves when the toast will dismiss.
Signature	onWillDismiss<T = any>() => Promise<OverlayEventDetail<T>>

present

Description	Present the toast overlay after it has been created.
Signature	present() => Promise<void>

CSS Shadow Parts

Name	Description
button	Any button element that is displayed inside of the toast.
container	The element that wraps all child elements.
header	The header text of the toast.
icon	The icon that appears next to the toast content.
message	The body text of the toast.

CSS Custom Properties

Name	Description
--background	Background of the toast
--border-color	Border color of the toast
--border-radius	Border radius of the toast
--border-style	Border style of the toast
--border-width	Border width of the toast
--box-shadow	Box shadow of the toast
--button-color	Color of the button text
--color	Color of the toast text
--end	Position from the right if direction is left-to-right, and from the left if direction is right-to-left
--height	Height of the toast
--max-height	Maximum height of the toast
--max-width	Maximum width of the toast
--min-height	Minimum height of the toast
--min-width	Minimum width of the toast
--start	Position from the left if direction is left-to-right, and from the right if direction is right-to-left
--white-space	White space of the toast message
--width	Width of the toast

Slots

No slots available for this component.