Alert | NDS - Vanilla National Design System

Variants

Five status variants communicate different message types through color and icon

Success

Operation completed successfully!

Inline

Compact single-line layout with bottom stripe and solid icon

Important:

This is a very important banner message that requires attention

Learn More


<div class="nds-alert nds-card nds-inline" data-status="critical" role="alert">
  <span class="nds-feedback nds-alert-icon">
    <span class="nds-feedback-icon">
      <i class="nds-icon" aria-hidden="true"></i>
    </span>
  </span>
  <div class="nds-alert-content">
    <div class="nds-alert-text">
      <span class="nds-alert-title">Important:</span>
      <p class="nds-alert-description">This is a very important banner message that requires attention.</p>
    </div>
    <div class="nds-alert-actions">
      <a href="#" class="nds-link">Learn More</a>
    </div>
  </div>
  <button class="nds-btn nds-subtle nds-icon-only nds-md nds-alert-close" aria-label="Close alert">
    <i class="nds-icon nds-hgi-cancel-01" aria-hidden="true"></i>
  </button>
</div>

NDS.Alert.create({
    variant: 'critical',
    title: 'Important:',
    description: 'This is a very important banner message that requires attention.',
    display: 'inline',
    target: '#alert-container',
    actions: [
        { label: 'Learn More', href: '#', class: 'nds-link' }
    ]
});

With Actions

Action buttons let users respond directly from the notification

Update Available

A new version is available. Would you like to update now?


<div class="nds-alert nds-card" data-status="info" role="alert">
  <span class="nds-feedback nds-alert-icon nds-outline">
    <span class="nds-feedback-icon">
      <i class="nds-icon" aria-hidden="true"></i>
    </span>
  </span>
  <div class="nds-alert-content">
    <div class="nds-alert-text">
      <span class="nds-alert-title">Update Available</span>
      <p class="nds-alert-description">A new version is available. Would you like to update now?</p>
    </div>
    <div class="nds-alert-actions">
      <button class="nds-btn nds-primary nds-sm">
        <span class="nds-label">Update Now</span>
      </button>
      <button class="nds-btn nds-subtle nds-sm">
        <span class="nds-label">Later</span>
      </button>
    </div>
  </div>
  <button class="nds-btn nds-subtle nds-icon-only nds-md nds-alert-close" aria-label="Close alert">
    <i class="nds-icon nds-hgi-cancel-01" aria-hidden="true"></i>
  </button>
</div>

NDS.Alert.create({
    variant: 'info',
    title: 'Update Available',
    description: 'A new version is available. Would you like to update now?',
    target: '#alert-container',
    actions: [
        { label: 'Update Now', class: 'nds-btn nds-primary nds-sm', onClick: () => handleUpdate() },
        { label: 'Later', class: 'nds-btn nds-subtle nds-sm', dismiss: true }
    ]
});

Toast Notifications

Floating notifications that appear at the top or bottom of the viewport

Select a variant and position above, then click the button to preview


<div class="nds-alert-placeholder" data-position="top">
  <div class="nds-alert nds-card nds-toast nds-shadow" data-status="success" role="alert" data-toast-state="show">
    <span class="nds-feedback nds-alert-icon nds-outline">
      <span class="nds-feedback-icon">
        <i class="nds-icon" aria-hidden="true"></i>
      </span>
    </span>
    <div class="nds-alert-content">
      <div class="nds-alert-text">
        <span class="nds-alert-title">Success</span>
        <p class="nds-alert-description">Changes saved successfully!</p>
      </div>
    </div>
    <button class="nds-btn nds-subtle nds-icon-only nds-md nds-alert-close nds-progress" aria-label="Close alert" style="--progress-duration: 4000ms;">
      <i class="nds-icon nds-hgi-cancel-01" aria-hidden="true"></i>
      <div class="nds-progress-circle">
        <svg width="100%" height="100%" viewBox="0 0 24 24">
          <circle class="nds-progress-bg" cx="12" cy="12" r="10" fill="none" stroke-width="2"></circle>
          <circle class="nds-progress-track" cx="12" cy="12" r="10" fill="none" stroke-width="2" stroke-dasharray="62.83" stroke-dashoffset="62.83" stroke-linecap="round"></circle>
        </svg>
      </div>
    </button>
  </div>
</div>

NDS.Alert.create({
    variant: 'success',
    title: 'Success',
    description: 'Changes saved successfully!',
    display: 'toast',
    position: 'top',
    duration: 4000,
    shadow: true
});

Built-in Features

Auto-initialization

Activates when .nds-alert is on the page. Close button handlers attach automatically.

Six Status Variants

Success, info, warning, error, critical, and neutral with automatic icon and color theming.

Toast Notifications

Fixed positioning with auto-dismiss timer and progress indicator.

Inline Layout

Single-line variant for contextual messages with actions pushed to the end.

Programmatic Control

Create, dismiss, and bulk-clear alerts through the JS API without writing HTML.

Responsive Layout

Stacks vertically on mobile with stripe repositioned to the top.

Usage Guidelines

Best Practices

Use standard alerts for important messages that need a title and description within a page section
Use inline alerts for contextual feedback near a form field or action where space is limited
Use toast notifications for transient feedback after an action (save, delete, submit) that does not require the user to stay on the page
Choose the variant that matches the message severity: success for confirmations, info for neutral updates, warning for caution, error for failures, critical for system-level emergencies, neutral for general notices
Do not use alerts for blocking decisions that require user input. Use a Modal instead
Do not use toast notifications for critical errors or messages that require user action. Toasts can auto-dismiss before the user reads them
Prefer alerts over modals for non-blocking feedback. Alerts let users continue working without interruption
Add action buttons when the user needs to respond (retry, undo, update) rather than just acknowledge the message
Add nds-color to reinforce severity in high-density layouts where the stripe alone may not stand out
Keep alert descriptions to one or two sentences. For longer content, link to a detail page with an action link
Set a reasonable duration for toast notifications (3000-5000 ms). Avoid durations under 2000 ms as users may not have time to read the message

Modifier Classes

Class	Description
`nds-inline`	Compact single-line layout with bottom stripe and solid icon
`nds-toast`	Floating notification style with opacity transitions for toast display
`nds-shadow`	Adds elevation shadow to the alert card
`nds-color`	Applies a tinted background matching the status variant

Data Attributes

Attribute	Description
`data-status`	Set on `.nds-alert` to control the variant. Values: `success`, `info`, `warning`, `error`, `critical`, `neutral`
`data-position`	Set on `.nds-alert-placeholder` to position toast containers. Values: `top`, `bottom`
`data-toast-state`	Controls toast visibility transitions. Values: `show`, `hide`. Managed automatically by the JS API

CSS Custom Properties

Property	Default	Description
`--alert-stripe`	`--border-neutral-primary`	Color of the side stripe indicator
`--alert-icon-bg`	`--background-neutral-light`	Background color of the feedback icon circle

JavaScript API

The NDS.Alert API provides methods to create, display, and dismiss alerts programmatically. For dynamically added HTML alerts, call NDS.Alert.init() to re-attach close button handlers.


// ── Create an alert ──────────────────────────────────
// Returns the created HTMLElement
const alert = NDS.Alert.create({
    variant: 'success',       // 'success' | 'warning' | 'error' | 'critical' | 'info' | 'neutral'
    title: 'Success',         // Optional heading text
    description: 'Saved.',    // Alert body text
    target: '#container',     // CSS selector or DOM element to insert into
    closable: true,           // Show close button (default: true)
    shadow: false,            // Add nds-shadow class (default: false)
    color: false,             // Add nds-color background (default: false)
    id: 'my-alert',           // Custom element ID (optional)
    prepend: false,           // Insert at start of target (default: false)
    display: 'default',       // 'default' | 'inline' | 'toast'
    actions: [                // Action buttons (optional)
        {
            label: 'Retry',
            class: 'nds-btn nds-primary nds-sm',  // Custom classes (overrides variant/size)
            onClick: (el) => {},  // Callback, receives the alert element
            dismiss: false,       // Auto-dismiss after click (default: false)
            href: '/url',         // Render as <a> link instead of <button> (optional)
            target: '_blank'      // Link target attribute (optional, requires href)
        }
    ]
});

// ── Create a toast notification ──────────────────────
NDS.Alert.create({
    variant: 'success',
    description: 'Changes saved!',
    display: 'toast',          // 'default' | 'inline' | 'toast'
    position: 'top',          // 'top' | 'bottom' (default: 'top')
    duration: 4000,           // Auto-dismiss in ms, 0 = manual (default: 0)
    shadow: true
});

// ── Dismiss ──────────────────────────────────────────
NDS.Alert.dismiss(alert);               // By element reference
NDS.Alert.dismiss('#my-alert');          // By selector
NDS.Alert.dismissAll('#container');      // All alerts in a container
NDS.Alert.dismissAll(document.body);     // All alerts on page

// ── Re-initialize after dynamic HTML ─────────────────
// Attaches close handlers to any new .nds-alert elements
NDS.Alert.init();

Alert - National Design System

Variants

Inline

With Actions

Toast Notifications

Built-in Features

Usage Guidelines

Best Practices

Modifier Classes

Data Attributes

CSS Custom Properties

JavaScript API

Cookies