https://github.com/codewithkyle/notifyjs
A lightweight JavaScript library for creating toast, snackbars, and notifications.
https://github.com/codewithkyle/notifyjs
lightweight notification notifications snackbar snackbar-notification toast toast-notifications web-components
Last synced: 6 months ago
JSON representation
A lightweight JavaScript library for creating toast, snackbars, and notifications.
- Host: GitHub
- URL: https://github.com/codewithkyle/notifyjs
- Owner: codewithkyle
- License: mit
- Created: 2019-07-05T12:24:44.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2025-03-15T21:22:43.000Z (7 months ago)
- Last Synced: 2025-04-07T01:39:31.880Z (6 months ago)
- Topics: lightweight, notification, notifications, snackbar, snackbar-notification, toast, toast-notifications, web-components
- Language: TypeScript
- Homepage: https://notifyjs.codewithkyle.com/
- Size: 171 KB
- Stars: 11
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Notify.js
Notify.js is a lightweight utility library for creating toast, snackbars, and notifications.
#### CSS Not Included
This library does not provide any CSS or base styling for the components / HTML Elements it produces. Example styles can be found at [Brixi UI](https://ui.brixi.dev/).
- [Notifications](https://ui.brixi.dev/notifications)
- [Toast](https://ui.brixi.dev/toast)
- [Snackbar](https://ui.brixi.dev/snackbar)
- Sonner (coming soon)
## Installation
Download Notify.js via NPM:
```sh
npm i --save @codewithkyle/notifyjs
```
Or use the CDN version:
```javascript
import toaster from "https://cdn.jsdelivr.net/npm/@codewithkyle/notifyjs@5/dist/toaster.js";
import snackbar from "https://cdn.jsdelivr.net/npm/@codewithkyle/notifyjs@5/dist/snackbar.js";
import notifications from "https://cdn.jsdelivr.net/npm/@codewithkyle/notifyjs@5/dist/notifications.js";
import sonner from "https://cdn.jsdelivr.net/npm/@codewithkyle/notifyjs@5/dist/sonner.js";
```
## Usage
1. [Snackbar Notification](#snackbar-notification)
1. [Snackbar Interface](#snackbar-interface)
1. [Snackbar HTML Structure](#snackbar-html-structure)
1. [Notifications](#notifications)
1. [Notifications Interface](#notification-interface)
1. [Notifications HTML Structure](#notification-html-structure)
1. [Toast Notification](#toast)
1. [Toast Interface](#toast-interface)
1. [Toast HTML Structure](#toast-html-structure)
1. [Sonner Notification](#sonner)
1. [Sonner Interface](#sonner-interface)
1. [Sonner HTML Structure](#sonner-html-structure)
### Global Manager
Import the notification type:
```typescript
import snackbar from "@codewithkyle/notifyjs/snackbar";
snackbar({
message: "All snackbar notifications require a message",
});
// Adds an action button
snackbar({
message: "All snackbar notifications require a message",
buttons: [
{
label: "Update",
callback: () => {
console.log("User clicked the update button");
},
},
],
});
```
```typescript
import notifications from "@codewithkyle/notifyjs/notifications";
notifications.push({
title: "Notificaitons require a title",
message: "They also require a message.",
});
// Append custom toast notifications:
class CustomNotificationElement extends HTMLElement {
constructor(message){
super();
this.innerText = message;
setTimeout(() => {
this.remove();
}, 5000);
}
}
notifications.append(new CustomNotificationElement());
```
```typescript
import toaster from "@codewithkyle/notifyjs/toaster";
toaster.push({
message: "Toast notifications require a message."
});
```
```typescript
import sonner from "@codewithkyle/notifyjs/sonner";
sonner.push({
heading: "Sonner toast example",
message: "Heading and message are optional."
});
```
### Custom Events
As of version 5 you can trigger notifications using [custom events](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) dispatched on the `window`.
```typescript
const event = new CustomEvent("notify:sonner", {
detail: {
heading: "Sonner Example",
message: `Example sonner toast message.`,
}
});
window.dispatchEvent(event);
```
The follow events are supported:
- `notify:sonner`
- `notify:alert`
- `notify:toast`
- `notify:snackbar`
The `detail` object accepts the same interfaces as the function versions (see below).
### Custom Event Callbacks
As of version 5 all callback interfaces support `event` and `eventData` properties. When the user interacts with a button a custom event will be fired on the `window`.
```typescript
import sonner from "@codewithkyle/notifyjs/sonner";
sonner.push({
message: "Heading and message are optional.",
button: {
label: "Test",
event: "test-event",
eventData: "Hi mom!",
}
});
// received when the user clicks the button within the sonner notification
window.addEventListener("test-event", (e)=>{
alert(e.detail);
});
```
---
## Snackbar Notification
Snackbar notifications are great for quick one-off notifications that require an action.
### Snackbar Interface
```typescript
type SnackbarNotification = {
message: string;
duration?: number; // in seconds
closeable?: boolean;
buttons?: Array<{
label: string;
callback?: Function;
ariaLabel?: string;
classes?: Array | string;
autofocus?: boolean;
event?: string;
eventData?: any;
}>;
force?: boolean; // defaults to true
classes?: Array | string;
autofocus?: boolean; // defaults to true
}
```
### Snackbar HTML Structure
```html
Custom notification message
Action
```
---
## Notifications
Notifications are great for application-like notification systems where users will need to recieve warnings, updates, successes, and errors.
### Notification Interface
```typescript
type Notification = {
title: string;
message: string;
closeable?: boolean;
icon?: string; // svg or img
duration?: number; // in seconds
classes?: string[];
autofocus?: boolean; // defaults to true
buttons?: Array<{
label: string;
callback?: Function;
ariaLabel?: string;
classes?: Array | string;
autofocus?: boolean;
event?: string;
eventData?: any;
}>;
timer?: "vertical" | "horizontal" | null; // defaults to null
};
```
### Notification HTML Structure
```html
Title
Custom notification message
Action
```
---
## Toast
Toast notifications are great for simple temporary alerts like "Copied to clipboard" or "Added to playlist".
### Toast Interface
```typescript
type ToastNotification = {
message: string;
duration?: number; // in seconds
classes?: string | string[];
};
```
### Toast HTML Structure
```html
Custom toast message.
```
## Sonner
Sonner notifications are great for simple temporary alerts. The Sonner notification is slightly opinionated due to the custom interaction and animations.
```css
sonner-toast-component {
opacity: var(--opacity);
transform: translateY(var(--y)) translateY(var(--offset)) scale(var(--scale));
transition: transform 300ms var(--ease-in-out), opacity 300ms var(--ease-in-out);
left: 0;
bottom: 0;
}
```
> **Note**: the sonner components UX is based on the look and feel of the [Sonner react package](https://sonner.emilkowal.ski/).
### Sonner Interface
```typescript
type SonnerNotification = {
heading?: string,
message?: string,
duration?: number,
classes?: Array|string,
button?: {
callback?: Function,
label: string,
classes?: Array|string,
event?: string;
eventData?: any;
}
};
```
### Sonner HTML Structure
```html
Example heading
This is an example sonner message.
Click me
```