Toaster

Maintainer:
ogonkov
GitHub
title
content
action
theme
autoHiding
isClosable
isMobile

Toaster — компонент для настраиваемых уведомлений.

Использование Toaster

Чтобы показывать тосты в вашем приложении, необходимо обернуть приложение в ToasterProvider.

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 является экземпляром класса, который хранит состояние всех ваших тостов и используется "под капотом" в хуке useToaster и HOC withToaster.

Вы также можете использовать toaster напрямую в различных частях вашего приложения (вне React):

toaster.add({
  title: 'Toaster is here',
});

Необходимо использовать один и тот же экземпляр Toaster в React и за его пределами, чтобы все тосты отображались в одном контейнере на экране. Вы можете реализовать эту логику самостоятельно или импортировать готовый экземпляр из модуля toaster-singleton.

import {toaster} from '@gravity-ui/uikit/toaster-singleton';

Использование useToaster

Вы можете показывать тосты с помощью хука useToaster в компонентах вашего приложения:

import {useToaster} from '@gravity-ui/uikit';
import {useEffect} from 'react';

export function FoobarComponent() {
  const {add} = useToaster();

  useEffect(() => {
    add({
      title: 'Toaster is here',
    });
  }, []);

  return null;
}

Хук возвращает методы add, update, remove и removeAll (подробнее о них ниже).

Использование Toaster как HOC

Для классовых компонентов можно использовать HOC withToaster, который добавит свойство toaster в ваш компонент.

import {Component} from 'react';
import {withToaster} from '@gravity-ui/uikit';

class FoobarComponent extends Component {
  render() {
    this.props.toaster.add({});
  }
}

const FoobarWithToaster = withToaster()(FoobarComponent);

Аргументы конструктора

ПараметрТипЗначение по умолчаниюОписание
classNamestringundefinedПользовательское имя класса, которое будет добавлено в контейнер компонента.
mobilebooleanfalseКонфигурация, управляющая мобильным и десктопным представлениями.

Методы

Название методаПараметрыОписание
add(toastOptions)ObjectСоздает новое уведомление.
remove(name)stringВручную удаляет существующее уведомление.
update(name, overrideOptions)string, ObjectИзменяет содержимое уже отображенного уведомления. В overrideOptions поля title, type, content и actions необязательные.
has(name)stringПроверяет наличие тоста с заданным именем в списке отображаемых тостов.

Дополнительно о методе add

Он принимает аргумент toastOptions с данными текущего уведомления:

ПараметрТипОбязательноеЗначение по умолчаниюОписание
namestringДаУникальное имя уведомления. Уведомления с одинаковыми именами объединяются в одно.
titlestringЗаголовок уведомления.
classNamestringCSS-класс.
autoHidingnumber или false5000Время задержки в миллисекундах перед скрытием уведомления. Для отключения автоматического скрытия тоста установите значение false.
contentnodeundefinedСодержимое уведомления. Оно может включать все, что можно отобразить: числа, строки, элементы или массив.
themestring"normal"Тема уведомления. Возможные значения: "normal", "info", "success", "warning", danger, "utility". Если для theme установить любое значение, кроме "normal", в заголовок уведомления добавится иконка. По умолчанию иконка отсутствует.
isClosablebooleantrueКонфигурация, управляющая отображением иконки X, которая позволяет пользователю закрыть уведомление.
actionsToastAction[]undefinedМассив действий, отображаемых после content.
renderIcon(toastProps: ToastProps) => ReactNodeundefinedИспользуется для кастомизации иконки тоста. По умолчанию используется поведение на основе типа.

Каждое действие (action) — это объект со следующими параметрами:

ПараметрТипОбязательноеЗначение по умолчаниюОписание
labelstringДаОписание действия.
onClick() => voidДаОбработчик клика по действию.
viewButtonViewoutlinedВнешний вид действия, соответствует view для <Button/>.
removeAfterClickbooleantrueВключает или отключает закрытие уведомления после клика по действию.

API CSS

ИмяОписание
--g-toaster-widthШирина контейнера.
--g-toaster-item-paddingОтступы элемента.
--g-toaster-item-gapИнтервал между элементами.