whiskrjs
v2.0.3
Published
An extremely customizable toast/snackbar library for web applications.
Downloads
371
Maintainers
Readme
WhiskrJS
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.
WhiskrJS Demo
Want to test out all the features? Click here to check out a demo!
Table of Contents
- WhiskrJS
Features
- 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.
Installation
Via NPM
Install WhiskrJS via NPM:
npm install whiskrjs
Via CDN
Include the CSS and JS files directly in your HTML:
<!-- Include JS -->
<script src="https://unpkg.com/whiskrjs/dist/whiskr.umd.js"></script>
Getting Started
Importing WhiskrJS
ES Modules (Recommended)
// Import WhiskrJS
import Whiskr from 'whiskrjs';
CommonJS
// Require WhiskrJS
const Whiskr = require('whiskrjs');
UMD (Browser Global)
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 -->
Basic Usage
Display a simple notification:
Whiskr.show({
message: 'Hello World!',
type: 'success', // 'success', 'error', 'info', 'warning'
});
API Reference
Whiskr.show(options)
Displays a notification with the specified options.
Parameters:
options
(object): Configuration options for the notification.
Options
message
- Type:
string
- Default:
''
- Description: The text message to display in the notification.
message: 'Operation completed successfully!'
html
- Type:
string
- Default:
''
- Description: Custom HTML content to display in the notification. Overrides message if provided.
html: '<strong>Success:</strong> Data saved!'
type
- Type:
string
- Default:
'info'
- Options:
'success'
,'error'
,'info'
,'warning'
- Description: Predefined styling for common notification types.
type: 'error'
duration
- Type:
number
- Default:
5000
(milliseconds) - Description: Duration the notification is displayed. Set to
0
for persistent notifications until manually closed.
duration: 3000 // 3 seconds
position
- 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'
styles
- Type:
object
- Default:
{}
- Description: Custom CSS styles applied to the notification container.
styles: {
backgroundColor: '#4CAF50',
color: '#FFFFFF',
fontSize: '16px',
padding: '15px 20px',
borderRadius: '8px',
}
borderColor
- Type:
string
- Default:
''
- Description: Color of the notification border.
borderColor: '#9c27b0'
borderSides
- Type:
array
- Default:
[]
- Description: Sides of the notification to apply the border to. Options are
'top'
,'right'
,'bottom'
,'left'
.
borderSides: ['top', 'bottom']
borderThickness
- Type:
object
- Default:
{}
- Description: Thickness of the border on each side.
borderThickness: {
top: '2px',
bottom: '2px',
}
closeButtonStyle
- Type:
string
- Default:
'right'
- Options:
'right'
,'left'
,'bar'
,'none'
- Description: Position or style of the close button.
closeButtonStyle: 'bar'
closeButtonColor
- Type:
string
- Default:
'#FFFFFF'
- Description: Color of the close button.
closeButtonColor: '#FFFFFF'
closeButtonContent
- Type:
string
- Default:
'×'
- Description: HTML content inside the close button.
closeButtonContent: '×'
textAlign
- Type:
string
- Default:
'left'
- Options:
'left'
,'center'
,'right'
- Description: Text alignment within the notification.
textAlign: 'center'
animationType
- Type:
string
- Default:
'slide'
- Options:
'slide'
,'fade'
,'zoom'
,'flip'
,'bounce'
,'rotate'
,'none'
- Description: Entrance and exit animation of the notification.
animationType: 'fade'
animationDuration
- Type:
number
- Default:
500
(milliseconds) - Description: Duration of the animation.
animationDuration: 800
pauseOnHover
- Type:
boolean
- Default:
false
- Description: Pauses the notification timer when hovered over.
pauseOnHover: true
width
- 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'
textOverflow
- Type:
string
- Default:
'wrap'
- Options:
'wrap'
,'scroll'
,'ellipsis'
- Description: Behavior when text overflows the notification container.
textOverflow: 'ellipsis'
actionButtons
- 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',
},
]
Whiskr.settings(options)
Sets global settings that affect all notifications.
Global Settings Options
maxToasts
(number): Maximum number of notifications to display per position. Set to0
for 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
});
Examples
Simple Notification
Whiskr.show({
message: '✅ Success! Your action was completed.',
type: 'success',
duration: 4000,
});
Custom Styled Notification
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',
});
Notification with Action Buttons
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',
},
],
});
Custom Animation
Whiskr.show({
message: '🎞️ Custom Animation',
animationType: 'zoom',
animationDuration: 700,
});
Custom Close Button
Whiskr.show({
message: '❎ Custom Close Button',
closeButtonStyle: 'left',
closeButtonColor: '#FFC107',
closeButtonContent: '✖',
});
Full Comprehensive Example
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');
},
});
Advanced Usage
Global Settings
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
});
Browser Compatibility
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.
Contributing
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.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgements
- Inspired by popular notification libraries like Toastr and Noty.
- Emoji icons from Emoji Cheat Sheet.
Contact
If you have any questions or need support, please open an issue on the GitHub repository.
Frequently Asked Questions
Q: How do I include custom fonts or icons in my notifications?
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',
Q: Can I display multiple notifications at the same time?
A: Yes, WhiskrJS supports displaying multiple notifications simultaneously. You can control the maximum number of notifications displayed per position using Whiskr.settings({ maxToasts: number })
.
Q: How do I remove all notifications at once?
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);
});
Q: How can I customize the animation of the notifications?
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',
});
Q: Is WhiskrJS accessible?
A: Yes, WhiskrJS is designed with accessibility in mind, using appropriate ARIA roles and attributes.
Support
If you find this library helpful, please consider starring the repository on GitHub. Your support is much appreciated!
Thank you for using WhiskrJS!