Basic Usage
Include the script and use the custom element:
<!-- Include the web component script --> <script
src="/js/notifications-widget.js"></script> <!-- Use the
custom element --> <legion-notifications user-id="123"
api-key="your-api-key" base-url="https://your-domain.com"
theme="light" max-notifications="10" auto-refresh="true">
</legion-notifications>
Core Attributes
-
user-id: User ID for notifications (required)
-
api-key: API key for authenticated requests
-
base-url: Base URL for API calls (default:
current origin)
- theme: "light" or "dark" (default: light)
-
max-notifications: Maximum notifications to show
(default: 10)
-
auto-refresh: Auto-refresh notifications
(default: true)
Container Theming
- notif-background-color: Widget background
- notif-text-color: Primary text color
- notif-secondary-text-color: Secondary text
- notif-border-color: Border color
-
notif-border-radius: Container border radius
- notif-padding: Container padding
- notif-shadow: Container box shadow
Color Theming
- notif-primary-color: Primary accent color
- notif-primary-hover: Primary hover color
- notif-accent-color: Accent color
Dark Theme Example
Use the dark theme with custom colors:
<legion-notifications user-id="123" api-key="your-api-key"
theme="dark" notif-background-color="#1a1b1e"
notif-text-color="#c1c2c5" notif-primary-color="#4cc9f0"
notif-border-radius="12px" notif-shadow="0 4px 20px
rgba(0,0,0,0.3)"> </legion-notifications>
Item Theming
Customize individual notification items:
- notif-item-bg: Item background color
- notif-item-hover-bg: Item hover background
- notif-item-border: Item border color
- notif-item-radius: Item border radius
- notif-item-shadow: Item shadow
- notif-item-padding: Item padding
- notif-item-gap: Gap between items
Unread Notification Styling
Highlight unread notifications:
- notif-unread-bg: Unread item background
- notif-unread-border: Unread item border
-
notif-unread-indicator: Unread indicator color
<legion-notifications user-id="123" api-key="your-api-key"
notif-unread-bg="#e7f5ff" notif-unread-border="#74c0fc"
notif-unread-indicator="#228be6"> </legion-notifications>
Avatar & Icon Styling
-
notif-avatar-size: Avatar size (default: 40px)
- notif-avatar-radius: Avatar border radius
- notif-avatar-border: Avatar border
- notif-icon-size: Icon size
- notif-icon-color: Icon color
Badge Theming
-
notif-badge-bg: Badge background (default:
#fa5252)
- notif-badge-color: Badge text color
- notif-badge-size: Badge size
Typography
-
notif-font-family: Font family (default: inherit)
-
notif-title-size: Title font size (default: 14px)
-
notif-title-weight: Title font weight (default:
600)
-
notif-body-size: Body font size (default: 13px)
-
notif-timestamp-size: Timestamp font size
(default: 11px)
Empty State Customization
Customize the empty state message:
- empty-title: Empty state title
- empty-subtitle: Empty state subtitle
-
empty-icon: Empty state icon (bell, gift,
activity, trophy)
- notif-empty-icon-color: Empty icon color
- notif-empty-text-color: Empty text color
<legion-notifications user-id="123" api-key="your-api-key"
empty-title="No new updates" empty-subtitle="Check back later for
notifications" empty-icon="bell"> </legion-notifications>
Button Theming
- notif-button-bg: Button background
- notif-button-color: Button text color
- notif-button-radius: Button border radius
Animation Settings
-
notif-transition-duration: Animation speed
(default: 0.2s)
-
notif-hover-scale: Hover scale factor (default:
1)
<legion-notifications user-id="123" api-key="your-api-key"
notif-transition-duration="0.3s" notif-hover-scale="1.02">
</legion-notifications>
Custom Brand Colors
Match your brand identity:
<legion-notifications user-id="123" api-key="your-api-key"
notif-primary-color="#7c3aed" notif-accent-color="#7c3aed"
notif-icon-color="#7c3aed" notif-badge-bg="#f59e0b"
notif-button-bg="#7c3aed" notif-border-radius="16px"
notif-item-radius="12px"> </legion-notifications>
Event Handling
Listen for notification events:
const notifications =
document.querySelector('legion-notifications'); // Notifications
loaded successfully
notifications.addEventListener('notifications-loaded', (event) => {
console.log('Notifications:', event.detail.notifications); }); //
New notification received
notifications.addEventListener('notification-received', (event) => {
console.log('New notification:', event.detail.notification); }); //
Error occurred while loading
notifications.addEventListener('notifications-error', (event) => {
console.error('Error:', event.detail.error); });
Dynamic Updates
Update attributes programmatically:
const notifications =
document.querySelector('legion-notifications'); // Switch to dark
theme notifications.setAttribute('theme', 'dark'); // Update user
notifications.setAttribute('user-id', 'new-user-id'); // Change
colors dynamically notifications.setAttribute('notif-primary-color',
'#ff6b6b'); // Update max notifications
notifications.setAttribute('max-notifications', '20');
Responsive Container
Make the widget responsive:
<style> .notifications-container { width: 100%; max-width:
400px; margin: 0 auto; } @media (max-width: 768px) {
.notifications-container { max-width: 100%; padding: 0 10px; } }
</style> <div class="notifications-container">
<legion-notifications user-id="123" api-key="your-api-key"
max-notifications="5"> </legion-notifications> </div>
All Theming Options
Complete list of CSS variable attributes:
- notif-background-color
- notif-text-color
- notif-secondary-text-color
- notif-border-color
- notif-border-radius
- notif-padding
- notif-shadow
- notif-primary-color
- notif-primary-hover
- notif-accent-color
- notif-item-bg
- notif-item-hover-bg
- notif-item-border
- notif-item-radius
- notif-item-shadow
- notif-item-padding
- notif-item-gap
- notif-unread-bg
- notif-unread-border
- notif-unread-indicator
- notif-avatar-size
- notif-avatar-radius
- notif-avatar-border
- notif-icon-size
- notif-icon-color
- notif-badge-bg
- notif-badge-color
- notif-badge-size
- notif-font-family
- notif-title-size
- notif-title-weight
- notif-body-size
- notif-timestamp-size
- notif-empty-icon-color
- notif-empty-text-color
- notif-empty-icon-size
- notif-divider-color
- notif-header-bg
- notif-header-border
- notif-button-bg
- notif-button-color
- notif-button-radius
- notif-transition-duration
- notif-hover-scale
- notif-loader-color
Error Handling
The widget handles various error states:
- Missing user-id attribute
- Invalid or expired API keys
- Network connectivity issues
- Server errors
Tip: Always provide error handling for production
use.
Browser Support
The web component works in all modern browsers that support:
- Custom Elements v1
- Shadow DOM v1
- ES6 Classes
Supported: Chrome 54+, Firefox 63+, Safari 10.1+,
Edge 79+