Alert

hc-alert is a block-level notice meant to draw the reader’s attention to a piece of information. Variants are switched with data-variant.

Basic HTML

Tip

You can press Ctrl+K to open the command bar.

Saved

Your changes are saved.

Heads up

This action will affect 3 connected systems.

Something went wrong

The server returned a 500. Please try again.

<div class="hc-alert" role="status">
  <strong class="hc-alert__title">Tip</strong>
  <p class="hc-alert__body">You can press <kbd>Ctrl</kbd>+<kbd>K</kbd> to open the command bar.</p>
</div>

<div class="hc-alert" data-variant="success" role="status">
  <strong class="hc-alert__title">Saved</strong>
  <p class="hc-alert__body">Your changes are saved.</p>
</div>

<div class="hc-alert" data-variant="warning" role="status">
  <strong class="hc-alert__title">Heads up</strong>
  <p class="hc-alert__body">This action will affect 3 connected systems.</p>
</div>

<div class="hc-alert" data-variant="error" role="alert">
  <strong class="hc-alert__title">Something went wrong</strong>
  <p class="hc-alert__body">The server returned a 500. Please try again.</p>
</div>

Variants

Variant	Use for
omitted	Informational notice (default blue).
`success`	Confirmation of a completed action.
`warning`	A caution before a non-destructive action.
`error`	Error, failure, or destructive warning.

htmx usage

A common server-side pattern returns a hc-alert fragment for a target region after a request. The behavior is identical to swapping any other HTML — alerts have no JavaScript of their own.

<button
  class="hc-button"
  data-hx-post="/items"
  data-hx-target="#flash"
  data-hx-swap="innerHTML">
  Save
</button>

<div id="flash" aria-live="polite"></div>

For ephemeral notifications across pages, use Toast, which is triggered by an hc:toast event or an HX-Trigger response header.

Validation-error fragment

An error alert can carry a field-error list — the wire format the field-errors recipe defines for server-side validation over htmx:

<div class="hc-alert" data-variant="error" role="alert" data-hc-field-errors>
  <p class="hc-alert__title">Unprocessable Entity</p>
  <ul class="hc-alert__errors">
    <li class="hc-alert__error" data-field="email" data-code="duplicate">
      email: duplicate</li>
  </ul>
  <p class="hc-alert__body">optional hint line</p>
</div>

With installFieldErrors() active, each .hc-alert__error is distributed to the field its data-field names and hidden in the summary (data-distributed); items naming no known control stay visible. Without the behavior the alert renders all errors as a plain list. See the recipe for the full attribute set and server contract.

Accessibility

Choose the role based on urgency:
- role="status" (or aria-live="polite") for non-urgent updates — they are announced after the screen reader finishes whatever it was saying.
- role="alert" (or aria-live="assertive") for errors and urgent failures — they interrupt the screen reader.
The component does not set the role for you because the right role depends on context. Be explicit at the call site.
Color alone must not carry the meaning. Include a short .hc-alert__title so the kind of alert is announced as text.

Theming tokens

Token path	Purpose
`alert.padding-block` / `-inline`	Padding.
`alert.radius`	Border radius.
`alert.gap`	Gap between title and body.
`alert.border-width`	Border thickness.
`alert.title-weight`	Title font weight.
`alert.{variant}.{bg,fg,border}`	Per-variant colors.

CSS variables

Show the generated CSS variables

--hc-alert-padding-block | -padding-inline | -radius | -gap | -border-width
--hc-alert-title-weight
--hc-alert-info-bg    | -fg | -border
--hc-alert-success-bg | -fg | -border
--hc-alert-warning-bg | -fg | -border
--hc-alert-error-bg  | -fg | -border

Badge — for inline status.
Toast — for transient cross-page notifications.