Severities and shapes
Payment failed
Payment failed
Payment failed
Payment failed
Payment failed
Payment failed
Payment failed
Payment failed
Payment failed
Payment failed
gog-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.
Import the component and write the message as its content. severity says what the message means, heading is optional.
import { AlertComponent } from '@guildofgleks/ui';
@Component({
// ...
imports: [AlertComponent],
})
Basic usage — a notice and an error, both already on the page when it loads:
Payment failed
<!-- 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> 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.
Payment failed
Payment failed
Payment failed
Payment failed
Payment failed
Payment failed
Payment failed
Payment failed
Payment failed
Payment failed
@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>
}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
@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>
} 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.
iconName overrides the severity's own glyph.
[iconName]="null" removes the icon, for a message whose words already carry it.
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>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
<!-- 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>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.
<!-- The close button is named "Meldung schließen" here, from the config. -->
<gog-alert dismissible live="off">Gespeichert.</gog-alert>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.
<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.
The visible alert is plain content with no role; the announcement is a separate region, and the icon is decorative.
aria-hidden, so the severity has to be in the words as well: "Payment failed", not a red edge on "Payment". 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. live defaults from the severity, and an alert on the page from the start should set live="off". | Name | Type | Default | Description |
|---|---|---|---|
severity | GogSeverity | '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. |
heading | string | undefined | undefined | Optional title above the projected body. A one-line message needs none. |
dismissible | boolean | false | Shows the close button and enables dismissed. The alert never removes itself — see the output below. |
iconName | GogIconName | null | undefined | undefined | Overrides the severity's glyph. null removes the icon entirely, for a message whose words already carry its meaning. |
live | GogAlertLive | undefined | from 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. |
| Name | Payload | Description |
|---|---|---|
dismissed | void | The close button was pressed. The alert is still in the DOM when this fires; hiding it, retrying or navigating is your decision. |
| Directive | Context | Description |
|---|---|---|
(content) | — | The message body. Its text is also what the live region announces. |
gogAlertIcon | none | An <ng-template> whose markup replaces the leading icon. |
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 dismissibleEvery 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.
| Token | Description |
|---|---|
--gog-alert-bg / -color / -font-family | Surface, 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 / -radius | The frame on three sides, and the corner radius. |
--gog-alert-edge-color / -edge-width | The 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-color | What 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-gap | Inner padding, the gap between icon, text and close button, and the gap between heading and body. |
--gog-alert-icon-font-size / -icon-line-height | The glyph, and the box that holds it. |
--gog-alert-heading-color / -heading-font-size / -heading-font-weight / -heading-line-height | The optional heading. |
--gog-alert-body-font-size / -body-line-height | The projected body. |