made for Nordcraft

Toast

A component that displays brief, non-disruptive messages to users. Implements proper focus management and gesture support for optimal user experience. Messages can be triggered from anywhere in the application through a provider component.

  • Automatically closes after configurable duration

  • Pauses closing on hover, focus and touch interactions

  • Supports closing via swipe gesture

  • Comes with a provider to easily trigger messages from any point in your application

Example

Architecture

zcore-toast-provider
Slot: default
zcore-toast-portal
Slot: default
zcore-toast-region
Slot: default
zcore-toast-content
Slot: default Place the contents of the toast here
zcore-toast-close
Slot: default You need to place an zcore-button here.
zcore-button

Reference

  • Context

    The root container that manages the state and behavior of all toast messages. Must be wrapped around your application components to enable toast functionality. Handles message timing, and dismissal behavior.

    • Attributes

      • duration
        number
        /
        default: 4000

        The default duration in milliseconds that each toast message will be displayed before automatically closing. Can be overridden per message.

      • swipe-directions
        enum[]
        /
        default: right

        The allowed directions in which users can swipe to dismiss toast messages. Multiple directions can be specified to provide flexible dismissal options.

    • Workflows

      • showToast

        A function that triggers the display of a new toast message. Can be called from any component within the provider's scope.

        Parameters
        • title
          string
          /
          default: -

          The heading text of the toast message.

        • message
          string
          /
          default: -

          The main content text of the toast message.

        • color
          enum
          /
          default: neutral

          The visual style to apply to the toast message. Affects the appearance by adding the appropriate class.

        • role
          enum
          /
          default: status

          The ARIA role to assign to the toast message. Use alert for important messages that should interrupt the user.

        • duration
          number
          /
          default: 4000

          The default duration in milliseconds that each toast message will be displayed before automatically closing. Can be overridden per message.

        • data
          object
          /
          default: -

          Can be used to provide arbitrary data to a toast.

  • Portal

    Renders the toast messages into the CSS top layer, ensuring they appear above all other content regardless of stacking context. The portal's positioning can be customized through CSS.

    • Attributes

      • id
        string
        /
        default: -

        ID that is forwarded to the underlying container for DOM manipulation.

  • Region

    A container that manages the layout and accessibility of toast messages. Implements keyboard shortcuts for quick access to messages and proper ARIA attributes for screen reader support.

    • Attributes

      • aria-label
        string
        /
        default: -

        Accessible label for the toast region that describes its purpose to screen readers.

      • aria-labelled-by
        string
        /
        default: -

        References the ID of the element that labels the toast region.

      • hotkey-code
        string
        /
        default: F8

        The keyboard shortcut that, when pressed, will focus the first available toast message in the region.

      • spacing
        number
        /
        default: 0

        The vertical space in pixels to maintain between multiple toast messages when they are stacked.

  • Data context

    A component that provides the data context for individual toast messages. Automatically included within zcore-toast-region to manage and distribute toast message properties.

    • Formulas

      • color

        The visual style of the current toast message. Used to apply appropriate styling based on the message type.

      • data

        Arbitrary data that was provided via showToast.

      • duration

        The default duration in milliseconds that each toast message will be displayed before automatically closing.

      • id

        ID that is forwarded to the underlying container for DOM manipulation.

      • message

        The content text of the current toast message being displayed.

      • role

        The ARIA role of the current toast message, determining how it is announced to screen readers.

      • title

        The heading text of the current toast message being displayed.

  • Content

    The container for an individual toast message. Manages interactions, animations, and proper ARIA attributes for accessibility.

    • Attributes

      • aria-described-by
        string
        /
        default: -

        References the ID of the element containing the toast message content for accessibility.

      • aria-labelled-by
        string
        /
        default: -

        References the ID of the element containing the toast title for accessibility.

    • Classes

      • close-transition

        Applied during the closing transition of the toast message.

      • closing

        Applied when the toast is closing, enabling different animations for opening and closing states.

      • critical

        Applied when the toast represents a critical message or error.

      • open

        Applied when the toast message is visible.

      • open-transition

        Applied during the opening transition of the toast message.

      • success

        Applied when the toast represents a successful action or positive message.

      • swipe-out-bottom

        Applied when the toast is dismissed via a downward swipe gesture.

      • swipe-out-left

        Applied when the toast is dismissed via a leftward swipe gesture.

      • swipe-out-right

        Applied when the toast is dismissed via a rightward swipe gesture.

      • swipe-out-top

        Applied when the toast is dismissed via an upward swipe gesture.

      • warning

        Applied when the toast represents a warning message.

  • Close

    A wrapper component that must contain an zcore-button. The button provides functionality to manually dismiss the toast message and automatically receives appropriate ARIA attributes.

    Keyboard

    • F8

      When pressed, moves focus to the first available toast message in the region.

    • Tab

      Moves focus to the next focusable element within the toast message.

    • Shift
      +Tab

      Moves focus to the previous focusable element within the toast message.

    • Space

      When focus is on a toast close button, dismisses the toast message.

    • Enter

      When focus is on a toast close button, dismisses the toast message.

    • Escape

      When focus is on any element within a toast message, dismisses that toast.