Toast

Purpose

The Toast reusable renders the UI container for toast notifications. All toast state and behavior is owned by the global Alpine store $store.toast (defined in Assets/js/theme.js).

Many other components/reusables use $store.toast to show success/error/info feedback.

Where it's rendered

This reusable is mounted once in the layout (Structure/LayoutA.liquid):

{% render 'Reusables\\Toast\\Default' %}

Inputs (Liquid render parameters)

This reusable is rendered without Liquid parameters.

Model shape (storefront example)

Required: provide a real storefront model sample.

To document the contract correctly, we use the real runtime shape of the Alpine toast store (Alpine.store('toast')). The store is code-defined (not delivered as a page model), but the “real” contract is the store object that exists at runtime.

Sanitized runtime shape (based on the actual store definition in Assets/js/theme.js) focusing on the fields used by the template:

{
  "messages": [
    {
      "id": "Toast Id",
      "message": "Sample text",
      "iconClass": "ic-check-circle-fill",
      "type": "success",
      "extraHtml": "<p>Sample extra HTML</p>",
      "extraHtmlIndex": 0,
      "keepAlive": false
    },
    ...
  ]
}

What each toast message prop means:

id

Unique identifier generated by the toast store.

Used by the close button ($store.toast.remove(id)) and by the auto-dismiss timer.

message

The main text shown in the toast (x-text="msg.message").

iconClass

Optional icon CSS class (e.g. ic-check-circle-fill, ic-warning).

When provided, the icon span is shown and receives this class.

type

Controls the visual variant class:

success → toast__box--success

error → toast__box--error

info → toast__box--info

extraHtml

Optional extra content rendered as HTML (x-html="msg.extraHtml").

Should be considered trusted/sanitized before being passed to the toast store.

extraHtmlIndex

Optional number kept on the message object.

The template binds it to data-toast-index on the close button.

It does not affect rendering by itself.

keepAlive

When true, the toast store will not auto-dismiss the message.

When false, the store auto-removes it after 5000ms.

Template behavior (Liquid + Alpine)

Shows the toast container when $store.toast.messages.length > 0.

Renders one toast per message in $store.toast.messages.

Applies UI variant classes based on message type:

toast__box--success

toast__box--error

toast__box--info

Each toast box:

Shows an icon when msg.iconClass exists.

Renders main message text from msg.message.

Optionally renders extra HTML when msg.extraHtml exists.

Close button calls:

$store.toast.remove(msg.id)

Accessibility:

role="alert"

aria-live="assertive"

aria-atomic="true"

JavaScript

Reusable JS file

Reusables/Toast/Default.js defines an empty object:

const toastreusabledefault = {};

The reusable itself does not own logic; it’s purely UI.

Global Alpine store (the real behavior)

In Assets/js/theme.js the toast store is defined as:

Alpine.store('toast', { ... })

Contract:

messages: array

_counter: internal counter

Methods:

add(message, iconClass, type, keepAlive, extraHtml, extraHtmlIndex)

Creates a unique id and pushes a new message to messages.

If keepAlive is false, auto-removes the toast after 5000ms.

Returns the created toast id.

What each argument does:

message

Value stored as msg.message and rendered as plain text.

iconClass

Value stored as msg.iconClass and applied to the icon span.

type

Value stored as msg.type and drives the toast__box--* class.

keepAlive

Value stored as msg.keepAlive.

When false, the store schedules auto-dismiss.

extraHtml

Value stored as msg.extraHtml and rendered with x-html.

extraHtmlIndex

Value stored as msg.extraHtmlIndex and bound to data-toast-index.

removeAll()

Clears the messages array.

remove(id)

Removes a single toast message by id.

Global Alpine stores

This reusable uses:

$store.toast

messages[]

remove(id)

Additionally, other stores interact with toast (notably $store.modal.close() clears toasts if any exist).

Services / API calls

This reusable does not call services.

Dependencies

Liquid: Reusables/Toast/Default.liquid

JS: Reusables/Toast/Default.js

Translations: Reusables/Toast/Default.json

Alpine store:

$store.toast (defined in Assets/js/theme.js)

Notes

Toast rendering uses msg.extraHtml via x-html, so any extra HTML should be trusted/sanitized before being passed to $store.toast.add(...).

The close button binds :data-toast-index="msg.extraHtmlIndex", but removal is performed by msg.id.

Toast

Purpose#

Where it's rendered#

Inputs (Liquid render parameters)#

Model shape (storefront example)#

Template behavior (Liquid + Alpine)#

JavaScript#

Reusable JS file#

Global Alpine store (the real behavior)#

add(message, iconClass, type, keepAlive, extraHtml, extraHtmlIndex)#

removeAll()#

remove(id)#

Global Alpine stores#

Services / API calls#

Dependencies#

Notes#