Alert

<gui-alert> is a message box. Its children are the message: the element keeps your markup as it is, styles the box around it and gives it a role, so screen readers announce it.

Your trial ends on 14 November. Pick a plan to keep your projects.

import { GuiAlert } from '@golemui/gui-components/react';
import '@golemui/gui-components/index.css';

export function AlertBasic() {
  return (
    <GuiAlert variant="info">
      Your trial ends on 14 November. Pick a plan to keep your projects.
    </GuiAlert>
  );
}

import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@golemui/gui-components/alert';

@Component({
  selector: 'app-alert-basic',
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <gui-alert variant="info">
      Your trial ends on 14 November. Pick a plan to keep your projects.
    </gui-alert>
  `,
})
export class AlertBasicComponent {}

<script setup lang="ts">
import '@golemui/gui-components/alert';
import '@golemui/gui-components/index.css';
</script>

<template>
  <gui-alert variant="info">
    Your trial ends on 14 November. Pick a plan to keep your projects.
  </gui-alert>
</template>

import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';
import '@golemui/gui-components/alert';
import '@golemui/gui-components/index.css';

@customElement('alert-basic')
export class AlertBasic extends LitElement {
  protected override createRenderRoot() {
    return this;
  }

  override render() {
    return html`
      <gui-alert variant="info"
        >Your trial ends on 14 November. Pick a plan to keep your
        projects.</gui-alert
      >
    `;
  }
}

<gui-alert variant="info">Your trial ends on 14 November. Pick a plan to keep your projects.</gui-alert>

Usage

The element’s entry point is @golemui/gui-components/alert, which registers <gui-alert> and nothing else. To install the package and load the stylesheet, see Installation.

The @golemui/gui-components/react components have typed props and an on* prop for each event. React 18 or later.

import { GuiAlert } from '@golemui/gui-components/react';
import '@golemui/gui-components/index.css';

export function AlertExample() {
  return (
    <GuiAlert
      variant="warning"
    >
      Your trial ends on 14 November.
    </GuiAlert>
  );
}

Add CUSTOM_ELEMENTS_SCHEMA to the component that uses the tags, and the stylesheet to styles in angular.json.

import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@golemui/gui-components/alert';

@Component({
  selector: 'app-alert-example',
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <gui-alert
      variant="warning"
    >
      Your trial ends on 14 November.
    </gui-alert>
  `,
})
export class AlertExampleComponent {}

"styles": ["node_modules/@golemui/gui-components/lib/styles/index.css"]

Tell Vue's compiler that gui-* tags are custom elements, and add the typings once for typed props and @gui-* handlers.

<script setup lang="ts">
import '@golemui/gui-components/alert';
import '@golemui/gui-components/index.css';
</script>

<template>
  <gui-alert
    variant="warning"
  >
    Your trial ends on 14 November.
  </gui-alert>
</template>

vue({
  template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith('gui-') } },
});

import type {} from '@golemui/gui-components/vue';

The page's stylesheet styles the gui-* elements, so it only reaches them outside a shadow root. Render the host component into the light DOM too, as below, or load the stylesheet into its shadow root.

import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';
import '@golemui/gui-components/alert';
import '@golemui/gui-components/index.css';

@customElement('alert-example')
export class AlertExample extends LitElement {
  protected override createRenderRoot() {
    return this;
  }

  override render() {
    return html`
      <gui-alert
        variant="warning"
      >
        Your trial ends on 14 November.
      </gui-alert>
    `;
  }
}

With any bundler, such as Vite. Import the element once, anywhere, and use the tag in your markup.

<gui-alert variant="warning">
  Your trial ends on 14 November.
</gui-alert>

<script type="module" src="./main.js"></script>

import '@golemui/gui-components/alert';
import '@golemui/gui-components/index.css';

Write the message inside it, as text or markup.

API

Properties

Property	Type	Default	Description
`variant`	`GuiAlertVariant`	`'default'`	The intent the alert shows.

Examples

Variants

variant sets the intent: default, the neutral box, info, success, warning or error. The color is not the only cue: say what happened in the message itself.

Ada Lovelace joined the workspace.

The new reports are ready to try.

Your changes are saved.

Your storage is 90% full.

The payment didn't go through.

import { GuiAlert } from '@golemui/gui-components/react';
import '@golemui/gui-components/index.css';

export function AlertVariants() {
  return (
    <div className="gui-grid">
      <div className="gui-grid__cell">
        <GuiAlert role="status">Ada Lovelace joined the workspace.</GuiAlert>
      </div>
      <div className="gui-grid__cell">
        <GuiAlert variant="info" role="status">
          The new reports are ready to try.
        </GuiAlert>
      </div>
      <div className="gui-grid__cell">
        <GuiAlert variant="success" role="status">
          Your changes are saved.
        </GuiAlert>
      </div>
      <div className="gui-grid__cell">
        <GuiAlert variant="warning" role="status">
          Your storage is 90% full.
        </GuiAlert>
      </div>
      <div className="gui-grid__cell">
        <GuiAlert variant="error" role="status">
          The payment didn't go through.
        </GuiAlert>
      </div>
    </div>
  );
}

import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@golemui/gui-components/alert';

@Component({
  selector: 'app-alert-variants',
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <div class="gui-grid">
      <div class="gui-grid__cell">
        <gui-alert role="status">Ada Lovelace joined the workspace.</gui-alert>
      </div>
      <div class="gui-grid__cell">
        <gui-alert variant="info" role="status">
          The new reports are ready to try.
        </gui-alert>
      </div>
      <div class="gui-grid__cell">
        <gui-alert variant="success" role="status">
          Your changes are saved.
        </gui-alert>
      </div>
      <div class="gui-grid__cell">
        <gui-alert variant="warning" role="status">
          Your storage is 90% full.
        </gui-alert>
      </div>
      <div class="gui-grid__cell">
        <gui-alert variant="error" role="status">
          The payment didn't go through.
        </gui-alert>
      </div>
    </div>
  `,
})
export class AlertVariantsComponent {}

<script setup lang="ts">
import '@golemui/gui-components/alert';
import '@golemui/gui-components/index.css';
</script>

<template>
  <div class="gui-grid">
    <div class="gui-grid__cell">
      <gui-alert role="status">Ada Lovelace joined the workspace.</gui-alert>
    </div>
    <div class="gui-grid__cell">
      <gui-alert variant="info" role="status">
        The new reports are ready to try.
      </gui-alert>
    </div>
    <div class="gui-grid__cell">
      <gui-alert variant="success" role="status">
        Your changes are saved.
      </gui-alert>
    </div>
    <div class="gui-grid__cell">
      <gui-alert variant="warning" role="status">
        Your storage is 90% full.
      </gui-alert>
    </div>
    <div class="gui-grid__cell">
      <gui-alert variant="error" role="status">
        The payment didn't go through.
      </gui-alert>
    </div>
  </div>
</template>

import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';
import '@golemui/gui-components/alert';
import '@golemui/gui-components/index.css';

@customElement('alert-variants')
export class AlertVariants extends LitElement {
  protected override createRenderRoot() {
    return this;
  }

  override render() {
    return html`
      <div class="gui-grid">
        <div class="gui-grid__cell">
          <gui-alert role="status"
            >Ada Lovelace joined the workspace.</gui-alert
          >
        </div>
        <div class="gui-grid__cell">
          <gui-alert variant="info" role="status"
            >The new reports are ready to try.</gui-alert
          >
        </div>
        <div class="gui-grid__cell">
          <gui-alert variant="success" role="status"
            >Your changes are saved.</gui-alert
          >
        </div>
        <div class="gui-grid__cell">
          <gui-alert variant="warning" role="status"
            >Your storage is 90% full.</gui-alert
          >
        </div>
        <div class="gui-grid__cell">
          <gui-alert variant="error" role="status"
            >The payment didn't go through.</gui-alert
          >
        </div>
      </div>
    `;
  }
}

<div class="gui-grid">
  <div class="gui-grid__cell">
    <gui-alert role="status">Ada Lovelace joined the workspace.</gui-alert>
  </div>
  <div class="gui-grid__cell">
    <gui-alert variant="info" role="status">The new reports are ready to try.</gui-alert>
  </div>
  <div class="gui-grid__cell">
    <gui-alert variant="success" role="status">Your changes are saved.</gui-alert>
  </div>
  <div class="gui-grid__cell">
    <gui-alert variant="warning" role="status">Your storage is 90% full.</gui-alert>
  </div>
  <div class="gui-grid__cell">
    <gui-alert variant="error" role="status">The payment didn't go through.</gui-alert>
  </div>
</div>

Rich content

The message can be any markup, such as a paragraph with links to the fields that need attention. The element never changes it.

Two fields need your attention: Billing email and City.

import { GuiAlert } from '@golemui/gui-components/react';
import '@golemui/gui-components/index.css';

export function AlertContent() {
  return (
    <GuiAlert variant="warning" role="status">
      <p>
        Two fields need your attention:{' '}
        <a href="#billing-email">Billing email</a> and{' '}
        <a href="#billing-city">City</a>.
      </p>
    </GuiAlert>
  );
}

import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@golemui/gui-components/alert';

@Component({
  selector: 'app-alert-content',
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <gui-alert variant="warning" role="status">
      <p>
        Two fields need your attention:
        <a href="#billing-email">Billing email</a> and
        <a href="#billing-city">City</a>.
      </p>
    </gui-alert>
  `,
})
export class AlertContentComponent {}

<script setup lang="ts">
import '@golemui/gui-components/alert';
import '@golemui/gui-components/index.css';
</script>

<template>
  <gui-alert variant="warning" role="status">
    <p>
      Two fields need your attention:
      <a href="#billing-email">Billing email</a> and
      <a href="#billing-city">City</a>.
    </p>
  </gui-alert>
</template>

import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';
import '@golemui/gui-components/alert';
import '@golemui/gui-components/index.css';

@customElement('alert-content')
export class AlertContent extends LitElement {
  protected override createRenderRoot() {
    return this;
  }

  override render() {
    return html`
      <gui-alert variant="warning" role="status">
        <p>
          Two fields need your attention:
          <a href="#billing-email">Billing email</a> and
          <a href="#billing-city">City</a>.
        </p>
      </gui-alert>
    `;
  }
}

<gui-alert variant="warning" role="status">
  <p>
    Two fields need your attention: <a href="#billing-email">Billing email</a> and
    <a href="#billing-city">City</a>.
  </p>
</gui-alert>

Messages that update

An alert has the alert role, which interrupts the screen reader to read it. For a message that can wait, such as a save confirmation, set role="status": screen readers read it when they finish what they are reading. Change the alert’s content, or its variant, from your own code: the element keeps whatever you put in it.

You have unsaved changes.

import { useState } from 'react';
import { GuiAlert, GuiButton } from '@golemui/gui-components/react';
import type { GuiAlertVariant } from '@golemui/gui-components';
import '@golemui/gui-components/index.css';

export function AlertLive() {
  const [variant, setVariant] = useState<GuiAlertVariant>('default');
  const [message, setMessage] = useState('You have unsaved changes.');

  const save = () => {
    setVariant('success');
    setMessage(`Profile saved at ${new Date().toLocaleTimeString()}.`);
  };

  return (
    <div className="gui-grid">
      <div className="gui-grid__cell">
        <GuiAlert id="profile-status" role="status" variant={variant}>
          {message}
        </GuiAlert>
      </div>
      <div className="gui-grid__cell">
        <GuiButton id="profile-save" label="Save profile" onClick={save} />
      </div>
    </div>
  );
}

import { Component, CUSTOM_ELEMENTS_SCHEMA, signal } from '@angular/core';
import type { GuiAlertVariant } from '@golemui/gui-components';
import '@golemui/gui-components/alert';
import '@golemui/gui-components/button';

@Component({
  selector: 'app-alert-live',
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <div class="gui-grid">
      <div class="gui-grid__cell">
        <gui-alert id="profile-status" role="status" [variant]="variant()">
          {{ message() }}
        </gui-alert>
      </div>
      <div class="gui-grid__cell">
        <gui-button
          id="profile-save"
          label="Save profile"
          (click)="save()"
        ></gui-button>
      </div>
    </div>
  `,
})
export class AlertLiveComponent {
  variant = signal<GuiAlertVariant>('default');
  message = signal('You have unsaved changes.');

  save() {
    this.variant.set('success');
    this.message.set(`Profile saved at ${new Date().toLocaleTimeString()}.`);
  }
}

<script setup lang="ts">
import { ref } from 'vue';
import type { GuiAlertVariant } from '@golemui/gui-components';
import '@golemui/gui-components/alert';
import '@golemui/gui-components/button';
import '@golemui/gui-components/index.css';

const variant = ref<GuiAlertVariant>('default');
const message = ref('You have unsaved changes.');

function save() {
  variant.value = 'success';
  message.value = `Profile saved at ${new Date().toLocaleTimeString()}.`;
}
</script>

<template>
  <div class="gui-grid">
    <div class="gui-grid__cell">
      <gui-alert id="profile-status" role="status" :variant="variant">
        {{ message }}
      </gui-alert>
    </div>
    <div class="gui-grid__cell">
      <gui-button
        id="profile-save"
        label="Save profile"
        @click="save"
      ></gui-button>
    </div>
  </div>
</template>

import { LitElement, html } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import '@golemui/gui-components/alert';
import '@golemui/gui-components/button';
import '@golemui/gui-components/index.css';

@customElement('alert-live')
export class AlertLive extends LitElement {
  @state() private savedAt?: string;

  protected override createRenderRoot() {
    return this;
  }

  private save() {
    this.savedAt = new Date().toLocaleTimeString();
  }

  override render() {
    return html`
      <div class="gui-grid">
        <div class="gui-grid__cell">
          <gui-alert
            id="profile-status"
            role="status"
            .variant=${this.savedAt ? 'success' : 'default'}
          >
            ${this.savedAt
              ? `Profile saved at ${this.savedAt}.`
              : 'You have unsaved changes.'}
          </gui-alert>
        </div>
        <div class="gui-grid__cell">
          <gui-button
            id="profile-save"
            label="Save profile"
            @click=${this.save}
          ></gui-button>
        </div>
      </div>
    `;
  }
}

<div class="gui-grid">
  <div class="gui-grid__cell">
    <gui-alert id="profile-status" role="status">You have unsaved changes.</gui-alert>
  </div>
  <div class="gui-grid__cell">
    <gui-button id="profile-save" label="Save profile"></gui-button>
  </div>
</div>

<script type="module">
  const status = document.querySelector('#profile-status');

  document.querySelector('#profile-save').addEventListener('click', () => {
    status.variant = 'success';
    status.textContent = `Profile saved at ${new Date().toLocaleTimeString()}.`;
  });
</script>

Styling

Anatomy

<gui-alert> renders nothing of its own. It is your content, with a role:

<gui-alert variant="info" role="alert">
  Your trial ends on 14 November. Pick a plan to keep your projects.
</gui-alert>

The alert has no classes. Style it by tag, and each variant by its attribute, which the element reflects when you set the property:

Selector	Part
`gui-alert`	The box, in every variant.
`gui-alert[variant='info']`	The info box.
`gui-alert[variant='error']`	The error box.

The box is a flex row, display: flex, so the hidden attribute doesn’t hide it. Remove the alert from the page instead, or hide it with your own CSS.

Tokens

The alert reads these design tokens. Set them on :root to change every alert, or on any element to change the alerts inside it:

Token	What it styles
`--gui-widget-size`	The smallest height of the box.
`--gui-space-4`	The space at the start and end of the box.
`--gui-radius-md`	The corner radius.
`--gui-font-sm`	The text size.
`--gui-bg-surface-hover`, `--gui-border-default`, `--gui-text-default`	The background, border and text of `default`.
`--gui-intent-info-bg`, `--gui-intent-info`, `--gui-intent-info-text`	The background, border and text of `info`.
`--gui-intent-success-bg`, `--gui-intent-success`, `--gui-intent-success-text`	The background, border and text of `success`.
`--gui-intent-warning-bg`, `--gui-intent-warning`, `--gui-intent-warning-text`	The background, border and text of `warning`.
`--gui-intent-error-bg`, `--gui-intent-error`, `--gui-intent-error-text`	The background, border and text of `error`.

The intent tokens are listed in Tokens.

/* Softer warning alerts, in one section only. */
.billing {
  --gui-intent-warning-bg: #fff8e6;
  --gui-intent-warning: #e0a800;
}

To restyle beyond the tokens, see Overriding styles; for dark mode and the Clay theme, see Themes and dark mode.

Accessibility

Role. The element sets role="alert" when it connects, unless it already has a role. Screen readers announce an alert when it appears in the page or when its content changes.
Status. Set role="status" for a message that can wait. Use alert only for what needs attention now, such as an error that blocks the user.
Color. Each variant has its own colors, but they carry no text of their own. Write the intent into the message, such as “Error:” or “Saved.”, when it matters.

The alert takes no focus and has no keys of its own. Links and buttons inside it work as anywhere else.

What every element shares is in Accessibility.