GUILD OF GLEKS UIv21.19.0

gog-toast

Toast

Fire-and-forget notifications via ToastService, rendered by a positioned gog-toast-container — with per-corner stacking, action buttons, sticky and timed variants, and automatic deduping of repeated calls.

Overview

Import ToastContainerComponent and mount <gog-toast-container /> once, near the root of the app. Every ToastService call renders through that one outlet, however many places call it.

typescript
import { ToastContainerComponent, ToastService } from '@guildofgleks/ui';

@Component({
  // ...
  imports: [ToastContainerComponent],
})
export class AppComponent {
  // Mount <gog-toast-container /> once, near the root of your app.
}

Basic usage — inject the service and call a shorthand:

<!-- Renders into the one <gog-toast-container /> mounted at the app root. -->
<gog-button (gogClick)="save()">Save</gog-button>

Examples

Types and states

The type picks the edge colour and the glyph. A timed toast carries a progress bar counting down its duration; one queued behind the front of its stack ([isFront]="false", the third in each type) keeps the bar full and still. These are placed directly to show every state at once — an app never places a gog-toast itself; the container renders one per show().

Report exported.
Report exported.
Report exported.
Report exported.
Report exported.
Report exported.
Report exported.
Report exported.
Report exported.
Report exported.
Report exported.
Report exported.

<!-- Placed directly only to show every state at once; an app lets the container do it. -->
@for (generation of [generation()]; track generation) {
  @for (cell of cells; track cell.toast.id) {
    <gog-toast [toast]="cell.toast" [isFront]="cell.isFront" />
  }
}
<p>
  <gog-button variant="ghost" size="sm" (gogClick)="generation.set(generation() + 1)">
    Bring closed toasts back
  </gog-button>
</p>

Long messages and icons

The toast is at least --gog-toast-min-width wide and caps itself in ch of its own message font, against the viewport too; the message wraps and the actions go under it. iconName replaces the type's glyph — any built-in, or a name registered with provideGogIcons; iconTemplate takes any markup. The colour stays the type's.

The export finished, but 14 rows referenced a cost centre that no longer exists and were written with an empty value. Open the report to review them.
<!-- A long message wraps; the actions go under it. -->
@for (generation of [generation()]; track generation) {
  <gog-toast [toast]="long" />
}
<gog-button variant="outline" (gogClick)="withIconName()">iconName</gog-button>
<gog-button variant="outline" (gogClick)="withIconTemplate()">iconTemplate</gog-button>
<gog-button variant="ghost" (gogClick)="generation.set(generation() + 1)">Reset</gog-button>
<ng-template #star><gog-icon name="star-filled" /></ng-template>

Fully configurable

Every field feeds one show() call — message, type and position are all the caller's.

<gog-inputfield label="Message" [(value)]="message" />
<gog-select label="Type" [options]="types" [(value)]="type" />
<gog-select label="Position" [options]="positions" [(value)]="position" />
<div>
  <gog-button (gogClick)="preview()">Preview toast</gog-button>
</div>

Types, positions and the stack

Each corner is its own stack, oldest in front. Only the front toast counts down; the ones behind wait with a full bar and fan out on hover. Past the container's maxVisiblePerPosition (5 on this site) the rest queue out of sight and are not announced until they are shown.

<gog-button variant="outline" (gogClick)="oneOfEach()">One of each type</gog-button>
@for (position of positions; track position) {
  <gog-button variant="outline" (gogClick)="at(position)">{{ position }}</gog-button>
}
<!-- Each corner is its own stack; only its front toast counts down. -->
<gog-button variant="outline" (gogClick)="burst()">Queue 7 at top-right</gog-button>

Duration and sticky

duration overrides the 4000 ms default; isSticky disables auto-dismiss entirely. dismissAll() clears every corner.

@for (duration of durations; track duration) {
  <gog-button variant="outline" (gogClick)="timed(duration)">{{ duration }} ms</gog-button>
}
<gog-button variant="outline" (gogClick)="sticky()">isSticky</gog-button>
<gog-button variant="ghost" (gogClick)="dismissAll()">dismissAll()</gog-button>

Actions, show() and dismiss()

An action's onClick gets the toast; pressing one does not close it, so an Undo calls dismiss(toast.id) itself. show() and the four shorthands return that id.

nothing yet

<gog-button variant="outline" (gogClick)="move()">Move with Undo</gog-button>

<p>{{ lastEvent() }}</p>

dedupeKey

A show() whose dedupeKey matches a toast still open replaces it in place — new message, timer restarted, announced again — instead of stacking another. Unset, the key is derived from the message, type, icon, position and action labels, so the same toast fired twice is one toast; this button changes its message each time, so it names a key.

<gog-button variant="outline" (gogClick)="save()">Save draft</gog-button>

App-wide defaults

GOG_CONFIG.toast.position and .duration set the corner and the time for every toast; a show() call still overrides them. They are read once, by the root ToastService, so they belong in app.config.ts — a provideGogConfig lower down never reaches them. labels.closeToast names the close button. See Global Configuration.

typescript
import { provideGogConfig } from '@guildofgleks/ui';

bootstrapApplication(App, {
  providers: [
    provideGogConfig({
      toast: {
        position: 'top-right',
        duration: 6000,
      },
    }),
  ],
});

Accessibility

A toast carries no role or aria-live. The container owns two live regions, mounted before any toast exists, and copies each shown toast's message into one.

  • Announcements — one region is polite, one assertive; the toast's type picks which (assertive for error and warning, polite otherwise). A live region has to exist before the text lands in it to be announced at all, which is why the toasts do not carry their own. The message leaves the region when the toast does.
  • Queued toasts past maxVisiblePerPosition are not announced until they are shown.
  • Keyboard — the close button and the actions are real buttons in the tab order. The close button is named by GOG_CONFIG.labels.closeToast.
  • Timing — hovering a toast pauses its countdown. Under prefers-reduced-motion the progress bar still reports the time left, in twenty discrete steps rather than a slide. Put anything a user must act on in a sticky toast or somewhere that does not expire.

API Reference

ToastConfig

NameTypeDefaultDescription
messagestringrequiredThe toast text.
type'success' | 'error' | 'warning' | 'info''info'Drives the accent color, the default icon, and which live region announces the toast (assertive for error/warning, polite otherwise).
iconNameGogIconNameper-type defaultOverrides the type-based default icon.
iconTemplateTemplateRef<unknown> | nullnullFully custom icon, taking priority over iconName.
actionsToastAction[][]Action buttons rendered in the toast: { label, onClick(toast), iconName?, iconTemplate? }.
isStickybooleanfalseDisables auto-dismiss entirely — the toast stays until dismissed manually or via dismissAll().
durationnumberGOG_CONFIG.toast.duration ?? 4000Auto-dismiss delay in ms. Ignored when isSticky is true.
position'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'GOG_CONFIG.toast.position ?? 'bottom-right'Which corner stack this toast joins. Each corner stacks and animates independently.
dedupeKeystringderived from message/type/icon/iconTemplate/position/actionsToasts sharing a dedupe key collapse into one instance instead of stacking duplicates — calling show() again just bumps its revision and restarts the timer. Pass '' to opt a specific call out of deduping.

ToastService methods

SignatureDescription
show(config: ToastConfig): stringShows a toast with full control over every option. Returns its id.
success(message, config?) / error(...) / warning(...) / info(...)Shorthands for show() that set type for you; config overrides everything else.
dismiss(id: string): voidDismisses a single toast by id.
dismissAll(): voidDismisses every visible toast, including sticky ones.

gog-toast-container — Inputs

NameTypeDefaultDescription
maxVisiblePerPositionnumber5Caps how many toasts stack at once per corner; the oldest (front of queue) stay visible first.

Global Configuration

Set any of these once with provideGogConfig() instead of repeating them on every instance — an instance's own input still wins when it sets one itself. See Global Configuration for the full reference.

  • GOG_CONFIG.toast.position
  • GOG_CONFIG.toast.duration
  • GOG_CONFIG.labels.closeToast

Styling Tokens

Every CSS custom property the toast paints with. Override any of them — on a single instance, a subtree, or a theme — to restyle it. See the Theming guide for the full token-layering model, or the Theme Generator to tweak these live.

TokenDescription
--gog-toast-bg / -color / -borderCard surface.
--gog-toast-success-color / -error-color / -warning-color / -info-colorAccent stripe and icon color, per toast type.
--gog-toast-padding / -radiusCard padding and corner radius.
--gog-toast-stack-peek / -stack-scale-step / -stack-expanded-gapCard-stack geometry when several toasts are visible at once.