﻿---
description: Компонент для создания элементов форм с поддержкой заголовка, подсказки и статуса валидации.
---

# FormItem \[tag:component]

Компонент для создания элементов форм с поддержкой заголовка, подсказки и статуса валидации.
Позволяет создавать структурированные и доступные формы с единым стилем оформления.
Рекомендуется оборачивать в компонент все поля, кроме [`Radio`](/components/radio) и [`Checkbox`](/components/checkbox), если для
них в дизайне не предусмотрены заголовки и иные описательные элементы.

```jsx
const id = React.useId();

return (
  <FormItem htmlFor={id} top="E-mail">
    <Input type="email" id={id} name="email" autoComplete="email" />
  </FormItem>
);
```

## Структура компонента

`FormItem` состоит из трёх основных частей:

* `top` — заголовок элемента формы;
* `children` — основной контент (поле ввода);
* `bottom` — подсказка или сообщение о статусе валидации.

```jsx
const id = React.useId()
const bottomId = React.useId()

return (
  <FormItem
    htmlFor={id}
    top="E-mail"
    bottom="Мы не передаём вашу почту третьим лицам"
    bottomId={bottomId}
  >
    <Input type="email" id={id} name="email" autoComplete="email" aria-labelledby={bottomId} />
  </FormItem>
);
```

### Подкомпоненты

Иногда шапка поля составная — содержит несколько отдельных компонентов. В таком случае используйте подкомпоненты: они позволяют собрать нужный заголовок и гибко управлять свойствами (например, для `a11y`).

* `<FormItem.Top>` служит оберткой для составной шапки поля, отвечая за выравнивание контента и расстановку отступов;
* `<FormItem.TopLabel>` отвечает за отрисовку заголовка поля. По умолчанию компонент представлен тегом `label`,
  если передано свойство `htmlFor`. Можно переопределить через свойство `Component`;
* `<FormItem.TopAside>` отвечает за отрисовку дополнительного контента справа от заголовка поля.

```jsx
const id = React.useId()

return (
  <FormItem
    top={
      <FormItem.Top>
        <FormItem.TopLabel htmlFor={id}>Дополнительная информация</FormItem.TopLabel>
        <FormItem.TopAside>0/100</FormItem.TopAside>
      </FormItem.Top>
    }
  >
    <Textarea id={id} name="about" />
  </FormItem>
);
```

## Состояния

#### `disabled`

Свойство `disabled` блокирует взаимодействие с компонентом и добавляет визуальную индикацию недоступности.

> Свойство `disabled` необходимо передавать и компоненту `FormItem`, и вложенному в него полю, потому что
> свойство влияет на разные части компонентов. Например, недоступные поля ввода по умолчанию нельзя [удалить](#removable).

```jsx
const id = React.useId()

return (
  <FormItem htmlFor={id} top="E-mail" disabled>
    <Input type="email" id={id} name="email" autoComplete="email" disabled />
  </FormItem>
);
```

## Валидация

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

* `"default"` - обычное состояние компонента (по умолчанию);
* `"error"` - состояние ошибки, используйте данное значение, чтобы сообщить пользователю о некорректно введённых данных;
* `"valid"` - состояние успешной валидации, используйте для индикации прошедшей проверки или при исправлении ошибки.

Если вы используете значения `"error"` (реже `"valid"`), старайтесь сопровождать состояние поясняющим сообщением, например,
используя свойство `bottom`.

```jsx
const emailId = React.useId()
const emailBottomId = React.useId()
const textId = React.useId()

return (
  <>
    <FormItem
      htmlFor={emailId}
      top="E-mail"
      status="error"
      bottom="Пожалуйста, введите e-mail"
      bottomId={emailBottomId}
      required
      noPadding
    >
      <Input aria-labelledby={emailBottomId} id={emailId} type="email" name="email" autoComplete="email" required />
    </FormItem>
    <FormItem htmlFor={textId} top="Описание" status="valid" noPadding>
      <Input id={textId} name="text" />
    </FormItem>
  </>
);
```

## Обязательность поля

Свойство `required` позволяет пометить поле как обязательное для заполнения.

> Это свойство отвечает только за визуальную составляющую.
> На само поле, обёрнутое в `FormItem`, нужно дополнительно передавать свойство `required`.

```jsx
<FormItem top="Email" required>
  <Input type="email" name="email" autoComplete="email" required />
</FormItem>
```

## Удаление поля \[#removable]

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

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

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

```jsx
const id = React.useId()
const bottomId = React.useId()

return (
  <FormItem
    htmlFor={id}
    removable
    onRemove={() => alert('Обработчик удаления')}
    top="Отчество"
    bottom="Если у вас нет отчества — удалите этот пункт"
    bottomId={bottomId}
  >
    <Input id={id} aria-labelledby={bottomId} />
  </FormItem>
);
```

## Отступы

По умолчанию компонент расставляет внешние отступы, чтобы автоматически выравниваться в соответствии с
требованиями дизайн-системы (при использовании в `Group`, например). Отключить эти отступы можно с помощью свойства `noPadding`.

## Тестирование (e2e) \[#e2e]

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

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

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

Для корректной работы ассистивных технологий необходимо вручную передавать некоторые параметры:

* при передаче в `FormItem` компонента, отвечающего за пользовательский ввод (например, `<input type="text" />`),
  рекомендуется передавать свойства `top` и `htmlFor`. В компонент пользовательского ввода должно быть передано свойство
  `id`, которое соответствует значению `htmlFor` в `FormItem`;
* при использовании свойства `bottom` рекомендуется также передавать в компонент пользовательского ввода (например,
  `<input type="text" />`) свойство `aria-describedby`, а в сам `FormItem` передать `bottomId`,
  который соответствует значению `aria-describedby`.

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

### FormItem

| Свойство             | Тип                                                                                             | По умолчанию | Описание                                                                                                                                                                                                                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bottom`             | `ReactNode`                                                                                     | `-`          | Дополнительный элемент, отображаемый под содержимым.                                                                                                                                                                                                                                   |
| `bottomId`           | `string`                                                                                        | `-`          | Передаётся при использовании `bottom`.  Должен совпадать с `aria-describedby`, который передаётся в компонент, отвечающий за пользовательский ввод.                                                                                                                                    |
| `Component`          | `ElementType<any, keyof IntrinsicElements>`                                                     | `-`          |                                                                                                                                                                                                                                                                                        |
| `getRootRef`         | `Ref<HTMLElement>`                                                                              | `-`          |                                                                                                                                                                                                                                                                                        |
| `noPadding`          | `boolean`                                                                                       | `-`          | Удаляет внешние отступы вокруг компонента.                                                                                                                                                                                                                                             |
| `onRemove`           | `((e: MouseEvent<Element, MouseEvent>, rootEl?: HTMLElement \| null) => void) \| undefined`     | `-`          | Обработчик, срабатывающий при нажатии на контрол удаления.                                                                                                                                                                                                                             |
| `ref`                | `Ref<HTMLElement>`                                                                              | `-`          |                                                                                                                                                                                                                                                                                        |
| `removable`          | `boolean \| "indent"`                                                                           | `-`          | Дает возможность удалить `FormItem`. Рекомендуется использовать только для `Input` или `Select`.  Режим `indent` предназначен для визуального отступа.                                                                                                                                 |
| `removeButtonTestId` | `string`                                                                                        | `-`          | Передает атрибут `data-testid` для кнопки удаления.                                                                                                                                                                                                                                    |
| `removePlaceholder`  | `ReactNode`                                                                                     | `Удалить`    | Текст кнопки удаления ячейки. Визуально скрыт везде, кроме iOS. На iOS появляется в выезжающей кнопке для удаления ячейки.                                                                                                                                                             |
| `render`             | `((props: AllHTMLAttributes<HTMLElement> & Omit<HasRootRef<HTMLElement>, "ref">) => ReactNode)` | `-`          | Позволяет переопределить рендер компонента, получая собранные свойства (включая вычисленные `className` и `style`). Используется вместо `Component`.  Позволяет гибко объединять несколько компонентов без создания промежуточных DOM-узлов и без ремаунта поддерева на каждый рендер. |
| `required`           | `boolean`                                                                                       | `false`      | Помечает поле обязательным.                                                                                                                                                                                                                                                            |
| `status`             | `"default" \| "error" \| "valid"`                                                               | `default`    | Статус, влияющий на стиль отображения компонента.                                                                                                                                                                                                                                      |
| `toggleButtonTestId` | `string`                                                                                        | `-`          | Передает атрибут `data-testid` для кнопки, которая активирует кнопку удаления (iOS only).                                                                                                                                                                                              |
| `top`                | `ReactNode`                                                                                     | `-`          | Дополнительный элемент, отображаемый над содержимым.                                                                                                                                                                                                                                   |
| `topComponent`       | `ElementType<any, keyof IntrinsicElements>`                                                     | `-`          | Позволяет поменять тег используемый для top Если оставить пустым, то тег top будет span. Если оставить пустым и использовать htmlFor, то тег top будет label.                                                                                                                          |
| `topId`              | `string`                                                                                        | `-`          | Передаётся при использовании `top`.  `id` для `top`.                                                                                                                                                                                                                                   |
| `topMultiline`       | `boolean`                                                                                       | `false`      | Многострочный вывод заголовка. По умолчанию текст не переносится при переполнении.                                                                                                                                                                                                     |

### FormItem.Top

| Свойство     | Тип                                                                                                   | По умолчанию | Описание                                                                                                                                                                                                                                                                               |
| ------------ | ----------------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Component`  | `ElementType<any, keyof IntrinsicElements>`                                                           | `-`          |                                                                                                                                                                                                                                                                                        |
| `getRootRef` | `Ref<HTMLDivElement>`                                                                                 | `-`          |                                                                                                                                                                                                                                                                                        |
| `ref`        | `Ref<HTMLDivElement>`                                                                                 | `-`          |                                                                                                                                                                                                                                                                                        |
| `render`     | `((props: AllHTMLAttributes<HTMLDivElement> & Omit<HasRootRef<HTMLDivElement>, "ref">) => ReactNode)` | `-`          | Позволяет переопределить рендер компонента, получая собранные свойства (включая вычисленные `className` и `style`). Используется вместо `Component`.  Позволяет гибко объединять несколько компонентов без создания промежуточных DOM-узлов и без ремаунта поддерева на каждый рендер. |

### FormItem.TopLabel

| Свойство     | Тип                                                                                             | По умолчанию | Описание                                                                                                                                                                                                                                                                               |
| ------------ | ----------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Component`  | `ElementType<any, keyof IntrinsicElements>`                                                     | `-`          |                                                                                                                                                                                                                                                                                        |
| `getRootRef` | `Ref<HTMLElement>`                                                                              | `-`          |                                                                                                                                                                                                                                                                                        |
| `ref`        | `Ref<HTMLElement>`                                                                              | `-`          |                                                                                                                                                                                                                                                                                        |
| `render`     | `((props: AllHTMLAttributes<HTMLElement> & Omit<HasRootRef<HTMLElement>, "ref">) => ReactNode)` | `-`          | Позволяет переопределить рендер компонента, получая собранные свойства (включая вычисленные `className` и `style`). Используется вместо `Component`.  Позволяет гибко объединять несколько компонентов без создания промежуточных DOM-узлов и без ремаунта поддерева на каждый рендер. |

### FormItem.TopAside

| Свойство     | Тип                                                                                             | По умолчанию | Описание                                                                                                                                                                                                                                                                               |
| ------------ | ----------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Component`  | `ElementType<any, keyof IntrinsicElements>`                                                     | `-`          |                                                                                                                                                                                                                                                                                        |
| `getRootRef` | `Ref<HTMLElement>`                                                                              | `-`          |                                                                                                                                                                                                                                                                                        |
| `ref`        | `Ref<HTMLElement>`                                                                              | `-`          |                                                                                                                                                                                                                                                                                        |
| `render`     | `((props: AllHTMLAttributes<HTMLElement> & Omit<HasRootRef<HTMLElement>, "ref">) => ReactNode)` | `-`          | Позволяет переопределить рендер компонента, получая собранные свойства (включая вычисленные `className` и `style`). Используется вместо `Component`.  Позволяет гибко объединять несколько компонентов без создания промежуточных DOM-узлов и без ремаунта поддерева на каждый рендер. |
