Notifications
Overview
The Notifications component in the Phenix Design System provides a way to display temporary messages to users. It's useful for showing feedback about actions, errors, warnings, or success messages that automatically disappear after a specified time.
The notifications()
method allows you to create notifications with different types, positions, and durations. You can use it to provide feedback for user actions, display system messages, or alert users about important events.
Basic Usage
To create a notification, you need to call the notifications()
method on the document
object. The method accepts an options object that allows you to customize the notification.
JavaScript
//====> Basic Notification <====//
Phenix(document).notifications({
type: 'normal', //====> Message type: normal, error, success, warning
message: 'This is a notification message', //====> Message content
duration: 3000, //====> Message timeout in milliseconds
position: 'bottom, start' //====> Message position [Y, X]
});
Notification Types
The Notifications component supports four types of notifications, each with its own styling to visually communicate different message purposes.
JavaScript
//====> Normal Notification (default) <====//
Phenix(document).notifications({
type: 'normal',
message: 'This is a normal notification'
});
//====> Success Notification <====//
Phenix(document).notifications({
type: 'success',
message: 'Operation completed successfully!'
});
//====> Error Notification <====//
Phenix(document).notifications({
type: 'error',
message: 'An error occurred. Please try again.'
});
//====> Warning Notification <====//
Phenix(document).notifications({
type: 'warning',
message: 'Warning: This action cannot be undone.'
});
Positioning
You can control where notifications appear on the screen using the position
option. The position format is "Y, X" where:
- Y is the vertical position: "top", "center", or "bottom"
- X is the horizontal position: "start", "center", or "end"
JavaScript
//====> Top-Right Notification <====//
Phenix(document).notifications({
message: 'Top-right notification',
position: 'top, end'
});
//====> Bottom-Center Notification <====//
Phenix(document).notifications({
message: 'Bottom-center notification',
position: 'bottom, center'
});
//====> Center Notification <====//
Phenix(document).notifications({
message: 'Centered notification',
position: 'center, center'
});
Duration
The duration
option controls how long notifications are displayed before they automatically disappear. The value is specified in milliseconds.
JavaScript
//====> Short Notification (1 second) <====//
Phenix(document).notifications({
message: 'This will disappear quickly',
duration: 1000
});
//====> Standard Notification (3 seconds) <====//
Phenix(document).notifications({
message: 'This is the default duration',
duration: 3000
});
//====> Long Notification (5 seconds) <====//
Phenix(document).notifications({
message: 'This will stay longer',
duration: 5000
});
Practical Examples
Button Click Notifications
This example shows how to trigger notifications when buttons are clicked, using data attributes to configure the notification options.
HTML
<!-- Notification Trigger Buttons -->
<button class="btn primary notification-demo"
data-type="success"
data-message="Operation completed successfully!">
Show Success Message
</button>
<button class="btn danger notification-demo"
data-type="error"
data-message="An error occurred. Please try again.">
Show Error Message
</button>
JavaScript
//====> Button Click Handler <====//
Phenix('.notification-demo').on('click', isClicked => {
// Get notification data from the clicked element
let type = isClicked.target.getAttribute('data-type'),
message = isClicked.target.getAttribute('data-message');
// Create and show the notification
Phenix(document).notifications({
type: type,
message: message,
duration: 3000,
position: 'top, center'
});
});
Form Submission Notification
This example demonstrates how to show a notification after a form is submitted, providing feedback to the user about the submission status.
HTML
<!-- Contact Form -->
<form id="contact-form" class="pdy-15">
<div class="form-control mb-15">
<input type="text" name="name" placeholder="Your Name" required>
</div>
<div class="form-control mb-15">
<input type="email" name="email" placeholder="Your Email" required>
</div>
<div class="form-control mb-15">
<textarea name="message" placeholder="Your Message" required></textarea>
</div>
<button type="submit" class="btn primary">Send Message</button>
</form>
JavaScript
//====> Form Submission Handler <====//
Phenix('#contact-form').on('submit', event => {
// Prevent default form submission
event.preventDefault();
// In a real application, you would send the form data to a server here
// For this example, we'll just simulate a successful submission
// Show a success notification
Phenix(document).notifications({
type: 'success',
message: 'Your message has been sent successfully!',
duration: 4000,
position: 'top, center'
});
// Reset the form
event.target.reset();
});
Options Reference
Option | Type | Default | Description |
---|---|---|---|
type | string | normal | Notification type: normal , success , error , warning |
message | string | '' | Content of the notification |
duration | number | 3000 | Time in milliseconds before notification disappears |
position | string | bottom, start | Position format: "Y, X" (Y: top/center/bottom, X: start/center/end) |
icon | boolean | true | Whether to show an icon based on notification type |
close | boolean | true | Whether to show a close button |
Styling Customization
You can customize the appearance of notifications by overriding the default CSS classes:
.px-notifications
- The container for all notifications.px-item
- Individual notification items
CSS
/*====> Custom Notification Styling <====*/
.px-notifications .px-item {
/* Customize notification box */
border-radius: 8px;
box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
padding: 15px 20px;
}
/* Success notification */
.px-notifications .px-item.success {
background-color: #d4edda;
border-color: #c3e6cb;
color: #155724;
}
/* Error notification */
.px-notifications .px-item.error {
background-color: #f8d7da;
border-color: #f5c6cb;
color: #721c24;
}
/* Warning notification */
.px-notifications .px-item.warning {
background-color: #fff3cd;
border-color: #ffeeba;
color: #856404;
}
Accessibility Considerations
For better accessibility, consider the following practices:
- Use clear and concise messages in notifications
- Ensure sufficient color contrast for text
- Provide enough time for users to read notifications
- Consider using
role="alert"
for important notifications - Ensure notifications can be dismissed by keyboard users
Best Practices
- Be Concise: Keep notification messages short and to the point
- Be Specific: Clearly communicate what happened or what action is needed
- Use Appropriate Types: Use the right notification type for the message context
- Position Strategically: Place notifications where they won't interfere with important content
- Reasonable Duration: Set duration based on message length and importance
- Don't Overuse: Avoid showing too many notifications at once
- Provide Actions: When appropriate, include action buttons within notifications