toast

The toast component is used to provide short and succint feedback to a user after they have completed an interaction or an asynchronous task completed.

The default Toast

The default Toast will:

  • Use the default style
  • Be light dismissable (click outside)
  • Be dismissable by pressing the escape key
  • Have an ARIA role of status which maps to an aria-live state of polite.

An alert Toast

When the Toast's ARIA role is set to alert, the Toast will:

  • Use the default style unless a toast_style of critical or success was set.
  • Will not be light dismissable
  • Be dismissable by pressing the escape key
  • Be dismissable by pressing the close button
  • Have an ARIA role of alert which maps to an aria-live state of assertive.

A timer-based Toast

A timer based Toast is enabled by setting the dismissable-timer value of the dismissable_by property. You can also set a timer_duration. If no timer_duration is provided the Toast will use a default of five seconds.

A timer based Toast will:

  • Use the default style unless a toast_style of critical or success was set. (Note: One should generally avoid combining critical with a timer only toast as a user might miss the message. For Toast messages which are critical it is best to use the alert style Toast.)
  • Will not be light dismissable
  • Will not be dismissable by pressing the escape key
  • Will not be dismissable by pressing the close button
  • Have an ARIA role of status which maps to an aria-live state of polite.

You can further customize how a Toast can be dismissed if the defined Toast types above does not fit your needs.

  • To allow a Toast to be light dismissed, set the dismissable-light value of the dismissable_by property.
  • To allow a Toast to be dismissed by the Escape key and a close button, set the dismissable-user value of the dismissable_by property.

The above can be combined with or without the dismissable-timer value of the dismissable_by property.

Information

Folder
src/components/elements/toast

Files

Schema 
// src/components/elements/toast/schema.yaml

$schema: http://json-schema.org/draft-07/schema
$id: elements/toast
type: object
required:
  - id
additionalProperties: false
properties:
  dismissible_by:
    type: array
    items:
      type: string
      enum:
        - dismissable-light
        - dismissable-timer
        - dismissable-user
  id:
    type: string
  timer_duration:
    type: number
  toast_style:
    type: string
    enum:
      - critical
      - default
      - success
  toast_role:
    type: string
    enum:
      - alert
      - status
Mocks 
// src/components/elements/toast/mocks.yaml

$hidden: true
id: support_email_sent
$variants:
  - $name: default
  - $name: alert
    toast_role: alert
  - $name: alert error
    toast_role: alert
    toast_style: critical
  - $name: alert success
    toast_role: alert
    toast_style: success
  - $name: callback
    toast_role: alert
  - $name: timer
    dismissible_by:
      - dismissable-timer
    timer_duration: 2000
    toast_role: status
  - $name: timer and close button
    dismissible_by:
      - dismissable-user
      - dismissable-timer
    toast_role: status
  - $name: timer, close and light dismiss
    dismissible_by:
      - dismissable-light
      - dismissable-user
      - dismissable-timer
    timer_duration: 3000
    toast_role: status
Template 
// src/components/elements/toast/toast.twig

{{ attach_library('finstral_global/element-toast') }}

{% set role = toast_role|default("status") %}
{% set popover_type = role == "alert" or dismissible_by ? "manual" : "auto" %}
{% set user_dismissable = role == "alert" or "dismissable-user" in dismissible_by %}

<finstral-toast
	class="Toast Toast--{{ toast_style|default('default') }}"
	id="{{ id }}"
	message=""
	popover="{{ popover_type }}"
	toast-role="{{ role }}"
	{% if "dismissable-timer" in dismissible_by %} timer-duration="{{ timer_duration|default(5000) }}" {%- endif -%}
	{% if dismissible_by %} {{ dismissible_by|join(" ") }} {%- endif -%}
>
	<output></output>
	<button class="Toast-close" type="button" {% if not user_dismissable %} hidden {%- endif -%}>
		<span class="visually-hidden">{{ "global.close_button"|tc }}</span>
		{% include "@elements/icon/icon.twig" with {
			"name": "close",
		} only %}
	</button>
</finstral-toast>

Variants

default
Open
alert
Open
alert error
Open
alert success
Open
callback
Open
timer
Open
timer and close button
Open
timer, close and light dismiss
Open