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

<Overview group="layout">

# Box [tag:component]

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

</Overview>

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

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

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

{/* @example-description: Базовый пример `Box` как контейнера с токенизированными внутренними отступами. */}
<Playground>
  ```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>
  ```
</Playground>

## Свойства раскладки [#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`);

{/* @example-description: Использование `paddingInline` и `paddingBlock` для независимой настройки отступов по осям. */}
<Playground>
  ```jsx
  <Card Component="div">
    <Box paddingInline="2xl" paddingBlock="2rem">
      <Text>Есть возможность задать отступы со всех сторон</Text>
    </Box>
  </Card>
  ```
</Playground>

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

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

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

{/* @example-description: Ограничение ширины и высоты контейнера через `inlineSize` и `blockSize`. */}
<Playground>
  ```jsx
  <Card Component="div">
    <Box padding="m" inlineSize="100px" blockSize="70px">
      <Icon56GhostOutline />
    </Box>
  </Card>
  ```
</Playground>

### Позиционирование [#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-переменные).

{/* @example-description: Абсолютно позиционированный `Box` для размещения элемента поверх карточки. */}
<Playground>
  ```jsx
  <Card Component="div">
    <Box padding="4xl" maxInlineSize={200}>
      Демонстрация абсолютно-позиционированного блока с иконкой
    </Box>
    <Box position="absolute" insetInlineEnd="m" insetBlockStart="m">
      <Icon16MoreVertical />
    </Box>
  </Card>
  ```
</Playground>

### 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-переменные).

{/* @example-description: Демонстрация `flexBasis` для управления размером элемента внутри `Flex`-контейнера. */}
<Playground>
  ```jsx
  <Flex direction="column">
    <Box>1</Box>
    <Box flexBasis={50}>2</Box>
    <Box>3</Box>
  </Flex>
  ```
</Playground>

### Переполнение [#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` | `-` | Позиционирование элемента. |