﻿---
description: Обязательный компонент, в который нужно обернуть всё приложение.
  В нём инкапсулирована логика режимов встраивания, управления прокруткой, безопасными отступами и порталами.
tags: provider
---

# AppRoot \[tag:component]

[Обязательный компонент](/overview/install#step4), в который нужно обернуть всё приложение. В нём инкапсулирована логика:

* режимов встраивания,
* управления прокруткой,
* безопасными отступами,
* и порталами.

## Режимы встраивания

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

* `"full"` — ваше приложение полностью реализовано с помощью VKUI;
* `"embedded"` — ваше приложение реализовано в виде блока, встроенного в основное приложение
  (например, Марусю или базовое приложение ВКонтакте);
* `"partial"` — ваше приложение реализовано с помощью сторонних решений и использует некоторые компоненты библиотеки VKUI.

В чём главные особенности перечисленных режимов и какой режим выбрать?

### Full

Этот режим используется по умолчанию и позволяет VKUI полностью контролировать страницы вашего приложения.
Предполагается, что `root`-элемент (точка монтирования приложения) приложения находится непосредственно внутри `<body>`.
VKUI добавит свои классы на `html`-элемент и на `root`-элемент.
Рекомендуем использовать его для `standalone`-проектов или при [интеграции с платформой VK Mini Apps](/integrations/vk-mini-apps).

### Embedded

В этом режиме VKUI подключается не на всю страницу приложения, а только к определённому контейнеру.
В отличие от `full` режима, VKUI добавит свои классы только на корневой контейнер (`.vkui__root` и `.vkui__root--embedded`).

По умолчанию, в режиме `embedded` система координат элементов с `position: fixed` переносится на свой контейнер через `transform: translate3d(0, 0, 0)`.
Это поведение можно отключить с помощью свойства `disableParentTransformForPositionFixedElements`.

### Partial

Данный режим подходит для случаев, когда вам нужно сверстать небольшой блок, а не страницу целиком. В `partial` режиме не подразумевается использование компонентов из раздела `Layout`. VKUI не добавляет никаких классов на `html` или корневой элемент.

## Визуальное оформление

Свойство `layoutMode` глобально задаёт тип оформления макета для компонентов [`Panel`](/components/panel) и [`Group`](/components/group).

* `"card"` — карточный дизайн с тенями и скруглениями;
* `"plain"` — плоский дизайн без теней и скруглений.

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

VKUI использует [порталы](https://react.dev/reference/react-dom/createPortal) для рендеринга всплывающих элементов (модальные окна, тултипы и т.д.).
По умолчанию, они рендерятся в `document.body`.

С помощью свойства `portalRoot` можно переопределить элемент, в котором будут рендериться всплывающие элементы.
Можно указать конкретный `DOM`-элемент (полученный, например, через `document.getElementById`) или ссылку на `DOM`-элемент (`ref`-объект).

С помощью свойства `disablePortal` можно отключить рендер всплывающих элементов в отдельном контейнере -
они будут рендериться непосредственно по месту определения.

## Управление полосой прокрутки

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

* `"global"` — VKUI-приложение скроллится вместе со страницей;
* `"contain"` — VKUI-приложение живет в отдельной зоне и скроллится независимо внутри `AppRoot` (например, в модалке).

В режимах `full` и `embedded` VKUI управляет полосой прокрутки приложения - например, блокирует скролл при поднятии
модального окна или запоминает положение скролла при переходе между панелями (`Panel`).

В случае `scroll="global"` положение полосы прокрутки рассчитывается относительно глобальных `window/document` страницы.
В случае `scroll="contain"` положение полосы прокрутки рассчитывается относительно выбранного корневого элемента,
это может быть полезно при использовании `mode="embedded"`.

## Безопасные отступы (safe-area-inset-\*) \[#safe-area-insets]

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

Иногда приложению может быть доступна не вся область экрана (например, смартфоны с "чёлкой").
Чтобы части приложения не перекрывали нативные элементы, мы используем стандартные `safe-area-inset-*`.
Подробнее можно ознакомиться в [документации](https://developer.mozilla.org/en-US/docs/Web/CSS/env#safe-area-inset-top).

Если вы разрабатываете мини-приложение или встраиваетесь в интерфейс, который требует использования специфичных отступов, то
используйте свойство `safeAreaInsets`, которое позволяет переопределять значения по умолчанию:

```jsx
const customSafeAreaInsets = {
  top?: number;
  right?: number;
  bottom?: number;
  left?: number;
}

// Переопределяем стандартные отступы
<AppRoot safeAreaInsets={customSafeAreaInsets}>
  <App />
</AppRoot>
```

Вы можете переопределить только часть отступов (например, только `bottom` или `top`), остальные значения будут использовать
заданные по умолчанию отступы.

## Выделение текста

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

Поскольку VKUI мимикрирует под мобильные платформы, мы по умолчанию запрещаем выделять текст в приложениях, запущенных в `webview`.
Для более гибкой настройки поведения используйте следующие значения:

* `"enabled-with-pointer"` – разрешается выделять текст, если устройство ввода типа `pointer` (например, мышь), в остальных случаях запрещается;
* `"disabled"` – запрещается выделять текст;
* `"enabled"` – разрешается выделять текст.

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

| Свойство                                         | Тип                                                     | По умолчанию | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------------------------------------ | ------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `disableParentTransformForPositionFixedElements` | `boolean`                                               | `-`          | По умолчанию, mode="embedded" переносит систему координат элементов с `position: fixed` на свой контейнер через `transform: translate3d(0, 0, 0)`.  Это поведение можно отключить с помощью этого параметра.                                                                                                                                                                                                                                                                                   |
| `disablePortal`                                  | `boolean`                                               | `false`      | Отключает рендер всплывающих компонентов в отдельном контейнере.                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `disableSettingVKUIClassesInRuntime`             | `boolean`                                               | `-`          | По умолчанию в режиме `mode="full"` VKUI в рантайме выставляет: - класс .vkui на html элемент - класс .vkui\_\_root на элемент-контейнер, в который монтируется VKUI С помощью этой опции такое поведение можно отключить.  Для корректной работы SSR рекоммендуется выставлять эти классы самостоятельно и отключить это поведение.                                                                                                                                                           |
| `layout`                                         | `AppRootLayout`                                         | `-`          | **Deprecated**: Используйте `layoutMode`.                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `layoutMode`                                     | `AppRootLayout`                                         | `-`          | Глобально задаёт тип оформления макета для компонентов [Panel](https://vkui.io/components/panel) и [Group](https://vkui.io/components/group).                                                                                                                                                                                                                                                                                                                                                  |
| `mode`                                           | `AppRootMode`                                           | `full`       | Режим встраивания.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `portalRoot`                                     | `HTMLElement \| RefObject<HTMLElement \| null> \| null` | `-`          | Кастомный root-элемент портала.                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `safeAreaInsets`                                 | `SafeAreaInsets`                                        | `-`          | См. Документацию [mdn web docs \| env#values](https://developer.mozilla.org/en-US/docs/Web/CSS/env#values).                                                                                                                                                                                                                                                                                                                                                                                    |
| `scroll`                                         | `AppRootScroll`                                         | `global`     | - `global` (по умолчанию) — VKUI-приложение скроллится вместе со страницей. - `contain` — VKUI-приложение живет в отдельной зоне и скроллится независимо внутри `AppRoot` (например, в модалке).  Полезно при использовании `mode="embedded"`.                                                                                                                                                                                                                                                 |
| `userSelectMode`                                 | `AppRootUserSelectMode`                                 | `-`          | Задаёт режим выбора текста (выделения текста) для всего приложения. По умолчанию, если режим не задан, запрещает выбор текста в приложениях, запущенных в webview (по значению свойства `isWebView` из [ConfigProvider](https://vkui.io/components/config-provider)).  - `enabled-with-pointer` – разрешает выбор текста, если устройство ввода типа `pointer` (например, `мышь`), в остальных случаях запрещает; - `disabled` – запрещает выбор текста; - `enabled` – разрешает выбор текста. |
