WhiskrJS is a highly customizable toast/snackbar library for modern web applications. It enables developers to display non-blocking notifications with extensive customization options, including styles, animations, positions, action buttons, and more.
Want to test out all the features? Click here to check out a demo!
- WhiskrJS
- Highly Customizable: Tailor notifications to match your application's style.
- Multiple Positions: Display notifications in various screen positions.
- Action Buttons: Add interactive buttons for user actions.
- Variety of Animations: Choose from multiple entrance and exit animations.
- Responsive Design: Works seamlessly on all screen sizes.
- Queueing and Limits: Control the number of simultaneous notifications and queue behavior.
- Easy Integration: Simple API for quick setup and use.
- Pause on Hover: Option to pause the notification timer when hovered over.
- Accessibility: Designed with accessibility in mind.
Install WhiskrJS via NPM:
npm install whiskrjsInclude the CSS and JS files directly in your HTML:
<!-- Include JS -->
<script src="https://unpkg.com/whiskrjs/dist/whiskr.umd.js"></script>// Import WhiskrJS
import Whiskr from 'whiskrjs';// Require WhiskrJS
const Whiskr = require('whiskrjs');Include the CSS and JS files in your HTML:
<!-- Include JS -->
<script src="https://unpkg.com/whiskrjs/dist/whiskr.umd.js"></script>
<!-- Whiskr is now available as a global variable -->Display a simple notification:
Whiskr.show({
message: 'Hello World!',
type: 'success', // 'success', 'error', 'info', 'warning'
});Displays a notification with the specified options.
options(object): Configuration options for the notification.
- Type:
string - Default:
'' - Description: The text message to display in the notification.
message: 'Operation completed successfully!'- Type:
string - Default:
'' - Description: Custom HTML content to display in the notification. Overrides message if provided.
html: '<strong>Success:</strong> Data saved!'- Type:
string - Default:
'info' - Options:
'success','error','info','warning' - Description: Predefined styling for common notification types.
type: 'error'- Type:
number - Default:
5000(milliseconds) - Description: Duration the notification is displayed. Set to
0for persistent notifications until manually closed.
duration: 3000 // 3 seconds- Type:
string - Default:
'top-right' - Options:
'top-left''top-right''bottom-left''bottom-right''top-center''bottom-center''center'
- Description: Screen position where the notification appears.
position: 'bottom-center'- Type:
object - Default:
{} - Description: Custom CSS styles applied to the notification container.
styles: {
backgroundColor: '#4CAF50',
color: '#FFFFFF',
fontSize: '16px',
padding: '15px 20px',
borderRadius: '8px',
}- Type:
string - Default:
'' - Description: Color of the notification border.
borderColor: '#9c27b0'- Type:
array - Default:
[] - Description: Sides of the notification to apply the border to. Options are
'top','right','bottom','left'.
borderSides: ['top', 'bottom']- Type:
object - Default:
{} - Description: Thickness of the border on each side.
borderThickness: {
top: '2px',
bottom: '2px',
}- Type:
string - Default:
'right' - Options:
'right','left','bar','none' - Description: Position or style of the close button.
closeButtonStyle: 'bar'- Type:
string - Default:
'#FFFFFF' - Description: Color of the close button.
closeButtonColor: '#FFFFFF'- Type:
string - Default:
'×' - Description: HTML content inside the close button.
closeButtonContent: '×'- Type:
string - Default:
'left' - Options:
'left','center','right' - Description: Text alignment within the notification.
textAlign: 'center'- Type:
string - Default:
'slide' - Options:
'slide','fade','zoom','flip','bounce','rotate','none' - Description: Entrance and exit animation of the notification.
animationType: 'fade'- Type:
number - Default:
500(milliseconds) - Description: Duration of the animation.
animationDuration: 800- Type:
boolean - Default:
false - Description: Pauses the notification timer when hovered over.
pauseOnHover: true- Type:
string - Default:
'auto' - Description: Width of the notification. Can be
'auto','full-width', or any valid CSS width value (e.g.,'300px','50%').
width: '400px'- Type:
string - Default:
'wrap' - Options:
'wrap','scroll','ellipsis' - Description: Behavior when text overflows the notification container.
textOverflow: 'ellipsis'- Type:
array - Default:
[] - Description: Array of action button objects to include in the notification.
Action Button Object Structure:
{
text: 'Button Text',
onClick: () => { /* Handle click */ },
styles: {
/* Custom styles */
},
hoverColor: '#FFD54F',
activeColor: '#FFCA28',
}Example:
actionButtons: [
{
text: 'Undo',
onClick: () => {
console.log('Undo action clicked!');
},
styles: {
backgroundColor: '#FFC107',
color: '#FFFFFF',
padding: '6px 12px',
borderRadius: '4px',
},
hoverColor: '#FFD54F',
activeColor: '#FFCA28',
},
]Sets global settings that affect all notifications.
maxToasts(number): Maximum number of notifications to display per position. Set to0for unlimited.queue(boolean): Whether to queue notifications when the maximum is reached.fontFamily(string): Global font family for all notifications.
Example:
Whiskr.settings({
maxToasts: 5, // Maximum number of notifications per position
queue: true, // Enable queueing of notifications
fontFamily: 'Arial, sans-serif', // Set global font family
});Whiskr.show({
message: '✅ Success! Your action was completed.',
type: 'success',
duration: 4000,
});Whiskr.show({
message: '🎨 Custom Styled Notification',
styles: {
backgroundColor: '#9C27B0',
color: '#FFFFFF',
fontSize: '18px',
padding: '20px 30px',
borderRadius: '10px',
boxShadow: '0 6px 16px rgba(0, 0, 0, 0.2)',
},
borderColor: '#E91E63',
borderSides: ['top'],
borderThickness: {
top: '3px',
},
position: 'top-center',
textAlign: 'center',
});Whiskr.show({
message: '💾 Do you want to save changes?',
type: 'info',
duration: 0, // Keep the toast open indefinitely until an action is taken
closeButtonStyle: 'none', // Remove the close button
actionButtons: [
{
text: 'Save',
onClick: () => {
console.log('Save clicked');
// Your save logic here
},
styles: {
backgroundColor: '#4CAF50',
color: '#FFFFFF',
padding: '6px 12px',
borderRadius: '4px',
},
hoverColor: '#66BB6A',
},
{
text: 'Cancel',
onClick: () => {
console.log('Cancel clicked');
// Your cancel logic here
},
styles: {
backgroundColor: '#F44336',
color: '#FFFFFF',
padding: '6px 12px',
borderRadius: '4px',
},
hoverColor: '#EF5350',
},
],
});Whiskr.show({
message: '🎞️ Custom Animation',
animationType: 'zoom',
animationDuration: 700,
});Whiskr.show({
message: '❎ Custom Close Button',
closeButtonStyle: 'left',
closeButtonColor: '#FFC107',
closeButtonContent: '✖',
});Whiskr.show({
// Basic Content
message: '🚀 Welcome to WhiskrJS!',
html: '<strong>🚀 Welcome to <span style="color: #e91e63;">WhiskrJS</span>!</strong>',
// Notification Type
type: 'success', // Options: 'success', 'error', 'info', 'warning'
// Duration and Position
duration: 0, // Keep the notification open indefinitely until an action is taken
position: 'top-center', // Options: 'top-left', 'top-right', 'bottom-left', 'bottom-right', 'top-center', 'bottom-center', 'center'
// Custom Styles
styles: {
backgroundColor: '#333',
color: '#fff',
fontSize: '16px',
padding: '20px',
borderRadius: '10px',
boxShadow: '0 4px 12px rgba(0, 0, 0, 0.3)',
fontFamily: 'Roboto, sans-serif',
},
// Border Customization
borderColor: '#e91e63',
borderSides: ['top', 'bottom'],
borderThickness: {
top: '4px',
bottom: '4px',
},
// Close Button Customization
closeButtonStyle: 'left', // Options: 'left', 'right', 'bar', 'none'
closeButtonColor: '#e91e63',
closeButtonContent: '✖',
// Text Alignment
textAlign: 'center', // Options: 'left', 'center', 'right'
// Animation Settings
animationType: 'bounce', // Options: 'slide', 'fade', 'zoom', 'flip', 'bounce', 'rotate', 'none'
animationDuration: 800, // In milliseconds
animationEase: 'ease-in-out',
// Interaction Options
pauseOnHover: true,
focus: true,
// Dimensions and Text Overflow
width: '400px', // Can be 'auto', 'full-width', or any valid CSS width value
textOverflow: 'wrap', // Options: 'wrap', 'ellipsis', 'scroll'
// Action Buttons
actionButtons: [
{
text: 'Get Started',
onClick: () => {
alert('Let\'s get started!');
},
styles: {
backgroundColor: '#e91e63',
color: '#fff',
padding: '10px 20px',
borderRadius: '5px',
fontSize: '14px',
},
hoverColor: '#d81b60',
activeColor: '#c2185b',
},
{
text: 'Learn More',
onClick: () => {
window.open('https://github.com/whiskrjs/whiskrjs', '_blank');
},
styles: {
backgroundColor: '#2196f3',
color: '#fff',
padding: '10px 20px',
borderRadius: '5px',
fontSize: '14px',
},
hoverColor: '#1e88e5',
activeColor: '#1976d2',
},
],
// Callback Function
onClose: () => {
console.log('Notification closed');
},
});Control the overall behavior of the notification system.
Whiskr.settings({
maxToasts: 3, // Limit to 3 notifications per position
queue: true, // Enable queuing
fontFamily: 'Verdana, sans-serif', // Set a global font family
});WhiskrJS is compatible with all modern browsers, including:
- Chrome
- Firefox
- Safari
- Edge
- Opera
For legacy browser support (e.g., Internet Explorer 11), ensure you transpile your code with Babel and include necessary polyfills.
Contributions are welcome! Please follow these steps:
-
Fork the Repository: Click the "Fork" button at the top right of the GitHub repository page.
-
Clone Your Fork:
git clone https://github.com/charrde/whiskrjs.git- Create a New Branch:
git checkout -b feature/your-feature-name-
Make Your Changes: Implement your feature or bug fix.
-
Commit Your Changes:
git commit -am 'Add some feature'- Push to the Branch:
git push origin feature/your-feature-name- Open a Pull Request: Go to your fork on GitHub and open a pull request to the main repository.
Please ensure your code adheres to the project's coding standards and passes all tests.
This project is licensed under the MIT License - see the LICENSE file for details.
- Inspired by popular notification libraries like Toastr and Noty.
- Emoji icons from Emoji Cheat Sheet.
If you have any questions or need support, please open an issue on the GitHub repository.
A: You can include custom fonts or icons by adding them to your project's CSS and referencing them in the styles option.
styles: {
fontFamily: 'Your Custom Font',
},
html: '<i class="custom-icon"></i> Custom Notification',A: Yes, WhiskrJS supports displaying multiple notifications simultaneously. You can control the maximum number of notifications displayed per position using Whiskr.settings({ maxToasts: number }).
A: Currently, WhiskrJS does not provide a built-in method to remove all notifications at once. However, you can manually remove all notifications by selecting them and removing them from the DOM.
// Remove all Whiskr notifications
document.querySelectorAll('.whiskr-js-container').forEach(container => {
container.parentNode.removeChild(container);
});A: You can customize the animation by setting the animationType, animationDuration, and animationEase options in Whiskr.show().
Whiskr.show({
message: 'Custom Animation',
animationType: 'bounce',
animationDuration: 800,
animationEase: 'ease-in-out',
});A: Yes, WhiskrJS is designed with accessibility in mind, using appropriate ARIA roles and attributes.
If you find this library helpful, please consider starring the repository on GitHub. Your support is much appreciated!
Thank you for using WhiskrJS!