﻿---
description: Компонент реализующий модальное окно.
---

# ModalPage \[tag:component]

Компонент реализующий модальное окно. Позволяет показать дополнительный контент,
удерживая пользователя в текущем контексте страницы/приложения.

```jsx
<PlatformProvider value="vkcom">
  <ModalPage
    open={open}
    onClose={() => {}}
    disableModalOverlay
    header={
      <ModalPageHeader
        before={
          <PanelHeaderBack label="Назад" />
        }
      >
        Информация о пользователе
      </ModalPageHeader>
    }
  >
    <Group>
      <Cell>
        <InfoRow header="Дата рождения">5 ноября 1994</InfoRow>
      </Cell>
      <Cell>
        <InfoRow header="Родной город">Санкт-Петербург</InfoRow>
      </Cell>
      <Cell>
        <InfoRow header="Место работы">Команда ВКонтакте</InfoRow>
      </Cell>
    </Group>
  </ModalPage>
</PlatformProvider>
```

```jsx
const [open, setOpen] = React.useState(false);

return (
  <>
    <Button onClick={() => setOpen(true)}>Открыть</Button>
    <ModalPage
      open={open}
      onClose={() => setOpen(false)}
      header={
        <ModalPageHeader
          before={
            <PanelHeaderBack label="Назад" onClick={() => setOpen(false)} />
          }
        >
          Информация о пользователе
        </ModalPageHeader>
      }
    >
      <Group>
        <Cell>
          <InfoRow header="Дата рождения">5 ноября 1994</InfoRow>
        </Cell>
        <Cell>
          <InfoRow header="Родной город">Санкт-Петербург</InfoRow>
        </Cell>
        <Cell>
          <InfoRow header="Место работы">Команда ВКонтакте</InfoRow>
        </Cell>
      </Group>
    </ModalPage>
  </>
);
```

## Область применения

* Формы для редактирования.
* Детали профиля пользователя.
* Разделы настроек, которые должны удерживать пользователя в текущем контексте приложения.

## Анатомия

`ModalPage` состоит из композиции нескольких компонентов.

**Опциональные компоненты, передающиеся пользователем**:

* [ModalPageHeader](/components/modal-page-header) – передаётся через параметр `header`;

**Обязательные компоненты, задающиеся библиотекой**:

* `ModalOutlet` – обёртка с фиксированной позицией для перекрытия других элементов в **DOM**;
* `ModalOverlay` – интерактивный задний фон;
* `ModalPageInternal` – инкапсулирует в себе всю логику поведения;
* `ModalPageContent` – оборачивает переданный `children` в [CustomScrollView](/components/custom-scroll-view).

## Поведение

Параметр `open` задает состояние показа/скрытия `ModalPage`. По умолчанию компонент скрыт.

При состоянии `open={false}` компонент размонтируется из DOM. Чтобы отключить это поведение, необходимо задать параметр
`keepMounted`.

Смена состояния сопровождается анимацией содержимого `ModalPage`, а также `ModalOverlay`. За сменой состояния можно следить
через события:

* `onOpen`
* `onOpened`
* `onClose` – передаёт в аргумент причину закрытия (см. описание в таблице с API)
* `onClosed`

Отличие `onOpened`/`onClosed` от `onOpen`/`onClose` в том, что они вызываются после завершения анимации.

Далее поведение зависит от разрешения экрана.

### Настольный режим

При разрешении `>= 768px` компонент `ModalPage` имеет вид **диалогового окна**.

При `open={true}`:

* параметр `size` будет ограничивать максимальную ширину окна;
* навигация через `Tab` и `Shift` + `Tab` будет зациклена на содержимом `ModalPage`.

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

По умолчанию, пользователь может закрыть **диалоговое окно** с помощью:

* нажатия на кнопку закрытия, что вызовет событие `onClose` с аргументом `click-close-button`;
* нажатия на `ModalOverlay`, что вызовет событие `onClose` с аргументом `click-overlay`;
* нажатия на `Esc`, что вызовет событие `onClose` с аргументом `escape-key`.

### Мобильный режим

При разрешении `<= 767px` компонент `ModalPage` имеет вид панели, выдвигающейся снизу вверх (далее **bottom sheet**).

> При передаче `hasCustomPanelHeaderAfter` в [ConfigProvider](/components/config-provider) модальная страница
> сверху будет смещена на высоту [PanelHeader](/components/panel-header), чтобы кнопка закрытия модальной
> страницы не перекрывалась пользовательским "плавающим" элементом (например, панелью управления
> webview).

При `open={true}` навигация через `Tab` и `Shift` + `Tab` будет зациклена на содержимом `ModalPage` (допустимо, т.к. к устройству
может быть подключена клавиатура).

По умолчанию, пользователь может закрыть **bottom sheet** с помощью:

* нажатия на `ModalOverlay`, что вызовет событие `onClose` с аргументом `click-overlay`;
* нажатия на `Esc`, что вызовет событие `onClose` с аргументом `escape-key` (допустимо, т.к. к устройству может быть подключена
  клавиатура);
* определенного взаимодействие через тач или указатель мыши, что вызовет событие `onClose` с аргументом `swipe-down`
  (см. **Взаимодействие через тач или указатель мыши**)

#### Взаимодействие через тач или указатель мыши

> `<ConfigProvider platform="vkcom" />`
>
> При `platform === 'vkcom` описанный в этом разделе функционал полностью игнорируется, т.к. по историческим причинам
> `platform="vkcom"` форсирует условие, что сейчас используется десктопный режим. Высота **bottom sheet** будет определяться за счёт
> контента.

Для **bottom sheet** можно задавать на какой процент высоты экрана изначально должна открываться панель – этот процент задаётся
через параметр `settlingHeight`. Минимальное значение `25`, а максимальное `100`. По умолчанию используется `50`.

От `settlingHeight` зависит дальнейшее поведение **bottom sheet**:

* при `settlingHeight <= 90` у **bottom sheet** появляется возможность через перетаскивание раскрывать высоту до `100` и схлопывать
  обратно до переданного `settlingHeight`;
* при `settlingHeight > 90` значение приводится к `100` и, соответственно, **bottom sheet** всегда раскрывается на `100`.

Если необходимо, чтобы высота **bottom sheet** зависела от его контента, то стоит использовать параметр `dynamicContentHeight`,
вместо `settlingHeight`.

В обеих случаях перетаскивание **bottom sheet** изменяет прозрачность `ModalOverlay` – при перетаскивание вниз фон становится
светлее. При `settlingHeight` процент прозрачности высчитывается относительно переданного значения в `settlingHeight`.

Пользователь через перетаскивание может вызвать закрытие **bottom sheet** по следующим условиям:

* `onClose('swipe-down')` вызовется сразу же, если **bottom sheet** достиг высоты `0`, независимо закончил ли пользователь
  взаимодействие с ним или нет;

* `onClose('swipe-down')` вызовется, если после окончания взаимодействия с **bottom sheet** его высота будет:

  * *при `settlingHeight`*: меньше половины переданного значения в `settlingHeight` (пример, если `settlingHeight={50}`, то условием
    закрытие будет
    `height < 50 / 2`);
  * *при `dynamicContentHeight`*: меньше половины контента;

* `onClose('swipe-down')` вызовется при сильном смахивании вниз;
  * *при `settlingHeight`*: добавляется условии, что **bottom sheet** должен находится на высоте равной переданному в
    `settlingHeight`;

При следующих условиях возможность перетаскивания замораживается, чтобы не блокировать пользователя:

* при условии `disableContentPanningGesture={false}`, есть взаимодействие с контентом `ModalPageContent` при `scrollTop !== 0`;
* есть взаимодействие с горизонтальным скроллом;
* есть взаимодействие с текстовым полем;
* есть взаимодействие с выделенным текстом;
* есть взаимодействие с элементом вызвавшим `event.stopPropagation()` на `onTouchStart` или `onMouseDown`.
* есть взаимодействие с элементом с **data**-атрибутом `data-vkui-block-sheet-behavior`
  (в частности, используется при `disableContentPanningGesture={true}`);

## Хук `useModalManager`

Для более удобного управления модальными окнами вы можете использовать менеджер в виде хука [`useModalManager`](/components/use-modal-manager)

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

`ModalPage` является модальным окном (`role="dialog"`), а значит у него обязательно должно быть имя — его краткое название. Благодаря этому пользователи вспомогательных технологий знают, что это за элемент и какое у него содержимое.

Задать имя можно с помощью следующих способов:

* используя свойство `title`;
* используя свойство `aria-label`;
* используя свойство `aria-labelledby`;
* используя внутри компонент [ModalPageHeader](/components/modal-page-header). Этот компонент сам свяжется с `ModalPage` через контекст c помощью `aria-labelledby`.

## FAQ

### Как поменять максимальную ширину контента?

Используйте параметр `size`.

### Как задать фиксированную высоту контента?

Используйте параметр `height`. Высоту можно задать как числом (`height={300}`) так и в процентах (`height={'80%'}`).

> В мобильной версии на высоту по умолчанию также влияет значение `settlingHeight`. Чтобы отключить его влияние, достаточно задать
> `settlingHeight={100}`.

### Как правильно применять параметр `autoFocus`?

К сожалению, из-за особенностей **React**, `autoFocus` ломает CSS анимацию.

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

```jsx
const [open, setOpen] = React.useState(false);

const inputRef = React.useRef(null);

const handleOpen = React.useCallback(() => {
  if (inputRef.current) {
    inputRef.current.focus();
  }
}, []);

return (
  <>
    <Button onClick={() => setOpen(true)}>Открыть</Button>
    <ModalPage
      id="modal-with-auto-focus"
      open={open}
      onOpened={handleOpen}
      onClose={() => setOpen(false)}
    >
      <Box padding="system">
        <Input getRootRef={inputRef} />
      </Box>
    </ModalPage>
  </>
);
```

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

| Свойство                       | Тип                                                                                                              | По умолчанию | Описание                                                                                                                                                                                                                                                                                       |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `disableCloseAnimation`        | `boolean`                                                                                                        | `-`          | Отключает анимацию закрытия модалки.                                                                                                                                                                                                                                                           |
| `disableContentPanningGesture` | `boolean`                                                                                                        | `-`          | Отключает раскрытие и закрытие панели в мобильном виде.                                                                                                                                                                                                                                        |
| `disableFocusTrap`             | `boolean`                                                                                                        | `-`          | Позволяет отключить захват фокуса.  Нужно использовать, когда поверх одной модалки открывается другая, чтобы два `FocusTrap` не конфликтовали.                                                                                                                                                 |
| `disableModalOverlay`          | `boolean`                                                                                                        | `-`          | Отключает отображение и взаимодействие с фоном модалки.                                                                                                                                                                                                                                        |
| `disableOpenAnimation`         | `boolean`                                                                                                        | `-`          | Отключает анимацию открытия модалки.                                                                                                                                                                                                                                                           |
| `dynamicContentHeight`         | `boolean`                                                                                                        | `-`          | Если высота контента в модальной странице может поменяться, нужно установить это свойство.                                                                                                                                                                                                     |
| `footer`                       | `ReactNode`                                                                                                      | `-`          | Подвал модальной страницы.  `tsx <>   <Separator />   <Box padding="system">     <Button>Кнопка</Button>   </Box> </> `                                                                                                                                                                        |
| `getModalContentRef`           | `Ref<HTMLDivElement>`                                                                                            | `-`          | Возвращает DOM-элемент содержимого модального окна.                                                                                                                                                                                                                                            |
| `getRootRef`                   | `Ref<HTMLDivElement>`                                                                                            | `-`          |                                                                                                                                                                                                                                                                                                |
| `header`                       | `ReactNode`                                                                                                      | `-`          | Шапка модальной страницы, `<ModalPageHeader />`.                                                                                                                                                                                                                                               |
| `height`                       | `string \| number`                                                                                               | `-`          | Задаёт модальному окну фиксированную высоту. Можно передать числовое значение в пикселях, а можно строкой, в том числе и в процентах "50%". В мобильной версии 'settlingHeight' будет считаться относительно заданного height.                                                                 |
| `hideCloseButton`              | `boolean`                                                                                                        | `-`          | Скрывает кнопку закрытия (актуально для iOS, так как можно отрисовать кнопку закрытия внутри модалки).                                                                                                                                                                                         |
| `id`                           | `string`                                                                                                         | `-`          |                                                                                                                                                                                                                                                                                                |
| `keepMounted`                  | `boolean`                                                                                                        | `false`      | Сохранять ли компонент в DOM при `open={false}`.                                                                                                                                                                                                                                               |
| `modalContentTestId`           | `string`                                                                                                         | `-`          | `data-testid` для содержимого модального окна.                                                                                                                                                                                                                                                 |
| `modalDismissButtonLabel`      | `string`                                                                                                         | `-`          | Текст для скринридера.                                                                                                                                                                                                                                                                         |
| `modalDismissButtonTestId`     | `string`                                                                                                         | `-`          | `data-testid` для кнопки закрытия.                                                                                                                                                                                                                                                             |
| `modalOverlayTestId`           | `string`                                                                                                         | `-`          | `data-testid` для оверлея.                                                                                                                                                                                                                                                                     |
| `nav`                          | `string`                                                                                                         | `-`          | Уникальный идентификатор навигационного элемента (вместо id)                                                                                                                                                                                                                                   |
| `noFocusToDialog`              | `boolean`                                                                                                        | `-`          | Отключает фокус на интерактивный элемент после открытия модалки.  > Важно установить фокус после открытия в любое место модалки используя событие `onOpened`, иначе не будет работать закрытие по нажатию `Esc`.                                                                               |
| `onClose`                      | `((reason: ModalPageCloseReason, event?: UIEvent<HTMLElement, UIEvent>) => void) \| undefined`                   | `-`          | Будет вызвано при начале закрытия модалки.                                                                                                                                                                                                                                                     |
| `onClosed`                     | `VoidFunction`                                                                                                   | `-`          | Будет вызвано при окончательном закрытии модалки.                                                                                                                                                                                                                                              |
| `onOpen`                       | `VoidFunction`                                                                                                   | `-`          | Будет вызвано при начале открытия модалки.                                                                                                                                                                                                                                                     |
| `onOpened`                     | `VoidFunction`                                                                                                   | `-`          | Будет вызвано при окончательном открытии модалки.                                                                                                                                                                                                                                              |
| `open`                         | `boolean`                                                                                                        | `false`      | Состояние видимости.                                                                                                                                                                                                                                                                           |
| `outsideButtons`               | `ReactNode`                                                                                                      | `-`          | Управляющие элементы под кнопкой закрытия.  Доступно только в `compact`-режиме. Рекомендуется размещать иконки размера 20, обернутые в ModalOutsideButton.                                                                                                                                     |
| `preventClose`                 | `boolean`                                                                                                        | `-`          | Позволяет отключить возможность закрытия модальной страницы (смахивание, клавиша `ESC`, нажатие на подложку).  ⚠️ ВНИМАНИЕ: использование этой опции негативно сказывается на пользовательском опыте.                                                                                          |
| `ref`                          | `Ref<HTMLDivElement>`                                                                                            | `-`          |                                                                                                                                                                                                                                                                                                |
| `restoreFocus`                 | `boolean \| (() => boolean \| HTMLElement)`                                                                      | `true`       | Управление поведением возврата фокуса при закрытии всплывающего окна.                                                                                                                                                                                                                          |
| `settlingHeight`               | `number`                                                                                                         | `50`         | Процент, на который изначально будет открыта модальная страница.  > ⚠️ Следует использовать следующие значения: `25`, `50`, `75`, `100`. > При передаче `< 25` значение приведётся к `25`, при передаче `> 75` значение приведётся к `75`.  Игнорируется при включении `dynamicContentHeight`. |
| `size`                         | `LiteralUnion<"s" \| "auto" \| "m" \| "l" \| "max-content" \| "min-content" \| "fit-content", string \| number>` | `s`          | Задаёт контенту максимальную ширину на десктопе.                                                                                                                                                                                                                                               |
| `style`                        | `Omit<CSSProperties, "height" \| "maxHeight" \| "maxWidth">`                                                     | `-`          | Дополнительные стили.                                                                                                                                                                                                                                                                          |
