Notifications

Display instant feedback and status messages with Chassis CSS's token-driven notification system, seamlessly integrated with your design language.

Introduction

Notifications in Chassis CSS provide contextual feedback that can be triggered by user actions or system events. Unlike traditional alert dialogs (handled by Chassis's separate Alert component), these notifications are designed for non-blocking messages that inform without interrupting the user's workflow.

Interactive example

The following example shows a notification that appears in response to a user action and can be dismissed with the built-in close button.

html

<div id="notificationPlaceholder"></div>
<button type="button" class="button primary" id="notificationButton">Show notification</button>

The JavaScript that powers this interactive example:

site/src/assets/snippets.js

const notificationPlaceholder = document.getElementById('notificationPlaceholder')
const appendNotification = (message, type) => {
  const wrapper = document.createElement('div')
  wrapper.innerHTML = [
    `<div class="notification ${type} dismissible fade show" role="alert">`,
    `   <div>${message}</div>`,
    '   <button type="button" class="close-button" data-cx-dismiss="notification" aria-label="Close"></button>',
    '</div>'
  ].join('')

  notificationPlaceholder.append(wrapper)
}

const notificationTrigger = document.getElementById('notificationButton')
if (notificationTrigger) {
  notificationTrigger.addEventListener('click', () => {
    appendNotification('Nice, you triggered this notification message!', 'success')
  })
}

Semantic variants

Chassis CSS provides a semantic notification for each contextual color in the design system. Each variant is built on design tokens that synchronize with your Figma components, ensuring visual consistency between design and implementation.

A simple default notification — check it out!

A simple alternate notification — check it out!

A simple primary notification — check it out!

A simple secondary notification — check it out!

A simple neutral notification — check it out!

A simple danger notification — check it out!

A simple success notification — check it out!

A simple warning notification — check it out!

A simple info notification — check it out!

A simple black notification — check it out!

A simple white notification — check it out!

html

<div class="notification default" role="alert">
  A simple default notification — check it out!
</div>
<div class="notification alternate" role="alert">
  A simple alternate notification — check it out!
</div>
<div class="notification primary" role="alert">
  A simple primary notification — check it out!
</div>
<div class="notification secondary" role="alert">
  A simple secondary notification — check it out!
</div>
<div class="notification neutral" role="alert">
  A simple neutral notification — check it out!
</div>
<div class="notification danger" role="alert">
  A simple danger notification — check it out!
</div>
<div class="notification success" role="alert">
  A simple success notification — check it out!
</div>
<div class="notification warning" role="alert">
  A simple warning notification — check it out!
</div>
<div class="notification info" role="alert">
  A simple info notification — check it out!
</div>
<div class="notification black" role="alert">
  A simple black notification — check it out!
</div>
<div class="notification white" role="alert">
  A simple white notification — check it out!
</div>

Accessibility tip: Color alone shouldn't convey meaning as it's not perceived by assistive technology users. Ensure clarity through text with adequate contrast, ARIA attributes where needed, and consider using .visually-hidden for screen reader content.

Solid style

For higher-emphasis messaging, apply the .solid modifier to create notifications with a more prominent visual weight. This style works particularly well in contexts where the notification needs to stand out from surrounding content.

A simple default solid notification with icon and link.

A simple alternate solid notification with icon and link.

A simple primary solid notification with icon and link.

A simple secondary solid notification with icon and link.

A simple neutral solid notification with icon and link.

A simple danger solid notification with icon and link.

A simple success solid notification with icon and link.

A simple warning solid notification with icon and link.

A simple info solid notification with icon and link.

A simple black solid notification with icon and link.

A simple white solid notification with icon and link.

html

<div class="notification default solid" role="alert">
  <svg class="icon notification-icon"><use xlink:href="#info-circle-solid"/></svg>
  <p>A simple default solid notification with icon and <a href="#">link</a>.
</div>
<div class="notification alternate solid" role="alert">
  <svg class="icon notification-icon"><use xlink:href="#info-circle-solid"/></svg>
  <p>A simple alternate solid notification with icon and <a href="#">link</a>.
</div>
<div class="notification primary solid" role="alert">
  <svg class="icon notification-icon"><use xlink:href="#info-circle-solid"/></svg>
  <p>A simple primary solid notification with icon and <a href="#">link</a>.
</div>
<div class="notification secondary solid" role="alert">
  <svg class="icon notification-icon"><use xlink:href="#info-circle-solid"/></svg>
  <p>A simple secondary solid notification with icon and <a href="#">link</a>.
</div>
<div class="notification neutral solid" role="alert">
  <svg class="icon notification-icon"><use xlink:href="#info-circle-solid"/></svg>
  <p>A simple neutral solid notification with icon and <a href="#">link</a>.
</div>
<div class="notification danger solid" role="alert">
  <svg class="icon notification-icon"><use xlink:href="#info-circle-solid"/></svg>
  <p>A simple danger solid notification with icon and <a href="#">link</a>.
</div>
<div class="notification success solid" role="alert">
  <svg class="icon notification-icon"><use xlink:href="#info-circle-solid"/></svg>
  <p>A simple success solid notification with icon and <a href="#">link</a>.
</div>
<div class="notification warning solid" role="alert">
  <svg class="icon notification-icon"><use xlink:href="#info-circle-solid"/></svg>
  <p>A simple warning solid notification with icon and <a href="#">link</a>.
</div>
<div class="notification info solid" role="alert">
  <svg class="icon notification-icon"><use xlink:href="#info-circle-solid"/></svg>
  <p>A simple info solid notification with icon and <a href="#">link</a>.
</div>
<div class="notification black solid" role="alert">
  <svg class="icon notification-icon"><use xlink:href="#info-circle-solid"/></svg>
  <p>A simple black solid notification with icon and <a href="#">link</a>.
</div>
<div class="notification white solid" role="alert">
  <svg class="icon notification-icon"><use xlink:href="#info-circle-solid"/></svg>
  <p>A simple white solid notification with icon and <a href="#">link</a>.
</div>

Dismissible notifications

Chassis CSS includes JavaScript functionality to dismiss notifications inline. This feature is particularly useful for transient messages that users may want to clear after reading.

Implementation

To create dismissible notifications:

Ensure the notification plugin or compiled Chassis CSS JavaScript is loaded
Add the .dismissible class to create space for the close button
Include a close button with data-cx-dismiss="notification" attribute
Add .fade and .show classes for smooth transition animations

Important: This message requires your attention but can be dismissed.

html

<div class="notification warning dismissible fade show" role="alert">
  <strong>Important:</strong> This message requires your attention but can be dismissed.
  <button type="button" class="close-button" data-cx-dismiss="notification" aria-label="Close"></button>
</div>

Accessibility note: When a notification is dismissed, it's completely removed from the DOM. To maintain proper keyboard navigation, add JavaScript that listens for the closed.cx.notification event and sets focus to an appropriate element in the page.

Content enhancements

Actionable links

Notification links automatically inherit appropriate styling from their parent context, with increased font-weight for better visibility. The colors adapt to maintain appropriate contrast with the notification background.

A simple default notification with an example link. Give it a click if you like.

A simple alternate notification with an example link. Give it a click if you like.

A simple primary notification with an example link. Give it a click if you like.

A simple secondary notification with an example link. Give it a click if you like.

A simple neutral notification with an example link. Give it a click if you like.

A simple danger notification with an example link. Give it a click if you like.

A simple success notification with an example link. Give it a click if you like.

A simple warning notification with an example link. Give it a click if you like.

A simple info notification with an example link. Give it a click if you like.

A simple black notification with an example link. Give it a click if you like.

A simple white notification with an example link. Give it a click if you like.

html

<div class="notification default" role="alert">
  A simple default notification with <a href="#">an example link</a>. Give it a click if you like.
</div>
<div class="notification alternate" role="alert">
  A simple alternate notification with <a href="#">an example link</a>. Give it a click if you like.
</div>
<div class="notification primary" role="alert">
  A simple primary notification with <a href="#">an example link</a>. Give it a click if you like.
</div>
<div class="notification secondary" role="alert">
  A simple secondary notification with <a href="#">an example link</a>. Give it a click if you like.
</div>
<div class="notification neutral" role="alert">
  A simple neutral notification with <a href="#">an example link</a>. Give it a click if you like.
</div>
<div class="notification danger" role="alert">
  A simple danger notification with <a href="#">an example link</a>. Give it a click if you like.
</div>
<div class="notification success" role="alert">
  A simple success notification with <a href="#">an example link</a>. Give it a click if you like.
</div>
<div class="notification warning" role="alert">
  A simple warning notification with <a href="#">an example link</a>. Give it a click if you like.
</div>
<div class="notification info" role="alert">
  A simple info notification with <a href="#">an example link</a>. Give it a click if you like.
</div>
<div class="notification black" role="alert">
  A simple black notification with <a href="#">an example link</a>. Give it a click if you like.
</div>
<div class="notification white" role="alert">
  A simple white notification with <a href="#">an example link</a>. Give it a click if you like.
</div>

Icon integration

Combine notifications with Chassis's icon system using the flexbox utilities to create more visually distinctive messages.

An example notification with an icon and a link!

An example notification with a standard icon and a default link!

html

<div class="notification success" role="alert">
  <svg class="icon notification-icon" aria-hidden="true"><use xlink:href="#info-circle-solid"/></svg>
  <p>An example notification with an icon and <a href="#">a link</a>!</p>
</div>

<div class="notification success d-flex align-items-center" role="alert">
  <svg class="icon" aria-hidden="true"><use xlink:href="#info-circle-solid"/></svg>
  <div>An example notification with a standard icon and a <a href="#" class="font-normal default-link-main">default link</a>!</div>
</div>

Rich content

Notifications support structured content with headings, paragraphs, and more to communicate complex information while maintaining visual hierarchy.

Use the .notification-title class on headings to apply design token-based styling that ensures visual consistency. The notification component also automatically applies margin-bottom: 0 to the last paragraph element, creating proper spacing without extra effort.

A success notification!

This example text demonstrates how spacing works within structured notification content. The content flows naturally with appropriate spacing.

Notice that this final paragraph has no bottom margin.

html

<div class="notification success fade show" role="alert">
  <button type="button" class="close-button" data-cx-dismiss="notification" aria-label="Close"></button>
  <h4 class="notification-title">A success notification!</h4>
  <p>This example text demonstrates how spacing works within structured notification content. The content flows naturally with appropriate spacing.</p>
  <hr />
  <p>Notice that this final paragraph has no bottom margin.</p>
</div>

Spacing controls

Dismissible notifications auto-adjust padding for close buttons, while spacing utilities like pe-medium let you fine-tune dimensions. For paragraph spacing, apply .last-mb-0 to containers to remove bottom margin from last paragraph children.

Customized Notification Spacing

This notification demonstrates how spacing utilities provide fine-grained control over layout within notifications.

Margin utilities like mb-small and me-nmedium create precision in your component spacing.

html

<div class="notification pe-medium info fade show" role="alert">
  <svg class="icon notification-icon" aria-hidden="true"><use xlink:href="#check-solid"/></svg>
  <div class="last-mb-0">
    <h4 class="notification-title">Customized Notification Spacing</h4>
    <p>This notification demonstrates how spacing utilities provide fine-grained control over layout within notifications.</p>
    <hr class="mb-small me-nmedium">
    <p>Margin utilities like <code>mb-small</code> and <code>me-nmedium</code> create precision in your component spacing.</p>
  </div>
  <button type="button" class="close-button" data-cx-dismiss="notification" aria-label="Close"></button>
</div>

CSS

This component can be customized using CSS variables, allowing for styles to be modified dynamically on the page. These CSS variables are part of Chassis CSS's design token system, giving design teams control over component appearance. See the design tokens page for more details.

Sass variables

These Sass variables are also exposed as CSS custom properties using the --cx- prefix. A Sass variable $variable-name becomes available as --cx-variable-name in CSS, allowing for styles to be modified dynamically on the page. See the context components page for more details.

scss/_variables.scss

$notification-bg-color:           var(--#{$prefix}bg-main);

$notification-padding-y:          $cx-space-notification-padding-y;
$notification-padding-x:          $cx-space-notification-padding-x;
$notification-gap:                $cx-space-notification-gap;

$notification-border-width:       $cx-border-width-notification-main;
$notification-border-radius:      $cx-border-radius-notification-main;

$notification-icon-size:          $cx-size-icon-glyph-large;
$notification-icon-color:         var(--#{$prefix}fg-main);

$notification-title-font:         $cx-font-notification-title;
$notification-message-font:       $cx-font-notification-message;

$notification-margin-b:           $space-medium;
$notification-title-margin-b:     $space-xsmall;

JavaScript

Initialization

Initialize elements as notifications:

const notificationList = document.querySelectorAll('.notification')
const notifications = [...notificationList].map(element => new chassis.Notification(element))

For the sole purpose of dismissing a notification, it isn't necessary to initialize the component manually via the JS API. By making use of data-cx-dismiss="notification", the component will be initialized automatically and properly dismissed.

See the triggers section for more details.

Triggers

Enable dismissal with the data-cx-dismiss attribute on a button within the notification:

<button type="button" class="close-button" data-cx-dismiss="notification" aria-label="Dismiss"></button>

Or on a button outside the notification using the additional data-cx-target attribute:

<button type="button" class="close-button" data-cx-dismiss="notification" data-cx-target="#my-notification" aria-label="Dismiss notification"></button>

When a notification is dismissed, it is completely removed from the DOM. If you need to maintain focus management for accessibility, listen for the closed.cx.notification event to set focus to an appropriate element.

Methods

The Notification component provides a JavaScript API for programmatic control:

const cxNotification = new chassis.Notification('#myNotification')

This makes a notification listen for click events on descendant elements which have the data-cx-dismiss="notification" attribute. (Not necessary when using the data-api's auto-initialization.)

Method	Description
`close`	Closes a notification by removing it from the DOM. If the `.fade` and `.show` classes are present on the element, the notification will fade out before it is removed.
`dispose`	Destroys an element's notification. (Removes stored data on the DOM element)
`getInstance`	Static method which allows you to get the notification instance associated to a DOM element. For example: `chassis.Notification.getInstance(notification)`.
`getOrCreateInstance`	Static method which returns a notification instance associated to a DOM element or create a new one in case it wasn't initialized. You can use it like this: `chassis.Notification.getOrCreateInstance(element)`.

Basic usage:

const notification = chassis.Notification.getOrCreateInstance('#myNotification')
notification.close()

Events

Chassis CSS's notification component exposes events for integrating with notification functionality:

Event	Description
`close.cx.notification`	Fires immediately when the `close` instance method is called.
`closed.cx.notification`	Fired when the notification has been closed and CSS transitions have completed.

const myNotification = document.getElementById('myNotification')
myNotification.addEventListener('closed.cx.notification', event => {
  // do something, for instance, explicitly move focus to the most appropriate element,
  // so it doesn't get lost/reset to the start of the page
  // document.getElementById('...').focus()
})