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

<Overview group="feedback">
# ScreenSpinner [tag:component]

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

</Overview>

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

{/* @example-description: Базовый `ScreenSpinner` с оверлеем и закрытием в состоянии `cancelable`. */}
<Playground>

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

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

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

</Playground>

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

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

{/* @example-description: Сборка `ScreenSpinner` из подкомпонентов `Container`, `Loader` и `SwapIcon`. */}
<Playground>
  ```jsx
  <ScreenSpinner.Container>
    <ScreenSpinner.Loader />
    <ScreenSpinner.SwapIcon />
  </ScreenSpinner.Container>
  ```
</Playground>

### ScreenSpinner.Container

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

### ScreenSpinner.Loader

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

### ScreenSpinner.SwapIcon

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

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

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

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

{/* @example-description: Вариант `ScreenSpinner` в режиме `overlay` для контрастного фона. */}
<Playground>
  ```jsx
  <ScreenSpinner.Container mode="overlay">
    <ScreenSpinner.Loader />
    <ScreenSpinner.SwapIcon />
  </ScreenSpinner.Container>
  ```
</Playground>

## Состояния

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

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

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

{/* @example-description: Демонстрация состояний `ScreenSpinner`: loading, cancelable, done, error и custom. */}
<Playground>
  ```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>
  ```
</Playground>

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

Задаётся свойством `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 родителя. |
| `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` | Внешний вид отображения спиннера. |
| `state` | `"done" \| "loading" \| "custom" \| "error" \| "cancelable"` | `loading` | Тип отображения спиннера. |
| `visibilityDelay` | `number` | `-` | Задерживает отрисовку элемента на заданное количество миллисекунд. |

### ScreenSpinner.Loader

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

### ScreenSpinner.SwapIcon

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