Notification Tray Component

A web component that displays a notification bell icon with a dropdown panel for displaying notifications. The component supports both light and dark themes, and provides methods for managing notifications.

Usage

<!-- Load the component -->
<script type="module" src="assets/components/notification-tray/qds-notification-tray.js"></script>

<!-- Use the component -->
<qds-notification-tray></qds-notification-tray>

Properties

Attributes

• more-label (string): Text to display for the “more” link at the bottom of the notification panel
• more-url (string): URL for the “more” link at the bottom of the notification panel

Methods

• addNotification(notification): Adds a notification and returns its ID

  const id = notificationTray.addNotification({
    text: 'New notification',
    time: 'Just now',
    icon: '<i class="pi pi-info"></i>',
    url: 'https://example.com'
  });
  

• removeNotification(id): Removes a notification by ID

  notificationTray.removeNotification('notification-1');
  

• clearNotifications(): Removes all notifications

  notificationTray.clearNotifications();
  

Notification Object Structure

interface Notification {
  id?: string;          // Optional: Unique identifier. If not provided, one will be generated
  text: string;         // Required: The notification text content
  time?: string;        // Optional: Timestamp or relative time
  icon?: string;        // Optional: HTML string for an icon
  url?: string;         // Optional: URL associated with the notification
}

Text Processing

The component processes notification text in the following ways:

1. If the text starts with <, the entire string is treated as HTML and rendered as-is
2. If the text contains HTML but doesn’t start with <, the HTML is escaped and displayed as plain text
3. For plain text, URLs and email addresses are automatically converted to clickable links

Examples:

// Plain text with URL
addNotification({
  text: 'Check out https://example.com'
});

// HTML content
addNotification({
  text: '<div class="custom">HTML content</div>'
});

// Text containing HTML (will be escaped)
addNotification({
  text: 'This contains <b>HTML</b>'
});

CSS Customization

The component uses CSS custom properties for theming:

qds-notification-tray {
  --badge-bg-color: var(--theme-error);
  --badge-text-color: var(--theme-text-on-accent-primary);
  --panel-bg-color: var(--theme-background-elevated);
  --panel-border-color: var(--theme-border-primary);
  --divider-color: var(--theme-border-primary);
  --title-color: var(--theme-text-primary);
  --message-color: var(--theme-text-primary);
  --time-color: var(--theme-text-secondary);
  --empty-color: var(--theme-text-secondary);
  --link-color: var(--theme-accent-primary);
}

CSS Parts

• button: The button container
• icon: The notification bell icon
• badge: The notification count badge
• panel: The notification panel container
• notification: Individual notification item
• notification-text: The notification text content
• notification-time: The notification timestamp
• notification-icon: The notification icon
• divider: The divider line between notifications
• more-link: The “more” link at the bottom of the panel

Events

The component fires a click event when the notification button is clicked.

Accessibility

• The component uses semantic HTML elements
• Links open in new tabs with appropriate security attributes
• Color contrast meets WCAG guidelines
• Interactive elements are keyboard accessible

Browser Support

The component uses modern web features and is compatible with browsers that support:

• Web Components
• Shadow DOM
• Custom Elements
• ES6+ JavaScript