# react-poptart
[](https://github.com/designly1/react-poptart/actions/workflows/alltests.yml) [](https://badge.fury.io/js/react-poptart) [](https://github.com/dwyl/esta/issues)
[Changelog](https://github.com/designly1/react-poptart/blob/master/CHANGELOG.md)
## Overview
`react-poptart` is an easy-to-use notification and alert system for React apps. It includes features such as multiple animations, auto-dismiss notifications, progress bars, customizable alerts, and flexible theming options.
The bundled size of `react-poptart` is a mere 13kb, much smaller than most other libraries!
This documentation will guide you through the setup, usage, and customization of the Poptart Notification and Alert components.
## Installation
To install the package, use npm:
```bash
npm install react-poptart
```
## Setup
To use the Poptart component in your React app, you must wrap your application in the `PoptartProvider`. This ensures that all child components can trigger notifications and alerts.
```tsx
import React from 'react';
import { PoptartProvider } from 'react-poptart';
function App() {
return (
);
}
export default App;
```
## Notifications Usage
To trigger a notification, use the `usePoptart()` hook, which provides access to the `push()` and `dismiss()` methods.
### Example:
```tsx
import React from 'react';
import { usePoptart } from 'react-poptart';
const NotificationButton = () => {
const { push } = usePoptart();
const handleClick = () => {
push({
type: 'success',
message: 'This is a success notification!',
duration: 5000, // Optional: Specify duration in milliseconds
});
};
return ;
};
```
### Promises
You can also create a poptart with a loading spinner that resolves to either an error or success poptart:
```ts
// Promise interface
interface I_PoptartPromise {
promise: Promise;
successMessage: string;
errorMessage: string;
}
// Promise method
promise(message: string, promise: I_PoptartPromise, overrides?: Partial) => string;
```
### Example:
```ts
const handleCreatePromisePoptart = () => {
poptart.promise('Saving user data...', {
promise: new Promise(resolve => {
setTimeout(() => {
resolve();
}, 2000);
}),
successMessage: 'User data saved successfully!',
errorMessage: 'Failed to save user data',
});
};
```
## Poptart Properties
| Property | Type | Default | Description |
| -------------------- | ---------------- | ------------ | ----------------------------------------------------------------------------------------------------- |
| `type?` | string | `'info'` | Type of the notification: `'info'`, `'success'`, `'error'`, `'warning'` |
| `message` | string | N/A | The message displayed inside the notification |
| `width?` | string | `'450px'` | Width of the notification |
| `duration?` | number | `5000` | How long the notification stays visible (in milliseconds) |
| `poptartStyle` | string | `'default'` | Style of poptart container. Options: `'default'`, `'filled'`, or `'inverted'`. Default is `'filled'`. |
| `animation?` | string | `'bounceIn'` | Animation for the notification. Available options are `'fade'`, `'slide'`, `'bounceIn'`, etc. |
| `animationDuration?` | number | `0.6` | Animation duration in seconds |
| `onClick?` | function | `undefined` | Callback function for when a Poptart is clicked |
| `promise?` | I_PoptartPromise | `undefined` | Create a promise poptart that resolves to either an error or success poptart (see promises section) |
## Alerts Usage
You can also trigger alerts using the `alert()` method from `usePoptart()`. Alerts provide more detailed interactions like confirmation buttons and more.
### Example:
```tsx
import React from 'react';
import { usePoptart } from 'react-poptart';
const AlertButton = () => {
const { alert } = usePoptart();
const handleAlertClick = () => {
alert({
title: 'Confirmation',
message: 'Are you sure you want to proceed?',
confirmButtonLabel: 'Yes',
cancelButtonLabel: 'No',
onConfirm: () => {
console.log('Confirmed!');
},
onCancel: () => {
console.log('Cancelled!');
},
});
};
return ;
};
```
## Alert Properties
| Property | Type | Default | Description |
| ------------------------ | -------- | ------------- | ---------------------------------------------------------------------- |
| `title` | string | N/A | The title of the alert |
| `message` | string | N/A | The message displayed inside the alert |
| `confirmButtonLabel?` | string | `'Ok'` | The label for the confirm button |
| `cancelButtonLabel?` | string | `'Cancel'` | The label for the cancel button |
| `onConfirm?` | function | N/A | Callback function when the confirm button is pressed |
| `onCancel?` | function | N/A | Callback function when the cancel button is pressed |
| `showCancelButton?` | boolean | `true` | Whether to show the cancel button |
| `showConfirmButton?` | boolean | `true` | Whether to show the confirm button |
| `defaultBackgroundColor?`| string | `#F5F5F5` | Background color of the alert |
| `defaultFontColor?` | string | `#000` | Font color of the alert text |
| `defaultAnimation?` | string | `'slideFromBottom'` | Animation for the alert display |
| `defaultAnimationDuration?`| number | `0.25` | Animation duration in seconds |
| `allowClickOffDismissal?`| boolean | `true` | Whether clicking outside the alert dismisses it |
## Alert Inputs
In addition to basic alerts, `react-poptart` also supports input fields inside alerts, allowing for forms or other types of user input to be captured directly within the alert.
### Example:
```tsx
import React from 'react';
import { usePoptart } from 'react-poptart';
const InputAlertButton = () => {
const { alert } = usePoptart();
const handleAlertClick = () => {
alert({
title: 'Enter Your Email',
message: 'Please provide your email address.',
input: {
type: 'email',
placeholder: 'your-email@example.com',
required: true,
},
confirmButtonLabel: 'Submit',
cancelButtonLabel: 'Cancel',
onConfirm: (value) => {
console.log('Input value:', value);
},
});
};
return ;
};
```
### Alert Input Props
| Property | Type | Default | Description |
| ------------------------ | -------- | ----------- | ------------------------------------------- |
| `type?` | string | `text` | The type of input (e.g., `text`, `email`) |
| `placeholder?` | string | `""` | Placeholder text |
| `required?` | boolean | `false` | Whether the input is required |
| `validationCallback?` | function | `undefined` | Callback for custom input validation |
## Alert Inputs with Custom Validation
You can add custom validation to alert inputs by passing a `validationCallback` to the input configuration. This function should return `true` if the input is valid or return a string message if the validation fails. The string message will be displayed as an error.
### Example with Custom Validation:
```tsx
import React from 'react';
import { usePoptart } from 'react-poptart';
const CustomValidationAlertButton = () => {
const { alert } = usePoptart();
const handleAlertClick = () => {
alert({
title: 'Enter Your Email',
message: 'Please provide your email address.',
input: {
type: 'email',
placeholder: 'your-email@example.com',
required: true,
validationCallback: (value) => {
const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
if (!value) {
return 'Email is required';
} else if (!emailPattern.test(value)) {
return 'Please enter a valid email address';
}
return true;
},
},
confirmButtonLabel: 'Submit',
cancelButtonLabel: 'Cancel',
onConfirm: (value) => {
console.log('Valid input:', value);
},
});
};
return ;
};
```
### Custom Validation Workflow:
1. The `validationCallback` function is passed to the alert input.
2. If the input is valid, the callback returns `true`.
3. If the input is invalid, the callback returns a string which will be displayed as an error message below the input field.
## Default Configuration
Below is the default configuration for `react-poptart`. You can override these settings by passing a custom configuration object to the `PoptartProvider`.
```tsx
export const defaultConfig: I_PoptartConfig = {
// Default colors for the Poptart notifications
colors: {
success: '#229645', // Green color for success notifications
error: '#e71b44', // Red color for error notifications
warning: '#e9c514', // Yellow color for warning notifications
info: '#1FA2FF', // Blue color for info notifications
loading: '#4b5155', // Gray color for loading notifications
textLight: '#f9f9f9', // Light contrasting color for text
textDark: '#171717', // Dark contrasting color for text
invertedBackground: '#f6f6f6', // Background color for inverted notifications
},
// Override styles for various Poptart components
styleOverrides: {
container: {}, // Custom styles for the Poptart container
poptart: {}, // Custom styles for individual Poptart notifications
progressBar: {}, // Custom styles for the progress bar
alertContainer: {}, // Custom styles for the alert container
alert: {}, // Custom styles for the alert itself
},
// Default alignment of Poptarts (possible values: 'tl' - top-left, 'tc' - top-center, 'tr' - top-right, 'bl'
// - bottom-left, 'bc' - bottom-center, 'br' - bottom-right)
defaultPoptartStyle: 'default', // Default style of the notification (possible values: 'default', 'filled', 'inverted')
defaultAlign: 'br',
// Default type of notification (possible values: 'success', 'error', 'warning', 'info')
defaultType: 'info',
// Default duration for which the notification is displayed (in milliseconds)
defaultDuration: 5000,
// Default width of the notification poptart
defaultWidth: '450px',
// Default animation for the notification appearance (possible values: 'bounceIn', 'fadeIn', 'slideFromLeft',
// 'slideFromRight', 'slideFromTop', 'slideFromBottom')
defaultAnimation: 'bounceIn',
// Default animation duration for notifications (in seconds)
defaultAnimationDuration: 0.6,
// Default font size used in the notification text
fontSize: 16,
// Factor to adjust the size of icons relative to the font size
iconSizeFactor: 2.5,
// Customization for the progress bar in the notification
progressBar: {
lightColor: '#D6D6D6', // Color for the light theme of the progress bar
darkColor: '#454545', // Color for the dark theme of the progress bar
height: 5, // Height of the progress bar
},
// Minimum contrast threshold for readability (used in calculating appropriate text color contrasts)
contrastThreshold: 0.32,
// Padding around the Poptart notification (X-axis)
paddingX: 20,
// Padding around the Poptart notification (Y-axis)
paddingY: 16,
// The z-index to control stacking order of the notification
zIndex: 10,
// Default settings for alerts (confirm/cancel dialog boxes)
alerts: {
defaultWidth: '600px', // Default width of the alert
paddingX: 30, // Padding (X-axis) inside the alert box
paddingY: 26, // Padding (Y-axis) inside the alert box
borderRadius: 10, // Border radius for rounded corners of the alert box
defaultType: 'info', // Default type of alert (info, success, error, or warning)
defaultBackgroundColor: '#ffffff', // Default background color of the alert
defaultFontColor: '#000', // Default text color inside the alert
defaultFontSize: 20, // Default font size for the alert text
defaultTitleFontSize: 28, // Font size for the alert title
iconSizeFactor: 2, // Factor to adjust the size of icons within alerts
borderWidth: 3, // Border width around the alert box
defaultConfirmButtonColor: '#2d2d2d', // Color of the confirm button
defaultCancelButtonColor: '#6B6B6B', // Color of the cancel button
defaultConfirmButtonLabel: 'Ok', // Label text for the confirm button
defaultCancelButtonLabel: 'Cancel', // Label text for the cancel button
defaultShowCancelButton: false, // Whether the cancel button is shown by default
defaultShowConfirmButton: true, // Whether the confirm button is shown by default
defaultAnimation: 'slideFromBottom', // Default animation for alert boxes
defaultAnimationDuration: 0.25, // Default duration for alert box animations (in seconds)
allowClickOffDismissal: true, // Whether clicking outside the alert dismisses it
// Default input styles for alerts (if input is used)
input: {
backgroundColor: '#fcfcfcac', // Background color for input fields in alerts
fontColor: '#000', // Text color for input fields
borderRadius: 5, // Border radius for the input field
borderWidth: 1, // Border width around the input field
paddingX: 10, // Padding (X-axis) for the input field
paddingY: 8, // Padding (Y-axis) for the input field
maxWidth: '70%', // Maximum width of the input field
errorFeedbackColor: '#d12c2c', // Color used to indicate errors in input validation
placeholderColor: '#a0a0a0', // Placeholder text color
},
},
// Default settings for the spinner component
spinner: {
strokeWidth: 7, // Thickness of the spinner ring
baseColor: '#f3f3f3', // Background color of the spinner ring
accentColor: '#bbbbbb', // Accent color of the spinner ring
animationDuration: 1, // Duration of the spinner animation (in seconds)
},
};
```
## Dismissing Alerts
Alerts can be dismissed by clicking on the cancel button, clicking off the alert if `allowClickOffDismissal` is set to `true`, or programmatically using `dismissAlert()`.
```tsx
const { alert, dismissAlert } = usePoptart();
const handleDismiss = () => {
dismissAlert();
};
```
## Custom Styling
You can override the styles of both notifications and alerts by providing a `styleOverrides` object in the configuration.
```tsx
```
## Development
To develop `react-poptart`, simply clone and install dependencies and then run `pnpm run dev`.
To test in a React development project, in the `react-poptart` root directory run:
```
pnpm link --global
```
Then in your React project root, run:
```
pnpm link react-poptart
```
When you're done with development, simply run:
```
pnpm unlink react-poptart
```
Run `pnpm run build` to build and `pnpm run test` to run all tests.
## Issues
To report a bug or an issue, please use the [GitHub Repo Issues Tracker](https://github.com/designly1/react-poptart/issues).
## Contributing
All pull requests are welcome. For major changes, please file an [issue](https://github.com/designly1/react-poptart/issues) first to discuss what you would like to change.