Текстовое поле

Здесь два слоя. input() и textarea() — голые элементы управления; textField() и textareaField() оборачивают один из них в подпись, подсказку и сообщение об ошибке и связывают их через for и aria-describedby. Берите вторые, если только не собираете раскладку сами.

Простое поле

textField({ label: 'Имя', name: 'name', placeholder: 'Ada Lovelace' })

Текст подсказки

Подсказка связана через aria-describedby, поэтому скринридер читает её как часть поля, а не как отдельный текст после него.

Мы пишем только о неудачных сборках.
textField({
  label: 'Почта',
  name: 'email',
  type: 'email',
  help: 'Мы пишем только о неудачных сборках.',
})

Обязательное поле и ошибка

error помечает поле недействительным, красит рамку, выставляет aria-invalid и наводит aria-describedby на сообщение — один проп, все четыре эффекта.

Это не URL.
stack({ gap: 'lg' },
  textField({ label: 'Проект', name: 'project', required: true, value: '' }),
  textField({
    label: 'Сайт',
    name: 'site',
    error: 'Это не URL.',
    value: 'sitelo точка dev',
  }),
)

Размеры

stack({ gap: 'md' },
  textField({ label: 'Маленькое', name: 'small', size: 'sm', placeholder: 'sm' }),
  textField({ label: 'Среднее', name: 'medium', size: 'md', placeholder: 'md' }),
  textField({ label: 'Большое', name: 'large', size: 'lg', placeholder: 'lg' }),
)

Приставки

Префикс или суффикс, приклеенный к самому полю, — для единиц измерения и постоянных кусков значения.

https://
секунд
stack({ gap: 'md' },
  textField({ label: 'Сайт', name: 'url', startAdornment: 'https://', placeholder: 'example.com' }),
  textField({ label: 'Таймаут сборки', name: 'timeout', endAdornment: 'секунд', value: '30' }),
)

Отключено и только для чтения

stack({ gap: 'md' },
  textField({ label: 'Отключено', name: 'disabled', value: 'Редактировать нельзя', disabled: true }),
  textField({ label: 'Только для чтения', name: 'readonly', value: 'dist/', readonly: true }),
)

Многострочное

textareaField() — то же поле вокруг <textarea>. Его значение является содержимым элемента, а не атрибутом, и об этом заботится сам компонент.

Показывается в результатах поиска и в карточках для соцсетей.
textareaField({
  label: 'Описание',
  name: 'description',
  rows: 4,
  help: 'Показывается в результатах поиска и в карточках для соцсетей.',
  value: 'Генерация статических сайтов без настройки, на Vite.',
})

В форме

card(
  cardBody(
    stack({ gap: 'md' },
      textField({ label: 'Имя', name: 'contact-name', required: true }),
      textField({ label: 'Почта', name: 'contact-email', type: 'email', required: true }),
      textareaField({ label: 'Сообщение', name: 'message', rows: 3 }),
    ),
  ),
  cardFooter({ divided: true, style: 'justify-content: flex-end' },
    button({ variant: 'ghost', color: 'neutral' }, 'Отмена'),
    button({ type: 'submit' }, 'Отправить'),
  ),
)

Собрать самому

field() — это обёртка сама по себе: она принимает любой элемент управления потомком, так что можно поставить два инпута в одну строку или использовать элемент, которого в этой библиотеке нет, с тем же оформлением подписи и ошибки.

Одна подпись не может называть два элемента, поэтому здесь каждому инпуту нужно собственное доступное имя. Этим и заняты aria-label: видимая подпись называет пару, а каждый инпут говорит, какой он край.

Обе границы включаются.
field({ label: 'Диапазон дат', help: 'Обе границы включаются.' },
  stack({ direction: 'row', gap: 'sm' },
    input({ type: 'date', name: 'from', 'aria-label': 'С' }),
    input({ type: 'date', name: 'to', 'aria-label': 'По' }),
  ),
)

Пропсы

textField и textareaField

ПропТипПо умолчаниюОписание
labelChild—Подпись поля. Из неё же выводится id элемента, когда нет name.
namestring—Имя поля формы; из него выводится id.
helpChild—Подсказка под элементом, связанная через aria-describedby.
errorChild | false—Сообщение об ошибке. Заодно выставляет aria-invalid на элементе.
requiredbooleanfalseПомечает подпись и сам элемент.
size'sm' | 'md' | 'lg''md'Высота элемента и размер текста.
typestring'text'Любой тип input. Только для textField.
startAdornmentChild—Префикс, приклеенный к элементу. Только для textField.
endAdornmentChild—Суффикс, приклеенный к элементу. Только для textField.
valuestring | number—Начальное значение.
fieldClassstring—Класс для обёртки, а не для самого элемента.

Идентификаторы выводятся из name — или из label, когда name нет, — а не из счётчика, поэтому одна и та же страница на каждой сборке даёт одинаковый HTML. Передайте id, чтобы задать свой.

field

ПропТипПо умолчаниюОписание
labelChild—Текст подписи.
helpChild—Подсказка под элементом.
errorChild | false—Сообщение об ошибке; заодно добавляет обёртке состояние «недействительно».
requiredbooleanfalseДобавляет к подписи пометку обязательности.
forstring—Id элемента, который подписывается.