mui-alert-provider
Version:
Make your alerts float! A lightweight provider for Material UI’s Alert that fits seamlessly into any web UI.
127 lines (86 loc) • 5.94 kB
Markdown
# MUI Alert Provider
[](https://www.npmjs.com/package/mui-alert-provider)
[](https://www.npmjs.com/package/mui-alert-provider)
[](https://www.npmjs.com/package/mui-alert-provider)
[](https://www.npmjs.com/package/mui-alert-provider)
Make your alerts float! A lightweight provider for Material-UI’s Alert that fits seamlessly into any web UI.
Build a stack of [MUI Alert](https://mui.com/material-ui/react-alert/?srsltid=AfmBOorG16fDWlZUFpNDld6CbDRdpPOA8eTPa9eEriOYl9CywGZFowmu) in just minutes🚀
## Demo
[](
https://codesandbox.io/p/sandbox/mui-alert-provider-demo-kj6mjz)
### Desktop View
### Mobile View
## Features
- **Floating Stacks of MUI Alerts**
Display beautifully-styled, floating stacks of MUI Alerts that integrate seamlessly into any web UI. Fully customizable to match your design system.
- **Easy Integration with Context API & React Hooks**
Built on the [Context API](https://react.dev/reference/react/hooks#context-hooks) and [React Hooks](https://react.dev/learn/reusing-logic-with-custom-hooks) for fast setup. Easily trigger alerts from anywhere in your React component tree.
- **Lightweight & Performant**
Designed to be super lightweight with minimal impact on your bundle size and blazing-fast performance.
- **Accessible by Design**
Follows MUI’s accessibility standards to deliver an inclusive and user-friendly experience for all users.
## Installation
```bash
npm install mui-alert-provider
```
or
```bash
yarn add mui-alert-provider
```
## Usage
[Check out this playground](
https://codesandbox.io/p/sandbox/mui-alert-provider-demo-kj6mjz) 🎮
Wrap your application with the `AlertProvider`. If you're using the `ThemeProvider` from MUI, ensure that the `AlertProvider` is a child of it.
```jsx
import React from 'react';
import ReactDOM from 'react-dom';
import { AlertProvider } from 'mui-alert-provider';
const App = () => (
<AlertProvider>
{/* Your application components */}
</AlertProvider>
);
ReactDOM.render(<App />, document.getElementById('root'));
```
Trigger alerts from any part of your application using the `useAlert` hook. This hook provides access to the `addAlert` method, allowing you to add a new alert to the stack.
```jsx
import { useAlert } from 'mui-alert-provider';
const MyComponent = () => {
const {addAlert} = useAlert();
const handleClick = () => {
addAlert({
message: "Please enter your name to continue",
severity: "error",
})
};
return <button onClick={handleClick}>Show Alert</button>;
};
```
## API
### `AlertProvider`
Wraps your application and provides alert context.
#### Props
| Prop Name | Type | Default | Description |
|-------------------|------------|-----------|-----------------------------------------------------------------------------|
| `children` | `node` | N/A | React nodes to render inside the provider. |
| `limit` | `number` | `4` | The maximum number of alerts that can be displayed simultaneously. |
| `mobileLimit` | `number` | `1` | The maximum number of alerts that can be displayed simultaneously on screens smaller than `mobileBreakpoint`. |
| `position` | `AlertPosition` | `"top-right"` | Specifies where the alerts will appear on the screen. Options include `"top-right"`, `"top-left"`, `"bottom-left"`, or `"bottom-right"`. |
| `width` | `string` | `"20%"` | The width of the alert container. Accepts any valid CSS width value. On screens smaller than `mobileBreakpoint`, it automatically adjusts to 100% for optimal mobile responsiveness. |
| `minWidth` | `string` | `"280px"` | Sets the minimum width of the alert container. Accepts any valid CSS width value. On screens smaller than `mobileBreakpoint`, it automatically adjusts to 100% for optimal mobile responsiveness. |
| `containerSx` | `SxProps` | `{}` | A custom MUI `sx` object to style the container that holds the stack of alerts. |
| `duration` | `number` | `300` | The time (in milliseconds) that the alert's animation lasts, including its appearance and disappearance transitions. |
| `muiAlertProps` | `AlertProps` | `{}` | Props to be passed directly to the underlying [MUI Alert](https://mui.com/material-ui/api/alert/) component. |
| `muiStackProps` | `StackProps` | `{}` | Props to be passed directly to the underlying [MUI Stack](https://mui.com/material-ui/api/stack/) component. |
| `mobileBreakpoint` | `number` | `600` | The breakpoint width in pixels to consider a device as mobile. Alerts will adjust their behavior accordingly. 600px by default. |
### `useAlert`
#### Methods
| Method | Type | Description |
|---------------------------------|-----------------------------------|-------------------------------------------------------------------------------------------------|
| `addAlert({ message, severity })` | `(alert: Alert) => void` | Adds a new alert to the stack. `severity` defaults to `"success"` as defined by MUI. |
## Contributing
Contributions are welcome! Please open an issue or submit a pull request.
## License
This project is licensed under the [MIT License](LICENSE).