# browser-notification

> Small library built around browsers native Notification-API adding useful default behaviour.

Latest version **3.0.0** (published 2017-05-31) · MIT license · 0 weekly downloads

## Install

```sh
npm install browser-notification
pnpm add browser-notification
yarn add browser-notification
bun add browser-notification
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.0.0 |
| Published | 2017-05-31 |
| First published | 2017-02-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 5 |
| Author | Hugo Heyman |
| Maintainers | heyhugo |
| Keywords | browser-notification, Notification, browsernotification |

## Links

- npm: https://www.npmjs.com/package/browser-notification
- Repository: https://github.com/HeyHugo/browser-notification
- Homepage: https://github.com/HeyHugo/browser-notification#readme
- Issues: https://github.com/HeyHugo/browser-notification/issues
- npm.io page: https://npm.io/package/browser-notification

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 3.0.0 (latest) — 2017-05-31
- 2.0.1 — 2017-03-30
- 2.0.0 — 2017-02-20
- 1.0.3 — 2017-02-20
- 1.0.2 — 2017-02-19
- 1.0.1 — 2017-02-18
- 1.0.0 — 2017-02-18

## README

# browser-notification

Tiny library built around browsers native [Notification-API](https://developer.mozilla.org/en-US/docs/Web/API/Notification) with some useful default behavior.

[Demo](http://jsbin.com/riboqubela/edit?js,output)

**browser-notification does just a few things**
- Look for [browser support](http://caniuse.com/#feat=notifications) and ask for user permission when initialized.
- Clicking a notification will focus the browser tab that fired the notification.
- `ignoreFocused` - If browser tab is already focused `notify()` -call will be ignored. **optional, default: true**
- For API ergonomics it's always possible to fire `notify()` since in case Notifications are not available it's just a no-op (does nothing).
- `cooldown` - milliseconds before consecutive notification can be fired. **optional, default: 0**
- `timeout` - milliseconds to wait before auto-closing notifications. **optional, default: 0 (disabled)**

### Install
```
yarn add browser-notificaiton
```
or
```
npm install browser-notification --save
```
The library has no dependencies and size is less than 1kB (minified + gzipped).
A UMD build is available in `/dist` of the npm package.

### Usage

```
import {initNotifications, notify} from 'browser-notification';

// Check browser support, ask permission, initialize
initNotifications();
...
// Notify
notify('This is the title.', {body: '...and this is the body'});
```

**Note** - The underlying Notifications API for permission is async so if you want to initialize at the same time as firing `notify()`, you must first resolve the promise returned from `initNotifications()` to ensure initialization is complete, see API and example below.

### API
`initNotifications({options})`
Create and setup the notifier object, asking for permission, returns a promise resolving a boolean indicating wheather notifications are available or not.

Default options:

```
{
  ignoreFocused: true, // ignore notify() -calls when browser tab is already focused.
  timeout: 0,  // Set a time (ms) > 0 to activate
  cooldown: 0,  // Set a time (ms) > 0 to activate
}
```

`notify(title, {options})`
Takes the same arguments at the native [Notification API call](https://developer.mozilla.org/en-US/docs/Web/API/Notification/Notification)
returns the Notification object or null if notification was not sent.
_The Notification object can be used to attach event handlers onclick/onclose/onerror/onshow_


Example of initializing and calling `notify` asyncronously. Also using timeout/cooldown feature
```
import {initNotifications, notify} from 'browser-notification';

initNotifications({
    timeout: 3000,  // Auto-close notifications after 3 sec
    cooldown: 3000,  // Ignore new notify calls for 3 sec
}).then(function(isAvailable) {
  notify('Ping!');

  if (isAvailable) {
    console.log('notification was sent');
  }
  else {
    console.log('notification was not sent');
  }
});
```

---
_Source: https://npm.io/package/browser-notification · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._