Use Alert

<jangle-alert> presents persistent, in-flow feedback about the current task or content region. Use it for useful information, warnings, failures, and outcomes that should remain visible. Do not add success feedback when the changed interface already makes success clear.

Add Alert

Configure package access and install Components and Tokens, then load the theme and Alert registration entry:

import '@jangle-ui/tokens/tokens.css';
import '@jangle-ui/components/alert/register';

<jangle-alert tone="warning" heading="Reconnect before Friday" heading-level="3">
  The analytics connection expires soon and scheduled reports will stop updating.
</jangle-alert>

Choose information, success, warning, or danger for tone. The default is information. The required default slot accepts localized text and ordinary noninteractive HTML such as paragraphs, emphasis, and lists. Your original elements keep their semantics; Alert does not flatten them into a text copy. Write the message so it communicates the essential outcome without the optional heading. Keep links, controls, focusable or editable content, and nested live feedback out of the message; use the existing action slot for a recovery Button. Empty messages and unsupported interactive message content suppress the surface and produce a diagnostic.

<jangle-alert tone="warning" heading="Some records need attention" heading-level="3">
  <p><strong>Your import is saved.</strong> Review these items before continuing:</p>
  <ul>
    <li>Two records are missing an email address.</li>
    <li>One record has an unrecognized region.</li>
  </ul>
</jangle-alert>

The optional heading should be concise; set heading-level from 2 through 6 to fit the surrounding page hierarchy. Removing heading clears it. Removing close-label restores “Dismiss message.”

Choose announcement urgency

announcement="polite" is the default, including for danger. Use assertive only when the message is genuinely important and time-sensitive. Visible tone and announcement urgency are independent. Alert combines its heading and message into one atomic live region, while its decorative Icon does not repeat the meaning. Exact heading speech varies across browser and assistive-technology combinations, so never rely on the heading to make the required message understandable.

Alert does not move focus. Content present when a page loads may not be announced, so do not depend on a live announcement as the only way someone can discover the message. When reporting a new outcome, insert Alert in response to that outcome or update the existing Alert's message content.

Add a recovery action

An Alert can contain one direct command Button for a distinct recovery action, such as retrying an automatically started load. Use a small neutral, quiet Button with a status context matching the Alert tone. Register Button explicitly when using the action slot:

import '@jangle-ui/components/button/register';

<jangle-alert tone="danger" heading="Report unavailable">
  The report could not be loaded. Your filters and date range are unchanged.
  <jangle-button
    slot="action"
    intent="neutral"
    treatment="quiet"
    context="status-danger"
    size="sm"
    type="button"
    pending-label="Loading report"
  >
    Retry load
  </jangle-button>
</jangle-alert>

The application owns the Button's command, listener, availability, pending state, and result. Keep an existing Save control as the retry when it already performs the failed operation. Button's pending label communicates progress; do not duplicate it in Alert, and do not add a second success message when recovered content already communicates success.

When the Alert tone changes, update the Button context to match. Alert does not rewrite the Button's properties. Existing command Buttons with another visual treatment remain operable; migrate them to the matching quiet contextual recipe.

Offer dismissal

Set dismissible to show a close control and provide a localized close-label. Its default name is “Dismiss message.” The close control emits jangle-dismiss-request, a bubbling, composed, noncancelable event with no payload. Alert stays visible until the application removes or hides it. If the application ignores the request, the message remains visible; preventDefault() does not control dismissal.

Move focus to a meaningful surviving destination before removing focused Alert content. If focus is elsewhere, preserve it. In this example, the report heading is the destination:

<h2 id="report-heading" tabindex="-1">Quarterly report</h2>
<jangle-alert
  id="connection-warning"
  tone="warning"
  dismissible
  close-label="Dismiss connection warning"
>
  The analytics connection expires soon and scheduled reports will stop updating.
</jangle-alert>

const message = document.querySelector('#connection-warning');
const reportHeading = document.querySelector('#report-heading');

message.addEventListener('jangle-dismiss-request', () => {
  if (message.contains(document.activeElement)) reportHeading.focus();
  message.remove();
});

The close control follows normal Tab order and native Enter/Space activation. Alert does not add an Escape shortcut, a dismissal timer, or a dismissal announcement. The action and close control stay outside its live message region.

Explore the complete reference

Open Alert in the public Storybook for interactive controls, tone examples, recovery behavior, long content, and accessibility guidance. Storybook is public and does not require a Jangle UI account.