﻿---
description: Компонент-обертка над Spinner.
tags: loading
---

# ScreenSpinner \[tag:component]

Компонент-обертка над [`Spinner`](/components/spinner). Используется в случаях, когда требуется заблокировать весь интерфейс до завершения асинхронного процесса.

```jsx
<ScreenSpinner.Container>
  <ScreenSpinner.Loader />
  <ScreenSpinner.SwapIcon />
</ScreenSpinner.Container>
```

```jsx
const [spinner, setSpinner] = React.useState(null);

const showSpinner = () => {
  setSpinner(<ScreenSpinner state="cancelable" mode="overlay" onClick={() => setSpinner(null)} />);
};

return (
  <>
    <Button onClick={showSpinner}>Показать индикатор</Button>
    {spinner}
  </>
);
```

## Подкомпоненты

Чтобы собрать компонент по частям, используйте подкомпоненты. Это даёт гибкость управления отдельными частями и позволяет отвязаться от логики порталов и всплывающих окон (например, при появлении компонента блокируется скролл).

```jsx
<ScreenSpinner.Container>
  <ScreenSpinner.Loader />
  <ScreenSpinner.SwapIcon />
</ScreenSpinner.Container>
```

### ScreenSpinner.Container

Подкомпонент контейнера, которой содержит все части `ScreenSpinner`.

### ScreenSpinner.Loader

Подкомпонент спиннера.

### ScreenSpinner.SwapIcon

Подкомпонент для иконок.

## Внешний вид

Задаётся свойством `mode`.

Помимо стандартного стиля компонента (`mode="shadow"`), есть возможность задать `mode="overlay"`,
для использования индикатора загрузки поверх цветных элементов или фотографий.

```jsx
<ScreenSpinner.Container mode="overlay">
  <ScreenSpinner.Loader />
  <ScreenSpinner.SwapIcon />
</ScreenSpinner.Container>
```

## Состояния

Задаётся свойством `state`.

* `"loading"` — состояние исполняющегося процесса (по умолчанию);
* `"cancelable"` — состояние исполняющегося процесса с возможностью отмены;
* `"done"` — успешное завершение процесса;
* `"error"` — завершение процесса с ошибкой;
* `"custom"` — пользовательский вариант состояния процесса.

Состояние отвечает за иконку, которая будет отрисована. Если вам не подходит ни одно из представленных состояний,
то используйте `state="custom"`. Задать пользовательскую иконку в таком случае можно через свойство [`customIcon`](#custom-icon).

```jsx
<ScreenSpinner.Container>
  <ScreenSpinner.Loader />
  <ScreenSpinner.SwapIcon />
</ScreenSpinner.Container>
<ScreenSpinner.Container state="cancelable">
  <ScreenSpinner.Loader />
  <ScreenSpinner.SwapIcon />
</ScreenSpinner.Container>
<ScreenSpinner.Container state="done">
  <ScreenSpinner.Loader />
  <ScreenSpinner.SwapIcon />
</ScreenSpinner.Container>
<ScreenSpinner.Container state="error">
  <ScreenSpinner.Loader />
  <ScreenSpinner.SwapIcon />
</ScreenSpinner.Container>
<ScreenSpinner.Container state="custom" customIcon={<Icon56CheckCircleOutline />}>
  <ScreenSpinner.Loader />
  <ScreenSpinner.SwapIcon />
</ScreenSpinner.Container>
```

## Сопроводительный текст

Задаётся свойством `label`. Текст располагается под иконкой. Если вы хотите использовать просто иконку
без поясняющего текста, пожалуйста, не забывайте передавать описание иконки для ассистивных технологий через свойство `children`.

## Пользовательские иконки \[#custom-icon]

Задаётся свойством `customIcon` и работает совместно со `state="custom"`, .

```jsx
import { ScreenSpinner } from '@vkontakte/vkui';
import { Icon56CheckCircleOutline } from '@vkontakte/icons';

<ScreenSpinner state="custom" customIcon={<Icon56CheckCircleOutline />} />;
```

## Управление порталами

VKUI использует [порталы](https://react.dev/reference/react-dom/createPortal) для рендеринга `ScreenSpinner`.

Свойство `usePortal` позволяет настраивать порталы:

* `true` — использует свойство `portalRoot`, указанное в компоненте `AppRoot`, если не указано, то `document.body` (по умолчанию);
* `false`/`null` — отключает рендер компонента в отдельном контейнере, он будет рендериться непосредственно по месту определения;

Также можно указать конкретный `DOM`-элемент (полученный, например, через `document.getElementById`)
или ссылку на `DOM`-элемент ([`ref`-объект](https://react.dev/learn/manipulating-the-dom-with-refs)).

## Доступность (a11y) \[#a11y]

Чтобы уведомить пользователей скринридеров о выполнении асинхронного процесса,
проставьте на `SplitLayout` или любом корневом компоненте, в котором выполняется процесс,
метки [`aria-busy`](https://doka.guide/a11y/aria-busy/) и [`aria-live`](https://doka.guide/a11y/aria-live/).

Чтобы заменить текст, который прочитает скринридер, передайте его в `children`.
Он будет скрыт визуально, но останется доступным для ассистивных технологий.
Если вы используете свойство `label`, то передавать `children` не нужно, будет зачитан текст, переданный в `label`.

Свойство `cancelLabel` используется при `state="cancelable"` и делает кнопку отмены доступной для ассистивных технологий.

### disableAnimation

Компонент поддерживает свойство `disableAnimation`, которое позволяет отключить анимацию у спиннера.

## Свойства и методы \[#api]

### ScreenSpinner

| Свойство           | Тип                                                                | По умолчанию                                                | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------------ | ------------------------------------------------------------------ | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cancelLabel`      | `string`                                                           | `-`                                                         | Используется при `state='cancelable'`. Делает доступным для ассистивных технологий.                                                                                                                                                                                                                                                                                                                                                               |
| `customIcon`       | `ReactNode`                                                        | `-`                                                         | Кастомная иконка, работает совместно со `state="custom"`.                                                                                                                                                                                                                                                                                                                                                                                         |
| `disableAnimation` | `boolean`                                                          | `-`                                                         | Отключение анимации.                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `getRootRef`       | `Ref<HTMLSpanElement>`                                             | `-`                                                         |                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `label`            | `ReactNode`                                                        | `-`                                                         | Текст под иконкой.                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `mode`             | `"shadow" \| "overlay"`                                            | `-`                                                         | Внешний вид отображения спиннера.                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `noColor`          | `boolean`                                                          | `-`                                                         | Задать цвет можно будет через свойство color родителя.                                                                                                                                                                                                                                                                                                                                                                                            |
| `ref`              | `Ref<HTMLSpanElement>`                                             | `-`                                                         |                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `state`            | `"done" \| "loading" \| "custom" \| "error" \| "cancelable"`       | `loading`                                                   | Тип отображения спиннера.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `usePortal`        | `boolean \| HTMLElement \| RefObject<HTMLElement \| null> \| null` | `true (использует `document.body` как портал по умолчанию)` | Настройка портала для рендеринга компонента.  `true` - использует `portalRoot` из контекста `AppRoot` (если доступен) или `document.body`; `false` - отключает использование портала; `HTMLElement` - указывает конкретный DOM-элемент для использования в качестве портала; `React.RefObject<HTMLElement \| null>` - ссылка на DOM-элемент для использования в качестве портала; `null` - эквивалентно `false`, отключает использование портала. |
| `visibilityDelay`  | `number`                                                           | `-`                                                         | Задерживает отрисовку элемента на заданное количество миллисекунд.                                                                                                                                                                                                                                                                                                                                                                                |

### ScreenSpinner.Container

| Свойство          | Тип                                                          | По умолчанию | Описание                                                           |
| ----------------- | ------------------------------------------------------------ | ------------ | ------------------------------------------------------------------ |
| `customIcon`      | `ReactNode`                                                  | `-`          | Кастомная иконка, работает совместно со `state="custom"`.          |
| `getRootRef`      | `Ref<HTMLSpanElement>`                                       | `-`          |                                                                    |
| `label`           | `ReactNode`                                                  | `-`          | Текст под иконкой.                                                 |
| `mode`            | `"shadow" \| "overlay"`                                      | `shadow`     | Внешний вид отображения спиннера.                                  |
| `ref`             | `Ref<HTMLSpanElement>`                                       | `-`          |                                                                    |
| `state`           | `"done" \| "loading" \| "custom" \| "error" \| "cancelable"` | `loading`    | Тип отображения спиннера.                                          |
| `visibilityDelay` | `number`                                                     | `-`          | Задерживает отрисовку элемента на заданное количество миллисекунд. |

### ScreenSpinner.Loader

| Свойство           | Тип                    | По умолчанию | Описание                                                           |
| ------------------ | ---------------------- | ------------ | ------------------------------------------------------------------ |
| `disableAnimation` | `boolean`              | `-`          | Отключение анимации.                                               |
| `getRootRef`       | `Ref<HTMLSpanElement>` | `-`          |                                                                    |
| `noColor`          | `boolean`              | `-`          | Задать цвет можно будет через свойство color родителя.             |
| `ref`              | `Ref<HTMLSpanElement>` | `-`          |                                                                    |
| `visibilityDelay`  | `number`               | `-`          | Задерживает отрисовку элемента на заданное количество миллисекунд. |

### ScreenSpinner.SwapIcon

| Свойство      | Тип                | По умолчанию | Описание |
| ------------- | ------------------ | ------------ | -------- |
| `cancelLabel` | `string`           | `-`          |          |
| `getRootRef`  | `Ref<HTMLElement>` | `-`          |          |
| `ref`         | `Ref<HTMLElement>` | `-`          |          |
