---
description: Базовый компонент для создания модальных карточек с гибким содержимым.
---

<Overview group="modals">

# ModalCardBase [tag:component]

Базовый компонент для создания модальных карточек с гибким содержимым.
Используется как основа для `ModalCard`.

Связанные компоненты:

- [`ModalCard`](/components/modal-card)

</Overview>

{/* @example-description: Базовый `ModalCardBase` с иконкой, описанием и группой кнопок действий. */}
<Playground>
  ```jsx
  <ModalCardBase
    icon={<Icon56MoneyTransferOutline />}
    title="Подтверждение перевода"
    description="Сумма: 5 000 ₽ · Получатель: Иван Петров"
    actions={
      <ButtonGroup mode="horizontal" gap="s" stretched>
        <Button size="l" mode="primary" stretched>
          Подтвердить
        </Button>
        <Button size="l" mode="secondary" stretched>
          Отмена
        </Button>
      </ButtonGroup>
    }
    dismissLabel="Закрыть"
  />
  ```
</Playground>

## Ключевые элементы

## Визуальные компоненты

### Иконка

Задаётся свойством `icon`. Рекомендуется использовать:

- контурные иконки размером `56px` (`<Icon56...Outline />`);
- аватары размером `72px`(`<Avatar size={72} src={...} />`).

### Текстовые блоки

- Свойство `title` отвечает за основной заголовок.
- Свойство `description` отвечает за поясняющий текст.

## Интерактивные элементы

- Свойство `actions` используется для задания группы кнопок (`Button`).
- Свойство `outsideButtons` используется для дополнительных элементов управления (_только для десктопа_).
  Рекомендуется использовать компонент [`ModalOutsideButton`](/components/modal-outside-button)

## Блокировка закрытия

Свойство `preventClose` отключает закрытие по нажатию, свайпу или клавише `ESC`.

## Размеры и адаптивность

Компонент автоматически адаптируется под все устройства, но с помощью свойство `size` можно определить
максимальную ширину для десктопа (по умолчанию `450px`).

## Кнопка для закрытия

Через свойство `dismissButtonMode=inside|outside|none` можно задать вид кнопки закрытия.
Согласно нашим дизайн-гайдам, `dismissButtonMode=outside` отображается только для `compact`-режима (десктопная и планшетные версии).
Для iOS всегда будет применяться `dismissButtonMode=inside` в `regular`-режиме (мобильная версия).

> Обратите внимание, что свойство `dismissButtonMode=none`, которое позволяет скрыть крестик, или свойство `preventClose`,
> отключающее возможность закрыть модалку стандартными способами,
> негативно влияет на пользовательский опыт, используйте эти свойства только если точно знаете, что делаете.

## Отступы между контентом и кнопками действий (`actions`)

По умолчанию верхний отступ от кнопок действий `actions` равняется `16px`. Согласно дизайн-системе отступ может быть
больше в зависимости от того какие данные отображаются внутри `ModalCardBase`.
Если необходимо увеличить отступ, то передавайте в `actions` компонент [Spacing](/components/spacing).

{/* @example-description: `ModalCardBase` с ручной настройкой отступа перед блоком `actions` через `Spacing`. */}
<Playground>
  ```jsx
  <ModalCardBase
    dismissButtonMode="inside"
    dismissLabel="Закрыть"
    title="Десктопная и планшетная версии с крестиком внутри"
    description="Сверху будет безопасный отступ до иконки"
    actions={
      <React.Fragment>
        <Spacing size={16} />
        <Button size="l" mode="primary" stretched>
          Некая кнопка
        </Button>
      </React.Fragment>
    }
  />
  ```
</Playground>

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

Если `ModalCardBase` является модальным окном, то ему, или его родителю,
надо добавить аттрибуты `role="dialog"` и `aria-modal="true"`, чтобы пользователи клавиатуры или скринридера
не могли выйти за пределы модального окна пока оно не закрылось.

Также у `ModalCardBase` обязательно должно быть имя — краткое название. Благодаря этому пользователи вспомогательных
технологий знают, что это за элемент и какое у него содержимое.

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

- используя свойство `title`. Тогда следует также передать `aria-labelledby` и `titleId` так,
  чтобы они имели одинаковые значения, чтобы можно было связать `title` и модальное окно.
  Мы не делаем этого автоматически потому что не можем быть уверены на каком уровне будут заданы `role` и `aria-modal`;
- используя свойство `aria-label`;
- используя свойство `aria-labelledby`. Если не использовать свойство `title`, то можно передать `id` любого контейнера
  с текстом;

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

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

| Свойство | Тип | По умолчанию | Описание |
| --- | --- | --- | --- |
| `actions` | `ReactNode` | `-` | Кнопки-действия. Принимает [`Button`](https://vkui.io/components/button) с параметрами:  - `size="l" mode="primary" stretched` - `size="l" mode="secondary" stretched`.  Для набора кнопок используйте [`ButtonGroup`](https://vkui.io/components/button-group) с параметрами:  - `gap="s" mode="horizontal" stretched` - `gap="m" mode="vertical" stretched`. |
| `description` | `ReactNode` | `-` | Описание. |
| `descriptionComponent` | `ElementType<any, keyof IntrinsicElements>` | `span` | Позволяет поменять тег используемый для описания. |
| `dismissButtonMode` | `"none" \| "inside" \| "outside"` | `outside` | Расположение кнопки закрытия (внутри и вне `popout'a`).  Доступно только в `compact`-режиме.  На `iOS` в `regular`-режиме всегда включен `inside`.  ⚠️ ВНИМАНИЕ: использование `none` скрывает крестик, это негативно сказывается на пользовательском опыте. |
| `dismissLabel` | `string` | `Закрыть` | Текст кнопки закрытия. Делает ее доступной для ассистивных технологий. |
| `getRootRef` | `Ref<HTMLDivElement>` | `-` |  |
| `icon` | `ReactNode` | `-` | Иконка.  Может быть компонентом иконки, например, `<Icon56MoneyTransferOutline />`, или `<Avatar size={72} src="" />`. |
| `modalDismissButtonTestId` | `string` | `-` | Передает атрибут `data-testid` для кнопки закрытия. |
| `onClose` | `VoidFunction` | `-` | Обработчик закрытия модального окна. |
| `outsideButtons` | `ReactNode` | `-` | Управляющие элементы под кнопкой закрытия.  Доступно только в `compact`-режиме. Рекомендуется размещать иконки размера 20, обернутые в ModalOutsideButton. |
| `preventClose` | `boolean` | `-` | Позволяет отключить возможность закрытия модальной страницы (смахивание, клавиша `ESC`, нажатие на подложку).  ⚠️ ВНИМАНИЕ: использование этой опции негативно сказывается на пользовательском опыте. |
| `size` | `number` | `-` | Задаёт контенту максимальную ширину для десктопной версии. |
| `title` | `ReactNode` | `-` | Заголовок карточки. |
| `titleComponent` | `ElementType<any, keyof IntrinsicElements>` | `span` | Позволяет поменять тег используемый для заголовка. |
| `titleId` | `string` | `-` | Позволяет задать id для заголовка. Используется, чтобы связать модальное окно и title через aria-labelledby, тем самым задав модальному окну имя через title. |