# 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
```bash
npm install @rorycombe/toaster
```
## Quick Start
### HTML
```html
```
### JavaScript/TypeScript
```javascript
import '@rorycombe/toaster';
const toaster = document.querySelector('rc-toaster');
toaster.toast('Operation completed successfully!', 'success');
```
### React
```jsx
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 (
);
}
```
## 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:**
```javascript
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:
```css
rc-toaster {
bottom: 20px;
right: 20px;
}
```
Toast colors can be customized by targeting the shadow DOM:
```css
rc-toaster::part(toast-success) {
background-color: your-color;
}
```
## Examples
### Multiple Toasts
```javascript
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
```javascript
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