@gravity-ui/uikit
Version:
Gravity UI base styling and components
139 lines (101 loc) • 9.32 kB
Markdown
# Toaster
This is a component for adjustable notifications also known as toasts.
## Using Toaster
To show toasts in your application you need to wrap your application in `ToasterProvider`.
```jsx
import {Toaster, ToasterComponent, ToasterProvider} from '@gravity-ui/uikit';
const toaster = new Toaster();
const root = ReactDOMClient.createRoot(document.getElementById('root'));
root.render(
<ToasterProvider toaster={toaster}>
<App />
<ToasterComponent className="optional additional classes" />
</ToasterProvider>,
);
```
`toaster` here is the instance of the class, which holds the state with all your toasts and used under the hood in `useToaster` hook and `withToaster` HOC.
But you can also use `toaster` directly in different parts of your application (outside React):
```js
toaster.add({
title: 'Toaster is here',
});
```
You must use same instance of `Toaster` in React and outside of it to show all toasts in the same container on the screen.
You can implement this logic yourself or import ready-to-use instance from `toaster-singleton` module.
```js
import {toaster} from '@gravity-ui/uikit/toaster-singleton';
```
## Using `useToaster`
You can show toasts with the `useToaster` hook in your app components:
```jsx
import {useToaster} from '@gravity-ui/uikit';
import {useEffect} from 'react';
export function FoobarComponent() {
const {add} = useToaster();
useEffect(() => {
add({
title: 'Toaster is here',
});
}, []);
return null;
}
```
The hook returns the `add`, `update`, `remove`, and `removeAll` methods (see below for details).
## Using `Toaster` as a HOC
For class components, you can use the `withToaster` HOC, which will inject the `toaster` property into the component.
```jsx
import {Component} from 'react';
import {withToaster} from '@gravity-ui/uikit';
class FoobarComponent extends Component {
render() {
this.props.toaster.add({});
}
}
const FoobarWithToaster = withToaster()(FoobarComponent);
```
## Properties
These are the props of the `ToasterComponent` component.
| Name | Description | Type | Default |
| :-------- | :-------------------------------------------------- | :-------: | :-----: |
| className | Custom class name to add to the component container | `string` | |
| mobile | Configuration that manages mobile/desktop views | `boolean` | |
| hasPortal | Renders the toaster inside a `Portal` when enabled | `boolean` | `true` |
## Constructor arguments
| Parameter | Type | Default | Description |
| :-------- | :-------- | :---------- | :-------------------------------------------------- |
| className | `string` | `undefined` | Custom class name to add to the component container |
| mobile | `boolean` | `false` | Configuration that manages mobile/desktop views |
## Methods
| Method name | Params | Description |
| :---------------------------- | :----------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
| add(toastOptions) | `Object` | Creates a new notification |
| remove(name) | `string` | Manually deletes an existing notification |
| removeAll() | | Deletes all existing notifications |
| update(name, overrideOptions) | `string`, `Object` | Changes already rendered notification content. In `overrideOptions`, the `title`, `type`, `content`, and `actions` fields are optional. |
| has(name) | `string` | Checks for a toast with the certain name in the list of displayed toasts |
## More on `add`
It accepts the `toastOptions` argument with the ongoing notification details:
| Parameter | Type | Required | Default | Description |
| :--------- | :-------------------------------------- | :------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | `string` | yes | | Unique notification name. Notifications with identical names are collapsed into one |
| title | `string` | | | Notification title |
| className | `string` | | | CSS class |
| autoHiding | `number` or `false` | | 5000 | Number of ms to delay hiding the notification. Use `false` to disable hiding the toast after timeout |
| content | `node` | | `undefined` | Notification content. This may be [anything that can be rendered: numbers, strings, elements, or an array](https://reactjs.org/docs/typechecking-with-proptypes.html#proptypes) |
| theme | `string` | | `"normal"` | Notification theme. The possible values are `"normal"`, `"info"`, `"success"`, `"warning"`, `danger`, and `"utility"`. If `theme` is set to anything but `"normal"`, the icon will be added into the notification title. _By default, there is no icon_. |
| isClosable | `boolean` | | `true` | Configuration that manages the visibility of the X icon, which allows the user to close the notification |
| actions | `ToastAction[] \| () => ReactElement` | | `undefined` | Array of actions that are displayed after `content`, or callback, that returned required actions |
| renderIcon | `(toastProps: ToastProps) => ReactNode` | | `undefined` | Used to customize the toast icon. Type-based behavior is used by default |
Every `action` is an object with following parameters:
| Parameter | Type | Required | Default | Description |
| :--------------- | :---------------------------------------- | :------- | :--------- | :----------------------------------------------------------------------- |
| label | `string` | yes | | Action description |
| onClick | `() => void` | yes | | On-action click handler |
| view | [`ButtonView`](./Button.md#props) | | `outlined` | Action appearance, same as `view` for `<Button/>` |
| removeAfterClick | `boolean` | | `true` | Enables or disables closing the notification after the action is clicked |
## CSS API
| Name | Description |
| :------------------------- | :-------------- |
| `--g-toaster-width` | Container width |
| `--g-toaster-item-padding` | Item padding |
| `--g-toaster-item-gap` | Item gap |