Alert

Variants

Five status variants communicate different message types through color and icon

Success

Operation completed successfully!


<div class="nds-alert nds-card" data-status="success" 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">Success</span>
      <p class="nds-alert-description">Operation completed successfully!</p>
    </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: 'success',
    title: 'Success',
    description: 'Operation completed successfully!',
    target: '#alert-container',
    shadow: false,
    color: false
});

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 }
    ]
});

Copy Actions

Action buttons that place text on the clipboard with a checkmark flash: pass a literal string with copy, or point copyTarget at an element on the page. In a toast, clicking a copy action also keeps the toast open

Copy a one-time code

Verification code

Your one-time code is 843291. It expires in 10 minutes.


<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">Verification code</span>
      <p class="nds-alert-description">Your one-time code is 843291. It expires in 10 minutes.</p>
    </div>
    <div class="nds-alert-actions">
      <button class="nds-btn nds-subtle nds-sm nds-copy" data-copy="843291">
        <i class="nds-icon nds-hgi-copy-01" aria-hidden="true"></i>
        <span class="nds-label">Copy code</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: 'Verification code',
    description: 'Your one-time code is 843291. It expires in 10 minutes.',
    target: '#alert-container',
    actions: [
        { label: 'Copy code', copy: '843291' }
    ]
});

Copy an error log

Request failed

The request could not be completed. Share the error log with support.


<div class="nds-alert nds-card" data-status="error" 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">Request failed</span>
      <p class="nds-alert-description">The request could not be completed. Share the error log with support.</p>
    </div>
    <div class="nds-alert-actions">
      <button class="nds-btn nds-neutral nds-sm nds-copy" data-copy="TRACE-4821 TypeError: response is undefined
  at save (app.js:42)
  at async submit (form.js:17)">
        <i class="nds-icon nds-hgi-copy-01" aria-hidden="true"></i>
        <span class="nds-label">Copy error log</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>

// In production, pass the real error you already hold:
// quotes, commas, and newlines inside the string are all safe
NDS.Alert.create({
    variant: 'error',
    title: 'Request failed',
    description: 'The request could not be completed. Share the error log with support.',
    target: '#alert-container',
    actions: [
        { label: 'Copy error log', variant: 'neutral', copy: err.stack }
    ]
});

Toast Notifications

Floating notifications anchored to any corner of the viewport. The auto-dismiss timer pauses while users hover or focus, and a click keeps the toast until closed

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 nds-stroke" data-status="success" role="alert" data-state="toast-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
});

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

Floating notifications with an auto-dismiss timer and a countdown ring on the close button.

Pausable Auto-dismiss

Toast timers pause on hover or keyboard focus and resume on leave. A click keeps the toast until closed.

Flexible Placement

Toasts anchor to the top or bottom edge combined with start, end, left, or right, and logical sides follow text direction.

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 a copy action for content users will paste elsewhere (verification codes, reference numbers, error details) instead of making them select text from 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. The timer pauses on hover and focus, so users who start reading are never cut off
Prefer logical toast positions (start, end) so placement follows text direction in RTL and LTR. Reserve left and right for cases that must anchor to a physical screen edge

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` or `bottom`, optionally suffixed with an inline side: `-start`, `-end`, `-left`, `-right` (e.g. `top-start`, `bottom-left`). Bare values anchor to the inline end
`data-state`	Set on `.nds-toast` to control visibility transitions. Values: `toast-show`, `toast-hide`, `paused`. 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
`--progress-duration`	`4000ms`	Duration of the countdown animation on the toast close button. Set inline on `.nds-alert-close` by the JS API when `duration` is provided

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: true for toasts, else 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)
            copy: 'text',         // Copy this text on click: adds a copy icon,
                                  // checkmark flash, and screen-reader announce
            copyTarget: '#log'    // Or copy an element's textContent by CSS selector
                                  // (ignored when copy is also set)
        }
    ]
});

// ── Create a toast notification ──────────────────────
NDS.Alert.create({
    variant: 'success',
    description: 'Changes saved!',
    display: 'toast',          // 'default' | 'inline' | 'toast'
    position: 'top',          // 'top' | 'bottom', plus optional inline side
                              // '-start' | '-end' | '-left' | '-right'
                              // e.g. 'top-start', 'bottom-left' (default: 'top' = inline end)
    duration: 4000            // Auto-dismiss in ms, 0 = manual (default: 0)
                              // Timer pauses on hover/focus; a click pins the toast until closed
});

// ── 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

Copy Actions

Toast Notifications

Built-in Features

Usage Guidelines

Best Practices

Modifier Classes

Data Attributes

CSS Custom Properties

JavaScript API