Home

macOSNotifJS (v0.1.1)
A simple Javascript plugin to create simulated macOS notifications on your website.
macOSNotifJS is a plugin created by Matt Cowley.

NPM Package Version License Dev Dependencies JS Size Code Quality Patreon Slack

Breaking Change
From version 0.0.5-beta2 onwards, the option to trigger the dark mode theme was changed from dark: true to theme: macOSNotifThemes.Dark as part of the theming overhaul.

Installation:

For the easiest use, you can simply install the plugin through NPM:

npm i macosnotif

Or, you can manually install by copying the dist folder from the macOSNotifJS GitHub repository to your website.

To then have the plugin available on a page, in your head tag have the following to load the notification styling:

<link href="path/to/dist/macOSNotif.min.css" rel="stylesheet"/>

At the bottom of your body, you then need to have the following to load the notification script:

<script src="path/to/dist/macOSNotif.min.js"></script>

Usage & Options:

To get started, simply call the function macOSNotif.
This is a wrapper for the main class macOSNotifJS, which creates a new instance with the provided options, runs the notification and then returns the new instance.

To customise your notification, you can supply an object containing any of the options listed below:

options = {
    delay: 0.5,                             // Delay before display (in seconds)
    autoDismiss: 0,                         // Delay till automatic dismiss (0 = Never, in seconds)
    interactDismiss: true,                  // Toggle swipe/drag to dismiss

    sounds: false,                          // Play sounds for notification
    theme: macOSNotifThemes.Light,          // Set the theme to be used by the notification (from window.macOSNotifThemes)
    themeNative: false,                     // Attempt to detect light/dark from OS, fallback to theme
    zIndex: 5000,                           // CSS z-index value of the notification (will be adjusted for stacked notifications)

    imageSrc: null,                         // Link of the icon to display (null to hide icon)
    imageName: "",                          // Alt/Title text of the icon
    imageLink: null,                        // Link for icon click (see link functionality below)
    imageLinkDismiss: true,                 // Dismiss notification after Image Link pressed (useful if link is function)
    imageLinkNewTab: false,                 // Open Image Link in New Tab (ignored if link is set to dismiss)

    title: "macOSNotifJS",                  // Main Notif Title
    subtitle: "Default notification text",  // Main Notif Sub Title

    mainLink: null,                         // Link for the main text body (see link functionality below)
    mainLinkDismiss: true,                  // Dismiss notification after Main Link pressed (useful if link is function)
    mainLinkNewTab: false,                  // Open Main Link in New Tab (ignored if link is set to dismiss)

    btn1Text: "Close",                      // Text for Button 1 (null to hide all buttons)
    btn1Link: null,                         // Link for Button 1 (see link functionality below)
    btn1Dismiss: true,                      // Dismiss notification after Button 1 pressed (useful if link is function)
    btn1NewTab: false,                      // Open Button 1 Link in New Tab (ignored if link is set to dismiss)

    btn2Text: "Go",                         // Text for Button 2 (null to hide second button)
    btn2Link: null,                         // Link for Button 2 (see link functionality below)
    btn2Dismiss: true,                      // Dismiss notification after Button 2 pressed (useful if link is function)
    btn2NewTab: false,                      // Open Button 2 Link in New Tab (ignored if link is set to dismiss)
};

// Link functionality:
//  - Use null for no link (this will act as dismiss on btn1Link & btn2Link)
//  - Use "#" to make the element act as dismiss with no further action
//  - Use any string as a URL which will open when element is clicked
//  - Use a Javascript function to be called when element is clicked
//     (Note: The notification object is passed as the 1st parameter if required)

Native Theme Detection
This feature can be enabled by setting the option themeNative to true. It is designed to detect the theme preference from the user's device (light or dark). This makes use of prefers-color-scheme, which is currently only supported by Safari at the time of writing. Therefor, I suggest ensuring you set the correct fallback theme for your notifications if you are to use themeNative.

Browser Support:

macOSNotifJS is built to have support for the following browser definitions.
You can click on each one to view a full breakdown of every browser the definition covers.



Examples:

Button Configuration:


macOSNotif({
    title:'Dual button notification',
    subtitle:'Two buttons; dismiss and a link (opens in a new tab)',
    btn1Text:'Close',
    btn1Link:null,
    btn2Text:'Author',
    btn2Link:'https://mattcowley.co.uk/',
    btn2NewTab:true
})


macOSNotif({
    title:'Single button notification',
    subtitle:'A single button to dismiss the notification',
    btn2Text:null
})


macOSNotif({
    title:'Main body link notification',
    subtitle:'The main notification body is a link (opens in a new tab)',
    mainLink:'https://mattcowley.co.uk/',
    mainLinkNewTab:true
})


macOSNotif({
    title:'No button notification',
    subtitle:'The main body link dismisses the notification',
    mainLink:'#',
    btn1Text:null
})


macOSNotif({
    title:'Javascript callback button',
    subtitle:'Any link can be set to call a Javascript function',
    mainLink:'#',
    btn1Text:'Ping!',
    btn1Link:function(){alert('Pong!');},
    btn1Dismiss:false,
    btn2Text:null
})

Notification Customisation:


macOSNotif({
    title:'Image (icon) notification with link',
    subtitle:'Has an icon which also has a link',
    imageSrc:'https://mattcowley.co.uk/me.png',
    imageLink:'https://mattcowley.co.uk/',
    imageLinkNewTab:true
})


macOSNotif({
    title:'Sound (alert) notification',
    subtitle:'Requires user interaction first on some browsers',
    sounds:true
})

Theming Support:


macOSNotif({
    title:'Dark mode notification',
    subtitle:'Emulates the macOS dark mode styling',
    theme:macOSNotifThemes.Dark,
    mainLink:'#',
    btn1Text:'Dark',
    btn1Dismiss:false,
    btn1Link:function(n){n.theme = macOSNotifThemes.Dark;},
    btn2Text:'Light',
    btn2Dismiss:false,
    btn2Link:function(n){n.theme = macOSNotifThemes.Light;}
})


macOSNotif({
    title:'Native theme notification',
    subtitle:'Attempts to match the dark/light theme of the OS',
    themeNative:true,
    btn1Text:'Close',
    btn1Link:null,
    btn2Text:'Support',
    btn2Link:'https://caniuse.com/prefers-color-scheme',
    btn2NewTab:true
})


macOSNotif({
    title:'Info themed notification',
    subtitle:'Non-macOS theme to convey information',
    theme:macOSNotifThemes.Info,
    btn2Text:null
})


macOSNotif({
    title:'Warning themed notification',
    subtitle:'Non-macOS theme to convey a warning message',
    theme:macOSNotifThemes.Warning,
    btn2Text:null
})


macOSNotif({
    title:'Danger themed notification',
    subtitle:'Non-macOS theme to convey an immediate danger',
    theme:macOSNotifThemes.Danger,
    btn2Text:null
})


macOSNotif({
    title:'Success themed notification',
    subtitle:'Non-macOS theme to convey success',
    theme:macOSNotifThemes.Success,
    btn2Text:null
})

macOSNotifJS
macOSNotifJS is a plugin created by Matt Cowley.

macOSNotifJS - v0.1.1 - 2019-06-09