Как использовать SweetAlert для кастомных уведомлений в React

О чём эта статья

Эта статья объясняет, как подключить и использовать SweetAlert в React-приложении для создания кастомных уведомлений. Покрываем: установка, базовые вызовы, передача объекта настроек, кастомизация кнопок и контента, стилизация, автоматическое закрытие, сценарии использования, доступность, шаблоны и чеклисты для команды.

Важно: примеры рассчитаны на клиентский React. Если приложение сервер-рендерится (SSR), убедитесь, что swal запускается только на клиенте.

Установка SweetAlert

Установите пакет через npm или ваш диспетчер пакетов. Пример для npm:

npm install sweetalert --save

Если вы используете yarn:

yarn add sweetalert

После установки импортируйте swal в компоненте:

import swal from 'sweetalert'

Базовый пример использования

Самый простой вызов swal принимает строку — это будет заголовок уведомления:

import React from 'react'
import swal from 'sweetalert'

function App() {
  const notify = () => swal('Hello There')

  return (
    

      Click Me
    
  )
}

export default App

Нажатие кнопки откроет модальное окно с заголовком «Hello There».

Три позиционных параметра: title, text, icon

swal может принимать три позиционных аргумента: заголовок (title), текст (text) и иконку (icon). Иконка — одно из значений: “success”, “warning”, “error”, “info”.

const notify = () => swal('Hello There', 'Welcome to my Page', 'success')

Пример полного компонента:

import React from 'react'
import swal from 'sweetalert'

function App() {
  const notify = () => swal('Hello There', 'Welcome to my Page', 'success')

  return (
    

      Click Me
    
  )
}

export default App

Использование объекта настроек

Часто удобно передавать объект с именованными опциями — так проще добавлять конфигурацию и читать код:

swal({
  title: 'Hello There',
  text: 'Welcome to my Page',
  icon: 'success',
  button: 'OK'
})

Свойства, которые чаще всего используются:

• title — заголовок уведомления.
• text — основной текст (обычно короткое сообщение).
• icon — тип иконки (success, warning, error, info).
• button — текст кнопки или объект с настройками.
• buttons — массив для нескольких кнопок или false для скрытия.
• content — для рендеринга HTМL-элемента внутри модального окна.
• className — CSS-класс, применяемый к модальному окну.
• closeOnEsc и closeOnClickOutside — логика закрытия.
• timer — авто-закрытие в миллисекундах.

Настройка свойства button

По умолчанию button можно задать как строку или как объект со свойствами:

swal({
  button: {
    text: 'OK',
    value: true,
    visible: true,
    className: '',
    closeModal: true
  }
})

Пояснения:

• text — текст на кнопке.
• value — значение, которое вернётся, когда пользователь нажмёт кнопку (swal возвращает Promise).
• visible — показывать кнопку или нет.
• className — CSS-класс для кнопки.
• closeModal — закрывать ли окно после клика.

Массив для нескольких кнопок:

swal({
  buttons: ['Cancel', 'Ok']
})

Если присвоить buttons: false — кнопки не будут показаны.

Рендеринг HTML-элементов внутри уведомления

swal поддерживает рендеринг HTML-элементов через опцию content. Это удобно для ввода данных или кастомных контролов.

import React from 'react'
import swal from 'sweetalert'

function App() {
  const notify = () => swal({
    content: {
      element: 'input',
      attributes: {
        placeholder: 'First Name',
        type: 'text'
      }
    },
    buttons: 'Sign Up'
  })

  return (
    

      Click Me
    
  )
}

export default App

Этот пример отрендерит поле ввода с placeholder и кнопку регистрации.

Совет: если вы хотите получить значение из поля, используйте Promise, который возвращает swal, и читайте value после закрытия.

Стилизация уведомления

Вы можете задать CSS-класс модального окна через className и стилизовать его в вашем стилевом файле:

swal({
  title: 'Hello There',
  text: 'Welcome to my Page',
  button: false,
  className: 'alert'
})

Пример CSS:

.alert{
  background-color: green;
  font-family: cursive;
  border-radius: 15px;
}

Результат можно увидеть визуально и при тестировании. Помните, что глобальные CSS-классы могут пересекаться с библиотечными стилями — используйте префиксы или CSS-модули.

Закрытие уведомления: Esc, клик вне, таймер

Параметры, влияющие на закрытие:

• closeOnEsc: булево значение. По умолчанию true.
• closeOnClickOutside: булево значение. По умолчанию true.
• timer: число в миллисекундах для автозакрытия.

Примеры:

swal({
  // ...
  closeOnEsc: false
})

swal({
  // ...
  closeOnClickOutside: false
})

swal({
  // ...
  timer: 5000 // 5 секунд
})

Если нужен более сложный сценарий (например, показать индикатор прогресса до автоматического закрытия), реализуйте таймер вручную и контролируйте open/close через состояние компонента.

Работа с Promise и результатами пользователя

swal возвращает Promise, который резолвится после взаимодействия пользователя. Это удобно для последовательной логики:

swal({
  title: 'Are you sure?',
  buttons: ['Cancel', 'Yes']
}).then((value) => {
  if (value) {
    // пользователь подтвердил
  } else {
    // пользователь отменил
  }
})

Используйте async/await для более чистого кода:

const result = await swal({
  title: 'Enter name',
  content: { element: 'input' }
})

if (result) {
  console.log('User typed:', result)
}

Доступность и клавиатура

Важно обеспечить доступность (a11y):

• Следите, чтобы модальное окно получало фокус при открытии.
• Проверяйте, что Esc закрывает окно (если это ожидаемо).
• Используйте aria-атрибуты, если добавляете нестандартный контент.
• При полях ввода — проверяйте, что label или aria-label присутствуют.

Если вы используете кастомные кнопки, убедитесь, что они фокусируемые и имеют понятные подписи для скринридеров.

Когда не стоит использовать SweetAlert

Контрпримеры / ограничения:

• Если вам нужно массовое уведомление (список toast-уведомлений) с очередностью и SLI/SLO — рассмотрите специализированные библиотеки типа React-Toastify.
• Для полностью кастомных модальных потоков (многоступенчатая логика, сложная верстка) лучше использовать собственный модальный компонент, интегрированный с вашим стейтом и aria/role-логикой.
• В SSR-приложениях важно запускать swal только в браузере; серверная попытка обращения к window вызовет ошибку.

Альтернативы

• React-Toastify — для флотающих уведомлений (toasts), удобна при множественных сообщениях.
• Создать собственный компонент на базе headless-ui или Radix для лучшей интеграции с дизайном и доступностью.

Ментальные модели и эвристики

• Модель «одно сообщение — одно действие»: если уведомление требует решения — используйте modal (swal). Если это просто информация — лучше toast.
• Минимизируйте количество обязательных кликов: не ставьте confirm на каждое действие, только на критичные.
• Всегда показывайте полезный текст и, при необходимости, ссылку на документацию/помощь.

Чеклист по ролям

Разработчик:

• Установил пакет и импортировал swal.
• Вызовы swal находятся в блоках, выполняемых только в браузере.
• Обработан Promise результата.

Дизайнер:

• Предоставлены стили и дизайн кнопок.
• Согласованы тексты (microcopy) для кнопок/заголовков.

QA:

• Проверены варианты закрытия (Esc, клик вне, таймер).
• Тесты на доступность (фокус, скринридеры).
• Тесты на разные разрешения экрана.

Шаблон (SOP) для добавления нового уведомления

1. Определить цель уведомления (информировать/подтвердить/ввести данные).
2. Выбрать тип: modal (swal) или toast.
3. Составить тексты: заголовок, основной текст, текст кнопки(ок).
4. Определить поведение: автозакрытие, закрытие по Esc/клику вне.
5. Реализовать вызов swal и обработать Promise.
6. Протестировать на доступность и мобильных устройствах.

Мини-методология в 5 шагах для внедрения

1. Начните с простого: вызов swal(‘Title’).
2. Переведите на объект настроек для читаемости.
3. Добавьте кнопки через buttons или button: { … }.
4. Подключите content для ввода, если нужно.
5. Стилизация: className + CSS-модули.

Decision flowchart (Mermaid)

flowchart TD
  A[Есть ли многократные уведомления?] -->|Да| B[Использовать toast 'React-Toastify']
  A -->|Нет| C[Требуется ли ввод/подтверждение?]
  C -->|Да| D[Использовать swal с content и buttons]
  C -->|Нет| E[Использовать простой swal'title, text, icon']

Критерии приёмки

• Уведомление отображается при ожидаемом действии.
• Кнопка(и) работают и возвращают ожидаемые значения.
• Модальное получает фокус при открытии.
• Закрытие работает по Esc и клик вне (если включено).
• Стили соответствуют дизайн-гайдам проекта.

Примеры расширенного использования

1. Подтверждение удаления с обработкой ответа:

async function confirmDelete() {
  const willDelete = await swal({
    title: 'Delete item?',
    text: 'This action cannot be undone.',
    icon: 'warning',
    buttons: ['Cancel', 'Delete']
  })

  if (willDelete) {
    // вызвать API для удаления
  }
}

2. Модальное с валидацией ввода:

async function askName() {
  const name = await swal({
    title: 'Your name',
    content: { element: 'input', attributes: { placeholder: 'Name' } },
    buttons: true
  })

  if (!name) {
    swal('Name is required', { icon: 'error' })
    return
  }

  // продолжить с введённым именем
}

Тест-кейсы / Приёмочные критерии

• Открыть уведомление: появляется заголовок и текст.
• Нажать кнопку подтверждения: Promise резолвится соответствующим значением.
• Нажать отмену: Promise возвращает false или undefined.
• Проверить timer: уведомление закрывается через указанный интервал.
• Проверить, что при closeOnClickOutside: false клик вне не закрывает модал.

Советы по локализации и i18n

• Храните тексты уведомлений в системе локализации (i18n). Не хардкодьте строки.
• Для кнопки используйте translated labels: button: i18n.t(‘ok’).
• Убедитесь, что длина переведённых строк не ломает верстку.

Безопасность и приватность

• Не вставляйте в уведомления чувствительные данные (пароли, токены).
• Если контент генерируется на основе пользовательского ввода — экранируйте HTML или используйте безопасные способы рендера.

Совместимость и миграция

• SweetAlert — лёгкий пакет; следите за версией. При обновлении проверьте изменения в API — особенно в поведении Promise и опциях.
• Если переходите с другой библиотеки (например, React-Toastify), определите маппинг типов уведомлений и адаптируйте UX.

Когда использовать Toast вместо Modal

• Для краткой информации (успешная операция) — toast.
• Для подтверждений, ошибок с действиями и ввода — modal (swal).

Заключение

SweetAlert — быстрый способ добавить модальные уведомления в приложение React. Он удобен для подтверждений, простых форм и информационных сообщений. Для массовых оповещений или очень кастомного UI рассмотрите альтернативы. Внедряя swal, следуйте чеклисту, тестируйте доступность и локализуйте сообщения.

Важно: проверяйте вызовы на стороне клиента и обрабатывайте Promise результата, чтобы не терять логику приложения.

Короткое резюме:

• Устанавливаем пакет через npm/yarn.
• Используем swal как простую функцию или с объектом настроек.
• Кастомизируем кнопки, содержимое и стили.
• Тестируем доступность, локализацию и поведение закрытия.

Скорректируйте стиль и поведение под UX вашего продукта, и SweetAlert станет простым и гибким инструментом для уведомлений.