﻿---
description: Универсальный компонент для создания раскладок с поддержкой отступов, размеров, позиционирования и flex-свойств.
---

# Box \[tag:component]

Компонент построен на базе системы отступов VKUI и предоставляет гибкий способ создания раскладок в приложениях VKUI,
позволяя задавать отступы, размеры, позиционирование и flex-свойства, делая процесс верстки более декларативным и предсказуемым.

## Когда использовать \[#when-to-use]

Компонент `Box` рекомендуется использовать в следующих ситуациях:

* **Создание контейнеров с отступами**: когда нужно добавить внутренние или внешние отступы к любому элементу интерфейса;
* **Управление размерами**: для явного задания ширины, высоты или их ограничений;
* **Абсолютное и относительное позиционирование**: при создании наложений, выпадающих меню или сложных макетов;
* **Flex-элементы**: как потомок flex-контейнера.

```jsx
<Group header={<Header>Заголовок группы</Header>} separator="hide">
  <Box paddingInline="var(--vkui--size_base_padding_horizontal--regular)" paddingBlock="m">
    <Text>
      <strong>Совет:</strong> Используйте Box вместо обычных div-элементов, когда вам нужны
      layout-свойства. Это обеспечит консистентность с дизайн-системой VKUI и упростит поддержку
      кода.
    </Text>
  </Box>
</Group>
```

## Свойства раскладки \[#layout-props]

Компонент `Box` поддерживает обширный набор свойств, объединенных в логические категории:

### Отступы \[#padding-and-margin]

Свойства отступов (свойства с префиксом `padding*` и `margin*`) позволяют управлять пространством вокруг содержимого. Они принимают:

* токены дизайн-системы VKUI (`'2xs', 'xs', 's', 'm', 'l', 'xl', '2xl', '3xl', '4xl'`);
* стандартные CSS-значения (`'inherit'`, `'initial'`, `'unset'`);
* числовые значения (будут преобразованы в пиксели);
* любое валидное строковое значение (`"2rem", "10%"`, CSS-переменные).
* специальное значение `'system'` — работает только внутренних оступов (`padding*`), автоматически устанавливает системные отступы VKUI (эквивалентно использованию `--vkui--size_base_padding_vertical--regular` и `--vkui--size_base_padding_horizontal--regular`);

```jsx
<Card Component="div">
  <Box paddingInline="2xl" paddingBlock="2rem">
    <Text>Есть возможность задать отступы со всех сторон</Text>
  </Box>
</Card>
```

### Размеры \[#size]

Свойства размеров (свойства с постфиксом `*Size`) позволяют управлять шириной и высотой компонента, включая минимальные и максимальные ограничения.
Они принимают:

* стандартные CSS-значения (`'auto'`, `'max-content'`, `'min-content'`, `'fit-content'`, `'inherit'`, `'initial'`, `'unset'`);
* числовые значения в пикселях;
* любое валидное строковое значение (`"200px", "50%"`, CSS-переменные).

```jsx
<Card Component="div">
  <Box padding="m" inlineSize="100px" blockSize="70px">
    <Icon56GhostOutline />
  </Box>
</Card>
```

### Позиционирование \[#position]

Свойства позиционирования позволяют определять схему позиционирования и смещения для компонента Box, обеспечивая статическое, относительное, абсолютное или фиксированное позиционирование с направленными смещениями.

Свойство `position` принимает значения `'static', 'relative', 'absolute', 'fixed'`.

Свойства с префиксом `inset*` принимают:

* токены дизайн-системы VKUI (`'2xs', 'xs', 's', 'm', 'l', 'xl', '2xl', '3xl', '4xl'`);
* стандартные CSS-значения (`'auto'`, `'inherit'`, `'initial'`, `'unset'`);
* числовые значения (будут преобразованы в пиксели);
* любое валидное строковое значение (`"2rem", "10%"`, CSS-переменные).

```jsx
<Card Component="div">
  <Box padding="4xl" maxInlineSize={200}>
    Демонстрация абсолютно-позиционированного блока с иконкой
  </Box>
  <Box position="absolute" insetInlineEnd="m" insetBlockStart="m">
    <Icon16MoreVertical />
  </Box>
</Card>
```

### Flex-свойства \[#flex-props]

Flex-свойства (`flexGrow`, `flexShrink` и `flexBasis`) позволяют управлять поведением компонента внутри `flex`-контейнера.

Данные свойства принимают стандартные CSS-значения (`'inherit'`, `'initial'`, `'unset'`).

Свойства `flexGrow` и `flexShrink` также принимают числовые значения.

`flexBasis` дополнительно принимает:

* `'auto'`, `'max-content'`, `'min-content'`, `'fit-content'`, `'content'`;
* числовые значения (будут преобразованы в пиксели);
* любое валидное строковое значение (`"2rem", "10%"`, CSS-переменные).

```jsx
<Flex direction="column">
  <Box>1</Box>
  <Box flexBasis={50}>2</Box>
  <Box>3</Box>
</Flex>
```

### Переполнение \[#overflow]

Свойства переполнения (с префиксом `overflow*`) позволяют управлять отображением содержимого, которое выходит за границы компонента
Они принимают стандартные CSS-значения переполнения, такие как `'visible'`, `'hidden'`, `'clip'`, `'scroll'`, `'auto'`, `'inherit'`, `'initial'`, `'unset'`.

```jsx
<Box
  style={{
    border: '1px solid var(--vkui--color_separator_primary)',
    padding: '16px',
    margin: '16px 0',
    borderRadius: '8px',
    backgroundColor: 'var(--vkui--color_background_secondary)',
  }}
>
  <strong>📏 Единицы измерения:</strong> Все свойства принимают значения дизайн-системы VKUI
  (`'2xs'`, `'xs'`, `'s'`, `'m'`, `'l'`, `'xl'`, `'2xl'`, `'3xl'`, `'4xl'`), CSS-значения (`'auto'`,
  `'inherit'`, `'initial'`, `'unset'`) или числовые значения в пикселях.
</Box>
```

## Сравнение с другими компонентами \[#comparison]

### Box vs Flex

* **Box** — универсальный контейнер с настраиваемыми отступами, подходит для создания изолированных блоков,
  может быть потомком компонента `Flex`;
* **[`Flex`](/components/flex)** — специализированный контейнер для создания flex-блоков, поддерживает все flex-свойства.

### Box vs div

* **Box** — предоставляет декларативный API на базе дизайн-токенов VKUI;
* **div** — требует ручного управления стилями и классами (через свойства `style`/`class`).

```jsx
<Box padding="m" inlineSize={300} position="relative">
  Контент
</Box>

<div style={{ padding: 'var(--vkui--spacing_m)', width: 300, position: 'relative' }}>Контент</div>
```

### Box vs Spacing

* **Box** — для создания контейнеров с любыми layout-свойствами;
* **[`Spacing`](/components/spacing)** — исключительно для создания отступов между элементами.

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

| Свойство             | Тип                                                                                                   | По умолчанию | Описание                                                                                                                                                                                                                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `alignSelf`          | `AlignSelfProp`                                                                                       | `-`          | Для задания выравнивания, отличного от установленного на родителе, эквивалентно `align-self`.                                                                                                                                                                                          |
| `blockSize`          | `SizeProp`                                                                                            | `-`          | Размер элемента по блочной оси (при горизонтальном направлении письма - высота элемента).                                                                                                                                                                                              |
| `Component`          | `ElementType<any, keyof IntrinsicElements>`                                                           | `-`          |                                                                                                                                                                                                                                                                                        |
| `display`            | `"none" \| "inline" \| "inline-block" \| "block" \| "contents"`                                       | `-`          | Возможность задать css-свойство `display`.                                                                                                                                                                                                                                             |
| `flexBasis`          | `FlexBasisProp`                                                                                       | `-`          | Определяет начальный размер flex-элемента.                                                                                                                                                                                                                                             |
| `flexGrow`           | `FlexGrowProp`                                                                                        | `-`          | Определяет, насколько элемент будет расти относительно остальных flex-элементов.                                                                                                                                                                                                       |
| `flexShrink`         | `FlexShrinkProp`                                                                                      | `-`          | Определяет, насколько элемент будет сжиматься относительно остальных flex-элементов.                                                                                                                                                                                                   |
| `getRootRef`         | `Ref<HTMLElement>`                                                                                    | `-`          |                                                                                                                                                                                                                                                                                        |
| `inlineSize`         | `SizeProp`                                                                                            | `-`          | Размер элемента по строчной оси (при горизонтальном направлении письма - ширина элемента).                                                                                                                                                                                             |
| `inset`              | `InsetProp`                                                                                           | `-`          | Смещение элемента по `top`, `right`, `bottom` и `left` одновременно.                                                                                                                                                                                                                   |
| `insetBlock`         | `InsetProp`                                                                                           | `-`          | Боковое смещение по блочной оси (при горизонтальном направлении письма - свойства `top`/`bottom`).                                                                                                                                                                                     |
| `insetBlockEnd`      | `InsetProp`                                                                                           | `-`          | Смещение конечного отступа по блочной оси (при горизонтальном направлении письма - свойство `bottom`).                                                                                                                                                                                 |
| `insetBlockStart`    | `InsetProp`                                                                                           | `-`          | Смещение начального отступа по блочной оси (при горизонтальном направлении письма - свойство `top`).                                                                                                                                                                                   |
| `insetInline`        | `InsetProp`                                                                                           | `-`          | Боковое смещение по строчной оси (при горизонтальном направлении письма - свойства `left`/`right`).                                                                                                                                                                                    |
| `insetInlineEnd`     | `InsetProp`                                                                                           | `-`          | Смещение конечного отступа по строчной оси (при горизонтальном направлении письма - свойство `right`).                                                                                                                                                                                 |
| `insetInlineStart`   | `InsetProp`                                                                                           | `-`          | Смещение начального отступа по строчной оси (при горизонтальном направлении письма - свойство `left`).                                                                                                                                                                                 |
| `justifySelf`        | `JustifySelfProp`                                                                                     | `-`          | Для задания выравнивания, отличного от установленного на родителе, эквивалентно `justify-self`.                                                                                                                                                                                        |
| `margin`             | `MarginProp`                                                                                          | `-`          | Внешние отступы со всех сторон.                                                                                                                                                                                                                                                        |
| `marginBlock`        | `MarginProp`                                                                                          | `-`          | Внешние отступы по блочной оси.                                                                                                                                                                                                                                                        |
| `marginBlockEnd`     | `MarginProp`                                                                                          | `-`          | Внешний конечный отступ по блочной оси.                                                                                                                                                                                                                                                |
| `marginBlockStart`   | `MarginProp`                                                                                          | `-`          | Внешний начальный отступ по блочной оси.                                                                                                                                                                                                                                               |
| `marginInline`       | `MarginProp`                                                                                          | `-`          | Внешние отступы по строчной оси.                                                                                                                                                                                                                                                       |
| `marginInlineEnd`    | `MarginProp`                                                                                          | `-`          | Внешний конечный отступ по строчной оси.                                                                                                                                                                                                                                               |
| `marginInlineStart`  | `MarginProp`                                                                                          | `-`          | Внешний начальный отступ по строчной оси.                                                                                                                                                                                                                                              |
| `maxBlockSize`       | `SizeProp`                                                                                            | `-`          | Максимальный размер элемента по блочной оси (при горизонтальном направлении письма - высота элемента).                                                                                                                                                                                 |
| `maxInlineSize`      | `CSSGlobalValue \| ((string \| number) & Nothing) \| "max-content" \| "min-content" \| "fit-content"` | `-`          | Максимальный размер элемента по строчной оси (при горизонтальном направлении письма - ширина элемента).                                                                                                                                                                                |
| `minBlockSize`       | `SizeProp`                                                                                            | `-`          | Минимальный размер элемента по блочной оси (при горизонтальном направлении письма - высота элемента).                                                                                                                                                                                  |
| `minInlineSize`      | `CSSGlobalValue \| ((string \| number) & Nothing) \| "max-content" \| "min-content" \| "fit-content"` | `-`          | Минимальный размер элемента по строчной оси (при горизонтальном направлении письма - ширина элемента).                                                                                                                                                                                 |
| `overflow`           | `OverflowValue`                                                                                       | `-`          | Управление переполнением содержимого.                                                                                                                                                                                                                                                  |
| `overflowBlock`      | `OverflowValue`                                                                                       | `-`          | Управление переполнением содержимого по блочной оси (при горизонтальном направлении письма - свойство `overflow-y`).                                                                                                                                                                   |
| `overflowInline`     | `OverflowValue`                                                                                       | `-`          | Управление переполнением содержимого по строчной оси (при горизонтальном направлении письма - свойство `overflow-x`).                                                                                                                                                                  |
| `padding`            | `PaddingProp`                                                                                         | `-`          | Внутренние отступы со всех сторон.                                                                                                                                                                                                                                                     |
| `paddingBlock`       | `PaddingProp`                                                                                         | `-`          | Внутренние отступы по блочной оси.                                                                                                                                                                                                                                                     |
| `paddingBlockEnd`    | `PaddingProp`                                                                                         | `-`          | Внутренний конечный отступ по блочной оси.                                                                                                                                                                                                                                             |
| `paddingBlockStart`  | `PaddingProp`                                                                                         | `-`          | Внутренний начальный отступ по блочной оси.                                                                                                                                                                                                                                            |
| `paddingInline`      | `PaddingProp`                                                                                         | `-`          | Внутренние отступы по строчной оси.                                                                                                                                                                                                                                                    |
| `paddingInlineEnd`   | `PaddingProp`                                                                                         | `-`          | Внутренний конечный отступ по строчной оси.                                                                                                                                                                                                                                            |
| `paddingInlineStart` | `PaddingProp`                                                                                         | `-`          | Внутренний начальный отступ по строчной оси.                                                                                                                                                                                                                                           |
| `position`           | `PositionValue`                                                                                       | `-`          | Позиционирование элемента.                                                                                                                                                                                                                                                             |
| `ref`                | `Ref<HTMLElement>`                                                                                    | `-`          |                                                                                                                                                                                                                                                                                        |
| `render`             | `((props: AllHTMLAttributes<HTMLElement> & Omit<HasRootRef<HTMLElement>, "ref">) => ReactNode)`       | `-`          | Позволяет переопределить рендер компонента, получая собранные свойства (включая вычисленные `className` и `style`). Используется вместо `Component`.  Позволяет гибко объединять несколько компонентов без создания промежуточных DOM-узлов и без ремаунта поддерева на каждый рендер. |
