Form Item
import "@taprootio/espalier/form-item";
<esp-form-item>
Wraps fields with label and error message functionality. For more information about forms, read our guide for working with forms.
Exactly one element belongs in the default slot. That control may be
replaced or moved to another esp-form-item after render: the old binding
is removed before the new one is applied, including form-item-owned name,
description, accessible-label, validation-listener, and help-target state.
Consumer-authored name and description values are preserved. An empty or
multi-control default slot is reported asynchronously from the queued
slotchange reconciliation, after synchronous DOM moves have settled; the
error cannot be caught around the mutation itself. The same invalid initial
assignment is reported synchronously from firstUpdated and rejects the
component's first updateComplete promise.
Slots
<esp-form-item> has the following slots:
Default
The single form control the item wraps.
hint
Rich hint content; replaces the hint attribute text when present.
Attributes
<esp-form-item> has the following attributes:
label
label has a default value of "".
Label text to display for the given form control.
autofocus
autofocus has a default value of false.
When true, the first control where autofocus is true has focus captured.
hint
hint has a default value of "".
Persistent helper text shown with the field — the bottom rung of
the help ladder. Hints are static authored guidance such as an
expected format; validation messaging belongs to error and
warning and must not be routed through the hint. The hint stays
visible while an error or warning badge is showing, and is
announced to assistive technology as the field's description via
aria-describedby.
hint-placement
hint-placement has a default value of "below".
Where the hint renders. below (the default) places it directly
under the field, above the error/warning badge rows. above
places it between the label text and the field. Any other value
falls back to below.
error
error has a default value of undefined.
An error message to show for the given form control.
warning
warning has a default value of undefined.
A warning message to show for the given form control. Warning is hidden when an error is also present.
field-name
field-name has a default value of "".
Identifies this form item's field. Serves two purposes:
- Filters errors from the bound
errorPoolto show only errors whosefieldNamematches. - Propagates as the
nameattribute on the slotted form field, so there is no need to setnameseparately.
help-url
help-url has a default value of "".
Per-field help document override. A URL fragment selects the topic;
otherwise field-name supplies the anchor. When omitted, the nearest
composed-tree ancestor's help-src is used.
help-title-source
help-title-source has a default value of "field".
Chooses the flyout title for form-context help. The default, field,
uses this form item's visible label. Set document to adopt the text
of the matched heading in the help document instead.
error-pool
error-pool has a default value of undefined.
Bind to an array of ValidationError to automatically filter
and show errors whose fieldName matches this item's
field-name attribute.
Methods
<esp-form-item> has the following methods:
focus
Focus the assigned slotted field.
CSS Properties
<esp-form-item> has the following CSS properties:
--esp-form-item-label-color
The color of the label text.
--esp-form-item-hint-color
The color of the hint text. Defaults to a muted variant of the body text color.
--esp-form-item-hint-font-size
The font size of the hint text. Defaults to var(--esp-type-tiny).
--esp-form-item-error-color
The color of the visible error badge text.
--esp-form-item-error-background
The background color of the visible error badge.
--esp-form-item-error-field-background
The background color applied to slotted fields while an error is shown.
--esp-form-item-error-field-border-color
The border color applied to slotted fields while an error is shown.
--esp-form-item-error-field-text-color
The text color applied to slotted fields while an error is shown.
--esp-form-item-error-field-focus-shadow
The focus shadow color applied to slotted fields while an error is shown.
--esp-form-item-warning-color
The color of the visible warning badge text.
--esp-form-item-warning-background
The background color of the visible warning badge.
--esp-form-item-warning-field-background
The background color applied to slotted fields while a warning is shown.
--esp-form-item-warning-field-border-color
The border color applied to slotted fields while a warning is shown.
--esp-form-item-warning-field-text-color
The text color applied to slotted fields while a warning is shown.
--esp-form-item-warning-field-focus-shadow
The focus shadow color applied to slotted fields while a warning is shown.
--esp-form-item-font
The font family for the form item.
--esp-form-item-font-size
The font size for the form item.