GameToast

Methods

.effectCallback({ scene, round })

.show(text, opts)

.hide()

.triggerCallback(triggerName, event)

.define(tag, registry)

.subscribe(context, callback)

CSS Custom Properties

Shadow DOM Parts

Trigger-based feedback messages that fire on triggers. Uses the same trigger system as <game-sample> — state triggers (pass, fail, start, round, complete, timeout, tier-up) and DOM triggers (input, click, etc.).

Toasts come in two modes: ephemeral (default) and persistent. Ephemeral toasts are short-lived messages that drift upward and fade out — multiple can fire and stack simultaneously. Persistent toasts stay visible until the state changes, making them ideal for contextual commentary during gameplay.

Attributes

trigger

string -- The trigger condition. See the Triggers reference for all available values.

persist

boolean -- When present, the toast stays visible instead of fading out. The text is replaced each time the trigger fires. Automatically hides when the game leaves the relevant state (e.g. a pass persist toast hides when leaving between).

position

"center" | "bottom" | "top" | "inline" -- Positioning mode. Defaults to "center" (fixed, centered on screen). "bottom" and "top" anchor to the edges with a pill-shaped background (ideal for commentary captions). "inline" uses static positioning for embedding in layouts.

use-feedback

boolean -- When present, shows the lastFeedback signal value directly instead of selecting from options or text content. Useful for displaying the feedback string passed to GameRoundPassEvent.

set-feedback

boolean -- When present, writes the displayed text back to the shell's lastFeedback signal when the toast fires. Allows downstream components (other toasts, <game-between>, etc.) to observe the same message.

duration

string? -- Override the animation duration for ephemeral toasts, in bare milliseconds (e.g. "800", "2000"). The runtime appends ms when applying the value, so do not include a unit suffix. When absent, the --game-toast-duration CSS custom property (default 1s) controls the duration. Has no effect on persistent toasts.

value

string? -- When set, the toast only fires when the triggering event's value matches this string. Used for fine-grained control, for example firing only on a specific countdown second from a timer tick.

Text Resolution

When a toast fires, the message text is resolved in priority order:

1. lastFeedback signal -- If the use-feedback attribute is present and the game code provided explicit feedback text (e.g. new GameRoundPassEvent(342, "342ms")), that text is used.
2. <option> children -- A random <option> is picked from the pool, filtered by any when-* conditions.
3. Static text content -- The element's own text content.

Declarative Messages with <option>

Use <option> children to define a custom message pool. A random option is picked each time the toast fires:

<game-toast when-some-scene="playing between paused" trigger="pass">
  <option>Brilliant!</option>
  <option>Superb!</option>
  <option>Flawless!</option>
  <option>Crushed it!</option>
</game-toast>

Options can have condition attributes for filtering:

<game-toast when-some-scene="playing between paused" trigger="pass">
  <option>Nice!</option>
  <option>Good one!</option>
  <option when-some-trophy="streak-3">Hat trick master!</option>
  <option when-min-score="15">You're on fire!</option>
  <option when-min-pass-streak="3">On a roll!</option>
</game-toast>

Options that don't match are filtered out before random selection. Base options (no when-* attributes) are always eligible.

Methods

.show(text, opts?)

Show a toast message programmatically, independent of triggers.

Parameters:

• text -- string -- The message to display.
• opts -- object (optional):
  • color -- string -- CSS colour override.
  • duration -- number -- Duration in milliseconds (default: 1000).

const toast = document.querySelector("game-toast");
toast.show("PERFECT!", { color: "#24C78B", duration: 1200 });
toast.show("+1 LIFE", { color: "#FFD700" });

.hide()

Hide a persistent toast (fades out). No-op on ephemeral toasts.

Signal Access

Usage

The simplest feedback setup — uses the lastFeedback signal:

<game-toast
  when-some-scene="playing between paused"
  trigger="pass"
  use-feedback
></game-toast>
<game-toast
  when-some-scene="playing between paused"
  trigger="fail"
  use-feedback
></game-toast>

Custom word pools:

<game-toast when-some-scene="playing between paused" trigger="pass">
  <option>Nailed it!</option>
  <option>Perfect!</option>
  <option>Incredible!</option>
</game-toast>

<game-toast when-some-scene="playing between paused" trigger="fail">
  <option>Missed!</option>
  <option>Not quite!</option>
  <option>Try again!</option>
</game-toast>

Fixed text for non-feedback triggers:

<game-toast when-some-scene="playing between paused" trigger="tier-up"
  >Level Up!</game-toast
>
<game-toast when-some-scene="playing between paused" trigger="complete"
  >Game Over!</game-toast
>
<game-toast when-some-scene="playing between paused" trigger="start"
  >Go!</game-toast
>

Score-filtered toasts (using conditions):

<game-toast
  when-some-scene="playing between paused"
  trigger="complete"
  when-min-score="20"
  >Perfect score!</game-toast
>
<game-toast
  when-some-scene="playing between paused"
  trigger="complete"
  when-max-score="5"
  >Better luck next time</game-toast
>

Streak-aware commentary (persistent, positioned at bottom):

<game-toast
  when-some-scene="playing between paused"
  trigger="round"
  persist
  position="bottom"
>
  <option when-min-pass-streak="3">On fire!</option>
  <option when-min-pass-streak="3">Can't be stopped!</option>
  <option when-min-fail-streak="3">Keep trying!</option>
  <option when-min-fail-streak="3">You'll get there</option>
  <option>Nice work!</option>
  <option>Keep going!</option>
</game-toast>

Per-trigger styling:

game-toast[trigger="pass"] {
  --game-toast-color: #00e5b0;
}
game-toast[trigger="tier-up"] {
  --game-toast-color: #fbbf24;
  --game-toast-size: 36px;
}