Alert

Alerts are inline notification banners used to communicate status messages, warnings, errors, or confirmations directly within the page layout. FrontAlign provides two complementary Alert systems: a Core Engine for managing existing HTML alerts declaratively, and a Dynamic Alert class for creating and injecting alerts programmatically.

Quick reference

FrontAlign supports two modes:

Core (Static): Alert already exists in HTML — handles dismissal, animations, persistence, and custom events automatically.
Dynamic (Class): Create and inject a new alert from JavaScript at runtime.

Five status types are supported across both modes: Default · Success · Danger · Warning · Info

HTML Structure

An alert consists of a root .alert element with a status modifier class, an .alert-content span for the message, and optionally an .alert-close button for dismissal.

<div class="alert"fa-component="alert">
  <span class="alert-content">This is a default alert.</span>
  <button class="button alert-close" aria-label="Dismiss alert"></button>
</div>

<div class="alert is-success"fa-component="alert">
  <span class="alert-content">Your profile has been updated.</span>
  <button class="button alert-close" aria-label="Dismiss alert"></button>
</div>

<div class="alert is-warning"fa-component="alert">
  <span class="alert-content">Your session will expire soon.</span>
  <button class="button alert-close" aria-label="Dismiss alert"></button>
</div>

<div class="alert is-danger"fa-component="alert">
  <span class="alert-content">Something went wrong. Please try again.</span>
  <button class="button alert-close" aria-label="Dismiss alert"></button>
</div>

This is a default alert.

Your profile has been updated.

Your session will expire soon.

Something went wrong. Please try again.

Structure Breakdown

Element	Selector	Description
Root container	`.alert`	The alert wrapper. Accepts status modifier classes and behavior attributes.
Message	`.alert-content`	Displays the alert text content.
Close button	`.alert-close`	Triggers dismissal. Requires `aria-label` for accessibility.

<div class="alert">
  <span class="alert-content">This is a default alert.</span>
  <button class="button alert-close" aria-label="Dismiss alert"></button>
</div>

<div class="alert is-success">
  <span class="alert-content">Action completed successfully.</span>
  <button class="button alert-close" aria-label="Dismiss alert"></button>
</div>

<div class="alert is-danger">
  <span class="alert-content">An error occurred.</span>
  <button class="button alert-close" aria-label="Dismiss alert"></button>
</div>

<div class="alert is-warning">
  <span class="alert-content">Proceed with caution.</span>
  <button class="button alert-close" aria-label="Dismiss alert"></button>
</div>

<div class="alert is-info">
  <span class="alert-content">Here is some useful information.</span>
  <button class="button alert-close" aria-label="Dismiss alert"></button>
</div>

Attributes

Attribute	Applied To	Value	Default	Description
`data-close-animation`	Root container	`"slide"`	`fade`	Exit animation. `slide` collapses height; default is `fade` (opacity).
`data-persistent`	Root container	`"true"`	`false`	Saves dismissed state to `localStorage` so the alert never reappears for that user.
`data-alert`	Root container	`string`	—	Unique identifier required for persistent alerts. Used as the `localStorage` key.

`data-close-animation`

By default, alerts exit with a fade animation (opacity transition). Set data-animation="slide" to collapse the alert's height instead — useful when you want the surrounding content to close the gap smoothly after dismissal.

<!-- Default: fade transition -->
<div class="alert is-success"fa-component="alert">
  <span class="alert-content">This alert fades out on dismiss.</span>
  <button class="button alert-close" aria-label="Dismiss alert"></button>
</div>

<!-- Slide transition -->
<div class="alert is-info" data-close-animation="slide">
  <span class="alert-content">This alert slides up on dismiss.</span>
  <button class="button alert-close" aria-label="Dismiss alert"></button>
</div>

This alert fades out on dismiss (default).

This alert slides up on dismiss.

`data-persistent`

By default, dismissed alerts reappear on the next page load. Set data-persistent="true" along with a unique alert-id to permanently remember the dismissed state in localStorage — ideal for promotional banners or one-time notices.

<!-- Persistent alert — dismissed state stored in localStorage -->
<div class="alert is-info" fa-component="alert" data-persistent="true" data-alert="promo-banner-2025">
  <span class="alert-content">Check out our new features!</span>
  <button class="button alert-close" aria-label="Dismiss alert"></button>
</div>

Check out our new features! (Dismissing this remembers your choice.)

Icon Variant

Add has-icon to the root .alert element to display a status icon alongside the message.

<div class="alert is-success has-icon">
  <span class="alert-content">Your profile has been updated.</span>
  <button class="button alert-close" aria-label="Dismiss alert"></button>
</div>

<div class="alert is-danger has-icon">
  <span class="alert-content">Something went wrong. Please try again.</span>
  <button class="button alert-close" aria-label="Dismiss alert"></button>
</div>

Your profile has been updated.

Something went wrong. Please try again.

Event System

The Core engine dispatches two native CustomEvents during the dismiss lifecycle. The close event is cancelable. Both events carry an alert reference in event.detail.

Event	Dispatched On	Cancelable	Description
`fa.alert.close`	The alert element	✅ Yes	Fires when the close button is clicked, before removal. `preventDefault()` cancels the dismissal.
`fa.alert.closed`	`document`	❌ No	Fires after the alert has been fully removed from the DOM.

event.detail

Both events carry one reference:

Property	Type	Description
`alert`	`HTMLElement`	The `.alert` element that was dismissed.

Cancel dismiss based on a condition

document.querySelector('#my-alert').addEventListener('fa.alert.close', (e) => {
  if (hasUnsavedChanges) {
    e.preventDefault();
    showUnsavedWarning();
  }
});

React Usage

'use client';

import { useAlertDismiss } from 'frontalign/react';

export function Example() {
  useAlertDismiss();

  return (
    <div className="alert">
      <span className="alert-content">Your profile has been updated.</span>
      <button className="button alert-close" aria-label="Dismiss alert"></button>
    </div>
  );
}

Dynamic Alert

The Alert class lets you create and inject fully configured alerts from JavaScript — no HTML required. Ideal for responding to async operations, API responses, or user actions at runtime.

Basic Usage

// Use when you want to bypass the Core engine
import { Alert } from 'frontalign';

const alert = Alert.create('#reference-element', {
  message: 'Your file has been uploaded successfully.',
  status: 'success',
  animation: 'slide',
  autoClean: true
});

Configuration Options

Option	Type	Default	Description
`message`	`string`	`"This is an alert message"`	Text content displayed inside the alert.
`status`	`string`	`"default"`	Visual variant: `success`, `danger`, `warning`, `info`, or `default`.
`dismissible`	`boolean`	`true`	Whether to render a close button and enable click-to-dismiss.
`position`	`string`	`"before"`	`"after"` inserts after the reference element; `"before"` inserts before it.
`animation`	`string`	`"fade"`	Exit animation: `fade` (opacity) or `slide` (height collapse).
`hasIcon`	`boolean`	`false`	Adds `has-icon` CSS class for a status icon.
`animated`	`boolean`	`true`	`false` adds `animation-none` class to disable entrance animation.
`bordered`	`boolean`	`false`	`false` adds `border-0` class to remove the alert border.
`autoClean`	`boolean`	`false`	Automatically calls `.dispose()` after dismissal.

Instance Methods

`.dispose()`

Removes the click event listener and nullifies all internal references. Call manually for cleanup, or set autoClean: true to have it called automatically.

alert.dispose();

Pro Tips

After an API call:

async function submitForm() {
  try {
    await postData('/api/submit', formData);
    Alert.create('#submit-btn', {
      message: 'Form submitted successfully!',
      status: 'success',
      animation: 'slide',
      autoClean: true
    });
  } catch {
    Alert.create('#submit-btn', {
      message: 'Something went wrong. Please try again.',
      status: 'danger',
      autoClean: true
    });
  }
}

React Usage — `useAlert`

The useAlert hook provides status-based shorthand methods for injecting dynamic alerts from any React component. It wraps the Alert class internally and is fully compatible with SSR ('use client' required).

Import

'use client';

import { useAlert } from 'frontalign/react';

Shorthand Methods

The hook returns five methods: show, success, danger, warning, and info. Each accepts a CSS selector and an options object.

Method	Equivalent Status	Description
`alert.show(selector, options)`	`default`	Generic alert — status must be passed via `options.status`.
`alert.success(selector, options)`	`success`	Injects a green success alert.
`alert.danger(selector, options)`	`danger`	Injects a red danger alert.
`alert.warning(selector, options)`	`warning`	Injects a yellow warning alert.
`alert.info(selector, options)`	`info`	Injects a blue info alert.

Basic Example

'use client';

import { useAlert } from 'frontalign/react';

export function AlertExample() {
  const alert = useAlert();

  return (
    <>
      <div id="form-message"></div>

      <button
        className="button is-primary"
        onClick={() => alert.success('#form-message', {
          message: 'Profile saved.',
          position: 'after',
          animation: 'slide'
        })}
      >
        Show Alert
      </button>
    </>
  );
}

All Statuses

'use client';

import { useAlert } from 'frontalign/react';

export function StatusExamples() {
  const alert = useAlert();

  return (
    <>
      <div id="alert-target"></div>

      <button className="button" onClick={() => alert.success('#alert-target', { message: 'Operation completed.' })}>
        Success
      </button>
      <button className="button" onClick={() => alert.danger('#alert-target', { message: 'An error occurred.' })}>
        Danger
      </button>
      <button className="button" onClick={() => alert.warning('#alert-target', { message: 'Proceed with caution.' })}>
        Warning
      </button>
      <button className="button" onClick={() => alert.info('#alert-target', { message: 'Here is some info.' })}>
        Info
      </button>
      <button className="button" onClick={() => alert.show('#alert-target', { message: 'A default alert.', status: 'default' })}>
        Default
      </button>
    </>
  );
}

After an Async Action

Use useAlert to respond to form submissions, API responses, or any async event:

'use client';

import { useState } from 'react';
import { useAlert } from 'frontalign/react';

export function SubmitForm() {
  const alert = useAlert();
  const [loading, setLoading] = useState(false);

  async function handleSubmit() {
    setLoading(true);
    try {
      await postData('/api/submit', formData);
      alert.success('#submit-btn', {
        message: 'Form submitted successfully!',
        animation: 'slide',
        autoClean: true
      });
    } catch {
      alert.danger('#submit-btn', {
        message: 'Something went wrong. Please try again.',
        autoClean: true
      });
    } finally {
      setLoading(false);
    }
  }

  return (
    <>
      <div id="submit-btn"></div>
      <button className="button is-primary" onClick={handleSubmit} disabled={loading}>
        {loading ? 'Submitting…' : 'Submit'}
      </button>
    </>
  );
}

With Icons and Custom Position

'use client';

import { useAlert } from 'frontalign/react';

export function IconAlerts() {
  const alert = useAlert();

  return (
    <>
      <div id="icon-target"></div>

      <button
        className="button"
        onClick={() => alert.danger('#icon-target', {
          message: 'Access denied. Please contact your administrator.',
          hasIcon: true,
          position: 'after',
          animation: 'fade',
          dismissible: true
        })}
      >
        Show Icon Alert
      </button>
    </>
  );
}

Cancel dismiss with confirmation:

document.querySelector('#important-alert').addEventListener('fa.alert.close', (e) => {
  if (hasUnsavedChanges) {
    e.preventDefault();
    showConfirmationModal();
  }
});

Notes

Two Complementary Systems: Use Core for static HTML alerts and the Alert class for dynamic ones, or combine both in the same project.
Persistent Alerts: Core alerts can be permanently dismissed per-user via localStorage, so they never reappear after being closed.
Dual Transition Modes: Choose between fade (opacity) or slide (height collapse) exit animation on dismissal.
Custom Events: Core alerts dispatch fa.alert.close and fa.alert.closed events, allowing you to hook into the dismiss lifecycle.
Flexible Injection: Dynamic alerts can be inserted either before or after the reference element.
Auto Clean: Dynamic alerts can automatically dispose their instance from memory after dismissal.
Accessibility: Close buttons include aria-label attributes for screen reader support.