search

sciactive / pnotify

Beautiful JavaScript notifications with Web Notifications support.
https://sciactive.com/pnotify/
Apache License 2.0
3.65k stars 514 forks source link
desktop-notifications html javascript jquery notifications pnotify ui ui-components

readme

PNotify
v4:
v5:

A JavaScript/TypeScript notification, confirmation, and prompt library.

Notifications can display as toast style, snackbar style, banners, dialogs, alerts, or desktop notifications (using the Web Notifications spec) with fall back to an in-browser notice.

PNotify provides a unique notification flow called modalish that provides a good user experience, even when many notifications are shown at once.

Demos

Latest Stable - http://sciactive.com/pnotify/

Development - https://sciactive.github.io/pnotify/

Table of Contents

Getting Started

You can get PNotify using NPM or Yarn. (You can also use jsDelivr.)

You should install the packages you need individually. Alternatively, you can install all of them at once with the pnotify package.

# Install the packages you need individually.

# You definitely need this one.
npm install --save-dev @pnotify/core
# These are the optional ones.
npm install --save-dev @pnotify/animate
npm install --save-dev @pnotify/bootstrap3
npm install --save-dev @pnotify/bootstrap4
npm install --save-dev @pnotify/confirm
npm install --save-dev @pnotify/countdown
npm install --save-dev @pnotify/desktop
npm install --save-dev @pnotify/font-awesome4
npm install --save-dev @pnotify/font-awesome5-fix
npm install --save-dev @pnotify/font-awesome5
npm install --save-dev @pnotify/glyphicon
npm install --save-dev @pnotify/mobile
npm install --save-dev @pnotify/paginate

# ...

# Or, you can install this to get them all.
npm install --save-dev pnotify

Documentation for Old Versions

Migrating from PNotify 4

Installation

In addition to the JS and CSS, be sure to include a PNotify style.

Svelte

PNotify in Svelte.

import { alert, defaultModules } from '@pnotify/core';
import * as PNotifyMobile from '@pnotify/mobile';

defaultModules.set(PNotifyMobile, {});

alert({
  text: 'Notice me, senpai!',
});

React

PNotify in React.

import { alert, defaultModules } from '@pnotify/core';
import '@pnotify/core/dist/PNotify.css';
import * as PNotifyMobile from '@pnotify/mobile';
import '@pnotify/mobile/dist/PNotifyMobile.css';

defaultModules.set(PNotifyMobile, {});

alert({
  text: 'Notice me, senpai!',
});

Angular

PNotify in Angular.

import { alert, defaultModules } from '@pnotify/core';
import '@pnotify/core/dist/PNotify.css';
import * as PNotifyMobile from '@pnotify/mobile';
import '@pnotify/mobile/dist/PNotifyMobile.css';

defaultModules.set(PNotifyMobile, {});

//...
export class WhateverComponent {
  constructor() {
    alert({
      text: 'Notice me, senpai!',
    });
  }
}

For IE support, see this issue.

Angular (Injectable)

PNotify in Angular (Injectable)

// pnotify.service.ts
import { Injectable } from '@angular/core';
import { alert, defaultModules } from '@pnotify/core';
import '@pnotify/core/dist/PNotify.css';
import * as PNotifyMobile from '@pnotify/mobile';
import '@pnotify/mobile/dist/PNotifyMobile.css';

defaultModules.set(PNotifyMobile, {});

@Injectable()
export class PNotifyService {
  getPNotifyAlert() {
    return alert;
  }
}

// whatever.module.ts
//...
import { PNotifyService } from './pnotify.service';
@NgModule({
  declarations: [...],
  imports: [...],
  providers: [PNotifyService],
  bootstrap: [...]
})
export class WhateverModule {}

// whatever.component.ts
import { PNotifyService } from './pnotify.service';
//...
export class WhateverComponent {
  alert = undefined;
  constructor(pnotifyService: PNotifyService) {
    this.alert = pnotifyService.getPNotifyAlert();
    this.alert({
      text: 'Notice me, senpai!'
    });
  }
}

AngularJS

PNotify in AngularJS.

<link
  href="https://github.com/sciactive/pnotify/blob/master/node_modules/@pnotify/core/dist/PNotify.css"
  rel="stylesheet"
  type="text/css"
/>
<link
  href="https://github.com/sciactive/pnotify/blob/master/node_modules/@pnotify/mobile/dist/PNotifyMobile.css"
  rel="stylesheet"
  type="text/css"
/>
var angular = require('angular');
var PNotify = require('@pnotify/core');
var PNotifyMobile = require('@pnotify/mobile');

PNotify.defaultModules.set(PNotifyMobile, {});

angular
  .module('WhateverModule', [])
  .value('PNotify', PNotify)
  .controller('WhateverController', [
    'PNotify',
    function (PNotify) {
      PNotify.alert({
        text: 'Notice me, senpai!',
      });
    },
  ]);

Vanilla JS (ES5)

PNotify in vanilla ES5

<script
  type="text/javascript"
  src="https://github.com/sciactive/pnotify/raw/master/node_modules/@pnotify/core/dist/PNotify.js"
></script>
<link
  href="https://github.com/sciactive/pnotify/blob/master/node_modules/@pnotify/core/dist/PNotify.css"
  rel="stylesheet"
  type="text/css"
/>
<script
  type="text/javascript"
  src="https://github.com/sciactive/pnotify/raw/master/node_modules/@pnotify/mobile/dist/PNotifyMobile.js"
></script>
<link
  href="https://github.com/sciactive/pnotify/blob/master/node_modules/@pnotify/mobile/dist/PNotifyMobile.css"
  rel="stylesheet"
  type="text/css"
/>
<script type="text/javascript">
  PNotify.defaultModules.set(PNotifyMobile, {});

  PNotify.alert({
    text: 'Notice me, senpai!',
  });
</script>

Vanilla JS (ES6)

PNotify in vanilla ES6+

<link
  href="https://github.com/sciactive/pnotify/blob/master/node_modules/@pnotify/core/dist/PNotify.css"
  rel="stylesheet"
  type="text/css"
/>
<link
  href="https://github.com/sciactive/pnotify/blob/master/node_modules/@pnotify/mobile/dist/PNotifyMobile.css"
  rel="stylesheet"
  type="text/css"
/>
<script type="module">
  import {
    alert,
    defaultModules,
  } from 'node_modules/@pnotify/core/dist/PNotify.js';
  import * as PNotifyMobile from 'node_modules/@pnotify/mobile/dist/PNotifyMobile.js';

  defaultModules.set(PNotifyMobile, {});

  alert({
    text: 'Notice me, senpai!',
  });
</script>

Styles

Bright Theme

The default theme, Bright Theme. Supports dark mode. Include the CSS file in your page:

<link
  href="https://github.com/sciactive/pnotify/blob/master/node_modules/@pnotify/core/dist/BrightTheme.css"
  rel="stylesheet"
  type="text/css"
/>

Or if you're using a packager that imports CSS:

import '@pnotify/core/dist/BrightTheme.css';

Material

The Material theme. Supports dark mode. Requires material-design-icons and optionally the Roboto font. Include the CSS file in your page:

<link
  href="https://github.com/sciactive/pnotify/blob/master/node_modules/@pnotify/core/dist/Material.css"
  rel="stylesheet"
  type="text/css"
/>

Or if you're using a packager that imports CSS:

import '@pnotify/core/dist/Material.css';

Then set the default styling and icons to 'material':

import { defaults } from '@pnotify/core';
// or
const { defaults } = require('@pnotify/core');

// Set default styling.
defaults.styling = 'material';
// This icon setting requires the Material Icons font. (See below.)
defaults.icons = 'material';

Material Icons

To use the Material Style icons, include the Material Design Icons Font in your page.

# The official Google package:
npm install --save material-design-icons

# OR, An unofficial package that only includes the font:
npm install --save material-design-icon-fonts
<link
  rel="stylesheet"
  href="https://github.com/sciactive/pnotify/blob/master/node_modules/material-design-icons/iconfont/material-icons.css"
/>

Or if you're using a packager that imports CSS:

import 'material-design-icons/iconfont/material-icons.css';

Alternatively, you can use the Google Fonts CDN:

<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/css?family=Material+Icons"
/>

Or a clone from jsDelivr:

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/material-icons-font@2.0.0/material-icons-font.css"
/>

Roboto Font

The Material style uses the "400" and "500" weights of Roboto. It will fall back to "sans-serif".

You can use the Google Font CDN:

<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;500&display=swap"
/>

Angeler

The Angeler theme. Supports dark mode. Include the CSS file in your page:

<link
  href="https://github.com/sciactive/pnotify/blob/master/node_modules/@pnotify/core/dist/Angeler.css"
  rel="stylesheet"
  type="text/css"
/>

Or if you're using a packager that imports CSS:

import '@pnotify/core/dist/Angeler.css';

It's recommended that you set the close button to not hide by default, as that is how Angela designed the theme to look best.

import { defaults } from '@pnotify/core';
// or
const { defaults } = require('@pnotify/core');

defaults.closerHover = false;

You can use the angeler-extended class to use the alternate, more spacious styling for the Angeler theme. This works great for big, center of the page notices, like page errors.

alert({
  text: "I'll be more expanded than normal, with a separated title line.",
  addClass: 'angeler-extended',
});

:info: It's named after Angela Murrell, who designed it, and it's pronounced like An-jel-er.

Bootstrap

npm install --save-dev @pnotify/bootstrap3 @pnotify/glyphicon
# or
npm install --save-dev @pnotify/bootstrap4

Styling for the popular Bootstrap library. Doesn't support dark mode (but you can use a Bootstrap theme).

Include the CSS:

<link
  rel="stylesheet"
  href="https://github.com/sciactive/pnotify/blob/master/node_modules/@pnotify/bootstrap4/dist/PNotifyBootstrap4.css"
/>

Or if you're using a packager that imports CSS:

import '@pnotify/bootstrap4/dist/PNotifyBootstrap4.css';

Include the appropriate line(s) from below:

import { defaultModules } from '@pnotify/core';
import * as PNotifyBootstrap4 from '@pnotify/bootstrap4';
// or
const { defaultModules } = require('@pnotify/core');
const PNotifyBootstrap4 = require('@pnotify/bootstrap4');

Then set it as a default module:

defaultModules.set(PNotifyBootstrap4, {});

Change the "4" to "3" for Bootstrap 3, and also import and set PNotifyGlyphicon to use Bootstrap 3's glyphicons. PNotifyGlyphicon doesn't have any CSS to import.

Font Awesome 4 (Icons)

npm install --save-dev @pnotify/font-awesome4

To set Font Awesome 4 as the default icons, include the appropriate line from below:

import { defaultModules } from '@pnotify/core';
import * as PNotifyFontAwesome4 from '@pnotify/font-awesome4';
// or
const { defaultModules } = require('@pnotify/core');
const PNotifyFontAwesome4 = require('@pnotify/font-awesome4');

Then set it as a default module:

defaultModules.set(PNotifyFontAwesome4, {});

Font Awesome 5 (Icons)

npm install --save-dev @pnotify/font-awesome5 @pnotify/font-awesome5-fix

To set Font Awesome 5 as the default icons, include the appropriate line from below:

import { defaultModules } from '@pnotify/core';
import * as PNotifyFontAwesome5Fix from '@pnotify/font-awesome5-fix';
import * as PNotifyFontAwesome5 from '@pnotify/font-awesome5';
// or
const { defaultModules } = require('@pnotify/core');
const PNotifyFontAwesome5Fix = require('@pnotify/font-awesome5-fix');
const PNotifyFontAwesome5 = require('@pnotify/font-awesome5');

Then set them as default modules:

defaultModules.set(PNotifyFontAwesome5Fix, {});
defaultModules.set(PNotifyFontAwesome5, {});

If you don't want to use Font Awesome 5 as your default icons, but you still want support for them in your notices, you should include only the @pnotify/font-awesome5-fix package. Font Awesome 5 does some mysterious magic in its code that breaks PNotify. This module has a workaround for it.

Creating Notices

To make a notice, use the factory functions. Each one takes an options object as its only argument. It will return a PNotify notice instance.

import { alert, notice, info, success, error } from '@pnotify/core';
// or
const { alert, notice, info, success, error } = require('@pnotify/core');

// Manually set the type.
const myAlert = alert({
  text: "I'm an alert.",
  type: 'info',
});

// Automatically set the type.
const myNotice = notice({
  text: "I'm a notice.",
});

const myInfo = info({
  text: "I'm an info message.",
});

const mySuccess = success({
  text: "I'm a success message.",
});

const myError = error({
  text: "I'm an error message.",
});

Options

PNotify options and default values.

defaults = {

}

defaultStack = new Stack({
  dir1: 'down',
  dir2: 'left',
  firstpos1: 25,
  firstpos2: 25,
  spacing1: 36,
  spacing2: 36,
  push: 'bottom',
  context: document.body,
});

Learn more about stacks.

defaultModules = new Map();

Changing Defaults

import { defaults } from '@pnotify/core';
// or
const { defaults } = require('@pnotify/core');

defaults.width = '400px';

Adding/removing a module to the defaults:

import { defaultModules } from '@pnotify/core';
import * as PNotifyMobile from '@pnotify/mobile';
// or
const { defaultModules } = require('@pnotify/core');
const PNotifyMobile = require('@pnotify/mobile');

// Add a module to the defaults. Note that the second argument should
// always be `{}`.
defaultModules.set(PNotifyMobile, {});

// Removing a module from the defaults.
defaultModules.delete(PNotifyMobile);

Changing a module's defaults:

import { defaults } from '@pnotify/animate';
// or
const { defaults } = require('@pnotify/animate');

// then
defaults.inClass = 'fadeInDown';
defaults.outClass = 'fadeOutUp';

Modules

Creating Notices with Modules

Besides using the default modules, you can remove or add modules and set their options when you call a notice. The modules Map has modules themselves as keys, and an options object as values.

import { notice, defaultModules } from '@pnotify/core';
import * as PNotifyBootstrap4 from '@pnotify/bootstrap4';
import * as PNotifyFontAwesome4 from '@pnotify/font-awesome4';
import * as PNotifyMobile from '@pnotify/mobile';
import * as PNotifyAnimate from '@pnotify/animate';

defaultModules.set(PNotifyBootstrap4, {});
defaultModules.set(PNotifyFontAwesome4, {});
defaultModules.set(PNotifyMobile, {});

// Remove one of the default modules.
notice({
  text: "I don't have the Mobile module.",
  modules: new Map([
    ...[...defaultModules].filter(([mod]) => mod !== PNotifyMobile),
  ]),
});

// Add an additional module and options.
notice({
  text: 'I use the Animate module in addition to the defaults.',
  modules: new Map([
    ...defaultModules,
    [
      PNotifyAnimate,
      {
        inClass: 'fadeInDown',
        outClass: 'fadeOutUp',
      },
    ],
  ]),
});

// Don't worry about adding a module that's already in the defaults.
// It's a Map, so only the last instance/options will end up in there.
notice({
  text: 'I use the Mobile module with options I specify.',
  modules: new Map([
    ...defaultModules,
    [
      PNotifyMobile,
      {
        swipeDismiss: false,
      },
    ],
  ]),
});

TypeScript

Using modules with TypeScript requires types assertions for module entries, and possibly the downlevelIteration TypeScript option.

import { notice, defaultModules, Notice, ModuleEntry } from '@pnotify/core';
import * as PNotifyConfirm from '@pnotify/confirm';

notice({
  text: "I'm a notice with modules, and my module options are checked by TypeScript.",
  modules: new Map([
    // This requires `"downlevelIteration": true` in your TypeScript config.
    ...defaultModules,
    [
      PNotifyConfirm,
      {
        confirm: true,
        buttons: [
          {
            text: 'Ok',
            primary: true,
            click: (notice: Notice) => notice.close(),
          },
        ],
        // ***
        // Notice the type assertion here. It tells TypeScript that the options
        // are for the Confirm module.
        // ***
      },
    ] as ModuleEntry<typeof PNotifyConfirm>,
  ]),
});

Desktop Module

Notifications that display even when the web page is not visible. Implements the Web Notifications spec.

If the user's browser doesn't support Web Notifications, or they deny permission to show them, they will see regular in-browser notices, unless fallback is false.

npm install --save-dev @pnotify/desktop
import { notice, defaultModules } from '@pnotify/core';
import * as PNotifyDesktop from '@pnotify/desktop';

const myNotice = notice({
  text: "I'm a notice.",
  modules: new Map([
    ...defaultModules,
    [
      PNotifyDesktop,
      {
        // Desktop Module Options
      },
    ],
  ]),
});

PNotifyDesktop.defaults = {

}

Mobile Module

Notices on mobile phones and tablets.

npm install --save-dev @pnotify/mobile
import { notice, defaultModules } from '@pnotify/core';
import * as PNotifyMobile from '@pnotify/mobile';

const myNotice = notice({
  text: "I'm a notice.",
  modules: new Map([
    ...defaultModules,
    [
      PNotifyMobile,
      {
        // Mobile Module Options
      },
    ],
  ]),
});

PNotifyMobile.defaults = {

}

Countdown Module

Give an indication of how much time is left.

npm install --save-dev @pnotify/countdown
import { notice, defaultModules } from '@pnotify/core';
import * as PNotifyCountdown from '@pnotify/countdown';

const myNotice = notice({
  text: "I'm a notice.",
  modules: new Map([
    ...defaultModules,
    [
      PNotifyCountdown,
      {
        // Countdown Module Options
      },
    ],
  ]),
});

PNotifyCountdown.defaults = {

}

Animate Module

Fluid CSS animations using Animate.css.

npm install --save-dev @pnotify/animate
import { notice, defaultModules } from '@pnotify/core';
import * as PNotifyAnimate from '@pnotify/animate';

const myNotice = notice({
  text: "I'm a notice.",
  modules: new Map([
    ...defaultModules,
    [
      PNotifyAnimate,
      {
        // Animate Module Options
      },
    ],
  ]),
});

PNotifyAnimate.defaults = {

}

The Animate module also creates a method, attention(aniClass, callback), on notices which accepts an attention grabber class and an animation completed callback.

Confirm Module

Confirmation dialogs and prompts.

npm install --save-dev @pnotify/confirm
import { notice, defaultModules } from '@pnotify/core';
import * as PNotifyConfirm from '@pnotify/confirm';

const myNotice = notice({
  text: "I'm a notice.",
  modules: new Map([
    ...defaultModules,
    [
      PNotifyConfirm,
      {
        // Confirm Module Options
      },
    ],
  ]),
});

PNotifyConfirm.defaults = {

buttons: [
  {
    text: 'Ok',
    primary: true,
    promptTrigger: true,
    click: (notice, value) => {
      notice.close();
      notice.fire('pnotify:confirm', { notice, value });
    },
  },
  {
    text: 'Cancel',
    click: (notice) => {
      notice.close();
      notice.fire('pnotify:cancel', { notice });
    },
  },
];

}

Because the default buttons fire notice events on confirmation and cancellation, you can listen for them like this:

import { alert } from '@pnotify/core';
const notice = alert({
  title: 'Confirmation Needed',
  text: 'Are you sure?',
  hide: false,
  modules: {
    Confirm: {
      confirm: true,
    },
  },
});
notice.on('pnotify:confirm', () => {
  // User confirmed, continue here...
});
notice.on('pnotify:cancel', () => {
  // User canceled, continue here...
});

Paginate Module

Provide an index and count of the notices in the stack, and/or buttons to let the user page through them.

npm install --save-dev @pnotify/paginate
import { notice, defaultModules } from '@pnotify/core';
import * as PNotifyPaginate from '@pnotify/paginate';

const myNotice = notice({
  text: "I'm a notice.",
  modules: new Map([
    ...defaultModules,
    [
      PNotifyPaginate,
      {
        // Paginate Module Options
      },
    ],
  ]),
});

PNotifyPaginate.defaults = {

}

Exported Methods and Properties

Instance Methods and Properties

Events

Event objects have a detail property that contains information about the event, including a reference to the notice itself.

From the Svelte Component API.

Don't use these. I'm putting them in here to document that you should not use them. That way, if you do, and you file a bug report, I can point to this section in the README, and tell you that you did a bad.

Stacks

A stack is an instance of the Stack class used to determine where to position notices and how they interact with each other.

import { alert, Stack } from '@pnotify/core';

const myStack = new Stack({
  dir1: 'up',
});

alert({
  text: "I'm a notice centered at the bottom!",
  stack: myStack,
});

Stack options and their defaults:

Stack behavior:

Stack methods:

There are other methods on the stack class, but you shouldn't use them. They're meant to be internal, so they begin with an underscore.

Stack properties:

All of the options are properties as well.

Stack events and event.detail contents:

:warning: Calling something like alert({text: 'notice', stack: new Stack({dir1: 'down', firstpos1: 25})}); may not do what you want. It will create a notice, but that notice will be in its own stack and will overlap other notices.

Example Stack

Here is an example stack with comments to explain. You can play with it here.

const stackBottomModal = new Stack({
  dir1: 'up', // With a dir1 of 'up', the stacks will start appearing at the bottom.
  // Without a `dir2`, this stack will be horizontally centered, since the `dir1` axis is vertical.
  firstpos1: 25, // The notices will appear 25 pixels from the bottom of the context.
  // Without a `spacing1`, this stack's notices will be placed 25 pixels apart.
  push: 'top', // Each new notice will appear at the bottom of the screen, which is where the 'top' of the stack is. Other notices will be pushed up.
  modal: true, // When a notice appears in this stack, a modal overlay will be created.
  overlayClose: true, // When the user clicks on the overlay, all notices in this stack will be closed.
  context: document.getElementById('page-container'), // The notices will be placed in the 'page-container' element.
});

If you just want to position a single notice programmatically, and don't want to add any other notices into the stack, you can use something like this:

alert({
  text: "Notice that's positioned in its own stack.",
  stack: new Stack({
    dir1: 'down',
    dir2: 'right', // Position from the top left corner.
    firstpos1: 90,
    firstpos2: 90, // 90px from the top, 90px from the left.
  }),
});

Features

Browser Compatibility and Build Size

PNotify provides prebuilt JS files, and those files are run through Babel to provide compatibility with older browsers. As such, their build size grows to maintain compatibility. If this is not acceptable, you can build much smaller (~80% of original) files yourself with:

git clone https://github.com/sciactive/pnotify.git
cd pnotify
npm i
mv .browserslistrc-smallbuild .browserslistrc
npx lerna bootstrap
npm build

You should now have dist folders in all the packages with smaller (but only compatible with newer browsers) build files. Note that this doesn't apply to Svelte projects, because they build the PNotify *.svelte source files anyway.

Licensing and Additional Info

Copyright 2009-2020 Hunter Perrin Copyright 2015 Google, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

See http://sciactive.com/pnotify/ for more information, and demos.