﻿---
description: Компонент, помогающий сгруппировать несколько полей формы FormItem, расположив их по вертикали или по горизонтали.
tags: forms, layout
---

# FormLayoutGroup \[tag:component]

Компонент, помогающий сгруппировать несколько полей формы (`FormItem`), расположив их по вертикали или по горизонтали.

```jsx
<FormLayoutGroup mode="horizontal">
  <FormItem htmlFor="name" top="Имя">
    <Input id="name" autoComplete="given-name" />
  </FormItem>
  <FormItem htmlFor="lastName" top="Фамилия">
    <Input id="lastName" autoComplete="family-name" />
  </FormItem>
</FormLayoutGroup>
```

## Вариант группировки

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

* `"vertical"` — поля располагаются вертикально друг под другом (по умолчанию);
* `"horizontal"` — поля располагаются горизонтально по линии.

При недостатке места (например, на мобильных) поля формы сжимаются пропорционально, поэтому в `mode="horizontal"` не рекомендуется располагать более трёх `FormItem`.

```jsx
<FormLayoutGroup mode="vertical" segmented>
  <FormItem htmlFor="doctype" top="Документ, удостоверяющий личность">
    <Select
      name="form-layout-group-option-1"
      id="doctype"
      options={['Паспорт гражданина РФ', 'Загранпаспорт'].map((i) => ({
        label: i,
        value: i,
      }))}
      defaultValue={'Загранпаспорт'}
    />
  </FormItem>
  <FormItem htmlFor="docnumber">
    <Input id="docnumber" placeholder="Номер документа" />
  </FormItem>
</FormLayoutGroup>
```

## Удаление группы

> Поддерживается только для `mode="horizontal"`.

Добавить возможность удалять сгруппированные поля можно с помощью свойства `removable`,
которое добавит кнопку удаления, стилизованную под используемую платформу.
Помимо значений `true`/`false`, также принимает значение `"indent"`, которое бывает полезно, когда
не все группы полей можно удалить, но есть необходимость поддерживать выравнивание, добавляя визуальный отступ.

При `removable={true}` можно использовать следующие свойства:

* `removePlaceholder` — текст, который будет зачитан скринридером или показан на платформе iOS
  при взаимодействии с кнопкой удаления (по умолчанию "Удалить");
* `onRemove` — функция-обработчик, которая будет вызвана при нажатии на кнопку удаления.

```jsx
<FormLayoutGroup mode="horizontal" removable onRemove={() => alert('Обработчик удаления')}>
  <FormItem top="Дата начала поездки" htmlFor="start" topMultiline>
    <DateInput id="start" disableCalendar />
  </FormItem>
  <FormItem top="Дата конца поездки" htmlFor="end" topMultiline>
    <DateInput id="end" disableCalendar />
  </FormItem>
</FormLayoutGroup>
```

## Сегментированный вид

Свойство `segmented` позволяет визуально склеить несколько `FormItem`, объединенные в одну `FormLayoutGroup`.
Работает для `mode="vertical"` и `mode="horizontal"`.
Используйте данное свойство, когда хотите показать, что элементы формы логически связаны между собой.
Особое внимание уделите [`a11y`](#a11y) для `FormItem`, которые не определяют свойства `htmlFor` или `top`.

```jsx
<FormLayoutGroup mode="horizontal" segmented>
  <FormItem htmlFor="email" top="E-mail">
    <Input id="email" autoComplete="username" slotProps={{ input: { 'aria-label': 'Имя пользователя' } }} />
  </FormItem>
  <FormItem>
    <Select
      name="form-layout-group-option-2"
      id="form-layout-group-input-2"
      slotProps={{ input: { 'aria-label': 'Имя домена' } }}
      options={['@mail.ru', '@internet.ru', '@bk.ru', '@inbox.ru', '@list.ru'].map((i) => ({
        label: i,
        value: i,
      }))}
      defaultValue="@mail.ru"
    />
  </FormItem>
</FormLayoutGroup>
```

## Тестирование

Для тестирования доступны свойства с постфиксом `*TestId` — они помогают находить нужные части компонента:

* `removeButtonTestId` — `id` кнопки удаления при `removable={true}`;
* `toggleButtonTestId` — `id` кнопки подтверждения удаления (**только для iOS**).

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

* в компоненте используется тэг `fieldset`, что позволяет скринридеру автоматически определить роль [`group`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role);
* рекомендуется предавать в компонент атрибуты `aria-labelledby`, `aria-label` и `aria-describedby` для предоставления
  дополнительной информации об элементе;
* если по дизайну требуется использовать сегментированный режим `segmented={true}`,
  без возможности задать свойства `htmlFor` и `top` у [FormItem](/components/form-item), то стоит добавить скрытый текст,
  используя сервисный компонент [VisuallyHidden](/components/visually-hidden), и связать его с полем формы через `id` и `htmlFor`,
  дублируя текст, заданный в `placeholder`.

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

| Свойство             | Тип                                                                                         | По умолчанию | Описание                                                                                                                            |
| -------------------- | ------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `disabled`           | `boolean`                                                                                   | `-`          | Блокировка взаимодействия с компонентом.                                                                                            |
| `getRootRef`         | `Ref<HTMLDivElement>`                                                                       | `-`          |                                                                                                                                     |
| `mode`               | `"horizontal" \| "vertical"`                                                                | `vertical`   | Направление отображения элементов формы.                                                                                            |
| `noPadding`          | `boolean`                                                                                   | `-`          | Удаляет внешние отступы вокруг компонента.                                                                                          |
| `onRemove`           | `((e: MouseEvent<Element, MouseEvent>, rootEl?: HTMLElement \| null) => void) \| undefined` | `-`          | Обработчик, срабатывающий при нажатии на контрол удаления.                                                                          |
| `ref`                | `Ref<HTMLDivElement>`                                                                       | `-`          |                                                                                                                                     |
| `removable`          | `boolean \| "indent"`                                                                       | `-`          | Только для режима horizontal. Дает возможность удалить всю группу `FormItem`.  Режим `indent` предназначен для визуального отступа. |
| `removeButtonTestId` | `string`                                                                                    | `-`          | Передает атрибут `data-testid` для кнопки удаления.                                                                                 |
| `removePlaceholder`  | `ReactNode`                                                                                 | `Удалить`    | Текст кнопки удаления ячейки. Визуально скрыт везде, кроме iOS. На iOS появляется в выезжающей кнопке для удаления ячейки.          |
| `segmented`          | `boolean`                                                                                   | `-`          | Дает возможность склеить несколько `FormItem`.                                                                                      |
| `toggleButtonTestId` | `string`                                                                                    | `-`          | Передает атрибут `data-testid` для кнопки, которая активирует кнопку удаления (iOS only).                                           |
