@rorycombe/toaster

v0.0.4

Published

a month ago

A toaster web component

Downloads

0High
0Medium
0Low

rorycombe

web components

Toaster

A beautiful, animated toast notification web component inspired by Sonner. Features a card-stacking effect with depth, smooth animations, and intelligent hover interactions.

Features

🎨 Beautiful animations - Smooth slide-in animations and card stacking effects
📚 Card stacking - Toasts stack on top of each other with a depth effect
🎯 Hover interactions - Hover to pause timers and expand the full stack
⏱️ Auto-hide - Toasts automatically hide after 5 seconds
🎭 Multiple types - Support for success, error, warning, and info toasts
🎪 Depth effect - Cards at the back are narrower and centered for a 3D effect
📱 Web Component - Works with any framework or vanilla JavaScript

Installation

npm install @rorycombe/toaster

Quick Start

HTML

<!DOCTYPE html>
<html>
<head>
  <script type="module" src="node_modules/@rorycombe/toaster/dist/index.mjs"></script>
</head>
<body>
  <rc-toaster></rc-toaster>
  
  <script>
    const toaster = document.querySelector('rc-toaster');
    toaster.toast('Hello, world!', 'success');
  </script>
</body>
</html>

JavaScript/TypeScript

import '@rorycombe/toaster';

const toaster = document.querySelector('rc-toaster');
toaster.toast('Operation completed successfully!', 'success');

React

import { useEffect } from 'react';
import '@rorycombe/toaster';

function App() {
  useEffect(() => {
    const toaster = document.querySelector('rc-toaster');
    if (!toaster) {
      const element = document.createElement('rc-toaster');
      document.body.appendChild(element);
    }
  }, []);

  const showToast = (message, type) => {
    const toaster = document.querySelector('rc-toaster');
    toaster.toast(message, type);
  };

  return (
    <div>
      <button onClick={() => showToast('Success!', 'success')}>
        Show Success
      </button>
    </div>
  );
}

API

Methods

`toast(message: string, type?: 'success' | 'error' | 'warning' | 'info'): void`

Displays a toast notification.

Parameters:

message (string, required) - The message to display
type (string, optional) - The toast type. Defaults to 'success'

Toast Types:

'success' - Green background (default)
'error' - Red background
'warning' - Yellow background
'info' - Blue background

Example:

const toaster = document.querySelector('rc-toaster');

// Success toast (default)
toaster.toast('Operation completed!');

// Error toast
toaster.toast('Something went wrong!', 'error');

// Warning toast
toaster.toast('Please check your input', 'warning');

// Info toast
toaster.toast('Here is some information', 'info');

Behavior

Card Stacking

New toasts appear at the front of the stack
Up to 3 toasts are visible when not hovered
Cards further back are narrower and slightly scaled down for depth
Cards are centered relative to the front card for a 3D effect

Auto-Hide

Toasts automatically hide after 5 seconds
Timers pause when hovering over the toast area
Timers resume when you stop hovering
Hidden toasts can still be viewed when hovering over the stack

Hover Interactions

Hovering over any toast or the container:
- Pauses all hide timers
- Expands the stack to show all toasts
- Cards space out evenly for readability
Moving away from the toast area:
- Resumes timers with remaining time
- Collapses the stack back to stacked view

Animations

Slide-in: New toasts slide in from the right
Slide-down: Toasts slide down when hiding
Stack shuffle: Existing toasts smoothly move back when new ones appear
Expand/Collapse: Smooth transitions when hovering

Styling

The toaster is positioned fixed at the bottom-right of the viewport. You can customize the position using CSS:

rc-toaster {
  bottom: 20px;
  right: 20px;
}

Toast colors can be customized by targeting the shadow DOM:

rc-toaster::part(toast-success) {
  background-color: your-color;
}

Examples

Multiple Toasts

const toaster = document.querySelector('rc-toaster');

// Show multiple toasts in sequence
['First', 'Second', 'Third'].forEach((msg, i) => {
  setTimeout(() => {
    toaster.toast(msg, ['success', 'error', 'warning'][i]);
  }, i * 500);
});

Error Handling

try {
  await someAsyncOperation();
  toaster.toast('Operation successful!', 'success');
} catch (error) {
  toaster.toast(`Error: ${error.message}`, 'error');
}

Browser Support

Chrome/Edge (latest)
Firefox (latest)
Safari (latest)
Any browser that supports Web Components and Shadow DOM

License

MIT

Author

Rory Combe