GUILD OF GLEKS UIv21.19.0

gog-alert

Alert

A persistent, in-flow message — the one a toast cannot be. No timer, no queue, no overlay and no service: it renders where you write it and stays until your app removes it. What it adds over a styled <div> is what a class cannot do — it announces itself to a screen reader, and its close button hands the decision back to you.

Overview

Import the component and write the message as its content. severity says what the message means, heading is optional.

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

@Component({
  // ...
  imports: [AlertComponent],
})

Basic usage — a notice and an error, both already on the page when it loads:

Your changes are saved automatically.

Payment failed

The card issuer declined the charge. No money has left your account.
<!-- live="off": both are on the page when it loads. See "How it announces" below. -->
<gog-alert severity="info" live="off">Your changes are saved automatically.</gog-alert>

<gog-alert severity="danger" heading="Payment failed" live="off">
  The card issuer declined the charge. No money has left your account.
</gog-alert>

Examples

Severities and shapes

Five severities, each as a body only, with a heading, and with dismissible. The severity is carried by a thicker leading edge and the icon over the ordinary surface — not by a tinted fill. accent is the default and claims nothing: the library's own colour, for a notice that is neither good news nor bad. The edge is logical, so it moves to the right under dir="rtl". An alert has no interactive states of its own — only its close button does.

The card issuer declined the charge.

Payment failed

The card issuer declined the charge.

Payment failed

The card issuer declined the charge.
The card issuer declined the charge.

Payment failed

The card issuer declined the charge.

Payment failed

The card issuer declined the charge.
The card issuer declined the charge.

Payment failed

The card issuer declined the charge.

Payment failed

The card issuer declined the charge.
The card issuer declined the charge.

Payment failed

The card issuer declined the charge.

Payment failed

The card issuer declined the charge.
The card issuer declined the charge.

Payment failed

The card issuer declined the charge.

Payment failed

The card issuer declined the charge.
@for (severity of severities; track severity) {
  <gog-alert [severity]="severity" live="off">The card issuer declined the charge.</gog-alert>
  <gog-alert [severity]="severity" heading="Payment failed" live="off">
    The card issuer declined the charge.
  </gog-alert>
  <gog-alert [severity]="severity" heading="Payment failed" dismissible live="off">
    The card issuer declined the charge.
  </gog-alert>
}

Dismissible — pressed, not removed

dismissed means the close button was pressed. The alert stays in the DOM and your app decides what happens — hide it, retry, navigate. The handler runs while the close button still has focus, so there is somewhere to move focus from; a component that deleted itself would drop a keyboard reader back onto <body>. This example moves focus to the button that takes the alert's place — press the close button with the keyboard.

Payment failed

The card issuer declined the charge. No money has left your account.
@if (visible()) {
  <gog-alert
    severity="danger"
    heading="Payment failed"
    live="off"
    [dismissible]="true"
    (dismissed)="onDismissed()"
  >
    The card issuer declined the charge. No money has left your account.
  </gog-alert>
} @else {
  <gog-button #restore variant="outline" (gogClick)="visible.set(true)">
    Bring the alert back
  </gog-button>
}

Icons

Each severity brings its own glyph — accent borrows info's, because there is no icon for "this is a message". iconName overrides it, [iconName]="null" removes it, and a projected <ng-template gogAlertIcon> replaces it with your own markup.

An iconName overrides the severity's own glyph.
[iconName]="null" removes the icon, for a message whose words already carry it.
A projected gogAlertIcon template replaces it with your own markup.
<gog-alert severity="success" iconName="lock" live="off">
  An <code>iconName</code> overrides the severity's own glyph.
</gog-alert>

<gog-alert severity="info" [iconName]="null" live="off">
  <code>[iconName]="null"</code> removes the icon, for a message whose words already carry it.
</gog-alert>

<gog-alert severity="warning" live="off">
  <ng-template gogAlertIcon><gog-icon name="star" /></ng-template>
  A projected <code>gogAlertIcon</code> template replaces it with your own markup.
</gog-alert>

Long content

The body is projected, so it can hold a list or a link. It wraps, and the icon stays at the top rather than centring against the middle of a paragraph.

Three records could not be imported

Rows 14, 27 and 31 name a cost centre that does not exist in this workspace. Everything else in the file was imported. Download the three rows, fix them and re-upload only those — re-uploading the whole file would duplicate the rest.
<!-- The body is projected: it can hold a link. The icon stays at the top as it wraps. -->
<gog-alert severity="danger" heading="Three records could not be imported" live="off">
  Rows 14, 27 and 31 name a cost centre that does not exist in this workspace. Everything else in
  the file was imported. <a href="#overview">Download the three rows</a>, fix them and re-upload
  only those — re-uploading the whole file would duplicate the rest.
</gog-alert>

App-wide label — GOG_CONFIG

The close button's name is the one thing an alert reads from GOG_CONFIG: labels.closeAlert, "Dismiss message" by default. In an app the provider goes in app.config.ts — see Global Configuration.

Gespeichert.
<!-- The close button is named "Meldung schließen" here, from the config. -->
<gog-alert dismissible live="off">Gespeichert.</gog-alert>

How it announces

live is 'assertive', 'polite' or 'off', and defaults from the severity: danger and warning interrupt, the rest wait for a pause. That default is right for a message that appears — after a save, a failed request, a finished export.

It is wrong for a message that is already on the page when it loads, which is the case a documentation site shows most — every other example on this page sets live="off" for exactly that reason. A reader arriving at a page does not need to be interrupted about something that was already there, and the component cannot tell the two cases apart for you, so set 'off' yourself.

This workspace is read-only until the owner restores billing.
<div>
  <gog-button variant="outline" (gogClick)="saveFailed.set(!saveFailed())">
    {{ saveFailed() ? 'Clear the error' : 'Fail a save' }}
  </gog-button>
  <gog-button variant="outline" (gogClick)="exported.set(!exported())">
    {{ exported() ? 'Clear the notice' : 'Finish an export' }}
  </gog-button>
</div>

<!-- No `live`: it defaults from the severity. danger interrupts... -->
@if (saveFailed()) {
  <gog-alert severity="danger" heading="Could not save">
    The server did not answer. Your draft is kept in this tab.
  </gog-alert>
}

<!-- ...and info waits for a pause in what the reader is already hearing. -->
@if (exported()) {
  <gog-alert severity="info">The export is ready in your downloads.</gog-alert>
}

<!-- On the page from the start, so it says nothing: set live="off" for that case yourself. -->
<gog-alert severity="warning" live="off">
  This workspace is read-only until the owner restores billing.
</gog-alert>

The announcement is a copy, in a separate visually-hidden region beside the alert. That region is in the DOM from the alert's first render and empty; the text lands one render later, and that change is what a screen reader announces. A live region filled in the same pass as its own creation announces nothing — which is why putting aria-live on the alert itself looks like a simplification and silently breaks it. The type of the input is exported as GogAlertLive.

Accessibility

The visible alert is plain content with no role; the announcement is a separate region, and the icon is decorative.

  • Reading — the alert is not a landmark and needs no name: it is read where it stands, like any paragraph.
  • Icon — aria-hidden, so the severity has to be in the words as well: "Payment failed", not a red edge on "Payment".
  • Keyboard — the close button is a gog-button, named from GOG_CONFIG.labels.closeAlert. An alert never takes focus and never traps it; for a message that has to stop the reader until they answer it, use a dialog.
  • Announcing — see How it announces: live defaults from the severity, and an alert on the page from the start should set live="off".

API Reference

Inputs

NameTypeDefaultDescription
severityGogSeverity'accent''accent' | 'success' | 'danger' | 'warning' | 'info' — the same type gog-button, gog-progressbar and gogBadge take. Picks the edge colour and the glyph. 'accent' claims nothing, which is the right default for a notice that is neither good news nor bad.
headingstring | undefinedundefinedOptional title above the projected body. A one-line message needs none.
dismissiblebooleanfalseShows the close button and enables dismissed. The alert never removes itself — see the output below.
iconNameGogIconName | null | undefinedundefinedOverrides the severity's glyph. null removes the icon entirely, for a message whose words already carry its meaning.
liveGogAlertLive | undefinedfrom severity'assertive' | 'polite' | 'off'. Unset, danger and warning are assertive and the rest polite. Set 'off' for an alert that is already on the page when it loads.

Outputs

NamePayloadDescription
dismissedvoidThe close button was pressed. The alert is still in the DOM when this fires; hiding it, retrying or navigating is your decision.

Slots

DirectiveContextDescription
(content)—The message body. Its text is also what the live region announces.
gogAlertIconnoneAn <ng-template> whose markup replaces the leading icon.

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.labels.closeAlert — the close button, when dismissible

Styling Tokens

Every CSS custom property the alert 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-alert-bg / -color / -font-familySurface, body text colour and font stack. The ordinary surface and text pair, not a status tint — the library ships no per-status tint family, and the alert does not invent one.
--gog-alert-border-color / -border-width / -border-style / -radiusThe frame on three sides, and the corner radius.
--gog-alert-edge-color / -edge-widthThe leading edge that carries the severity, and the icon colour. Written by the severity class, which outranks a plain class of yours — to repaint a severity, set its own colour token below instead.
--gog-alert-accent-color / -success-color / -danger-color / -warning-color / -info-colorWhat each severity points --gog-alert-edge-color at. Default to the foundation status colours, so a theme that sets those needs nothing here.
--gog-alert-padding-y / -padding-x / -gap / -main-gapInner padding, the gap between icon, text and close button, and the gap between heading and body.
--gog-alert-icon-font-size / -icon-line-heightThe glyph, and the box that holds it.
--gog-alert-heading-color / -heading-font-size / -heading-font-weight / -heading-line-heightThe optional heading.
--gog-alert-body-font-size / -body-line-heightThe projected body.