npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

whiskrjs

v2.0.3

Published

An extremely customizable toast/snackbar library for web applications.

Downloads

371

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

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: '&times;'
  • Description: HTML content inside the close button.
closeButtonContent: '&times;'

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 to 0 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:

  1. Fork the Repository: Click the "Fork" button at the top right of the GitHub repository page.

  2. Clone Your Fork:

git clone https://github.com/charrde/whiskrjs.git
  1. Create a New Branch:
git checkout -b feature/your-feature-name
  1. Make Your Changes: Implement your feature or bug fix.

  2. Commit Your Changes:

git commit -am 'Add some feature'
  1. Push to the Branch:
git push origin feature/your-feature-name
  1. 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!