Field

Usage

Field is one labeled form field: Label, a bordered control frame with an input, description and error copy, and optional adornments. Use it instead of a bare Label and Input pair. The label sits --space-8 above the control; to put a visible label above another control (SegmentedControl, ButtonGroup, ToggleGroup), compose FieldStack with Label, or use a Fieldset legend, and the gap is the same. Never add spacing of your own for it. Coming from ui-core Input and ui-forms FormInput? packages/ui/docs/migrating-from-ui-forms.md lists the prop renames (onChange to onValueChange, masked and maskType to mask, leadIcon and tailIcon to leadingIcon, trailingIcon and action) and the Controller recipe.

Masks

Set mask to format what the user types. The expected format belongs in description, because screen readers read the formatted value and the placeholder disappears as soon as the user types.

value and onValueChange carry the formatted text. Read details.raw (and details.e164 for phone) when the app stores the unformatted value.
Currency follows the nearest LocaleProvider, which the shell renders once with the app's UI language (ADR 0024). Pass locale only to override it. With no provider the default is en-US, fixed so server and client render the same text. Put the currency symbol in prefix or suffix.
A calendar day, a range, a time of day or a date-time is a DateInput, DateRangeInput, TimeInput or DateTimeInput, not a masked Field (FLD-24).
For any other format, pass a function. Keep it idempotent: formatting its own output must return the same output.

Phone limitations

Phone formatting is North American first and has no country table.

Ten digits format as (555) 123-4567. A leading 1, or +1, formats as +1 (555) 123-4567.
Any other number that starts with + is grouped in threes (+447 911 123 456), up to 15 digits. The country code is not separated from the number, because that needs per-country data. details.e164 is still correct.
Extensions start with * or # and work on North American numbers only, up to six digits.
Phone does not validate. details.e164 is only a shape check: ten North American digits, or at least eight digits after +.

For per-country grouping, pass a custom formatter built on a phone library in the app.

Editing behavior

The caret stays next to the digit being edited, including after paste.
Backspace or Delete with the caret next to a separator moves the caret over it and deletes nothing.
Deleting drops trailing separators, so (555) returns to (555.
An IME composition is formatted when it ends.

Input purpose

Use FieldType.Email, Url or Tel for those values rather than a text Field with a mask, so the browser knows the type. Set autoComplete and name on every field about the user, such as autoComplete="tel" on a callback number. Field never sets autocomplete="off".

Adornments

leadingIcon and trailingIcon are decorative and hidden from assistive technology. Pass a plain Icon: Field draws every icon it places, including those in the clear, reveal and action Buttons, at 16px in the subtle foreground. An icon turns to the default foreground only while its Button is selected or pressed, such as a revealed password. When the field is disabled, directly or through a disabled Fieldset, every icon, a trailing chevron included, paints the disabled foreground.
prefix and suffix are static text segments.
action adds one Button at the tail: a text label, or an icon with an accessible label. Search and Password own the tail, so action is a type error with them.

Empty State / Accessibility

Field / API and Development

On this page

Field

Usage

Masks

Set mask to format what the user types. The expected format belongs in description, because screen readers read the formatted value and the placeholder disappears as soon as the user types.

value and onValueChange carry the formatted text. Read details.raw (and details.e164 for phone) when the app stores the unformatted value.
Currency follows the nearest LocaleProvider, which the shell renders once with the app's UI language (ADR 0024). Pass locale only to override it. With no provider the default is en-US, fixed so server and client render the same text. Put the currency symbol in prefix or suffix.
A calendar day, a range, a time of day or a date-time is a DateInput, DateRangeInput, TimeInput or DateTimeInput, not a masked Field (FLD-24).
For any other format, pass a function. Keep it idempotent: formatting its own output must return the same output.

Phone limitations

Phone formatting is North American first and has no country table.

Ten digits format as (555) 123-4567. A leading 1, or +1, formats as +1 (555) 123-4567.
Any other number that starts with + is grouped in threes (+447 911 123 456), up to 15 digits. The country code is not separated from the number, because that needs per-country data. details.e164 is still correct.
Extensions start with * or # and work on North American numbers only, up to six digits.
Phone does not validate. details.e164 is only a shape check: ten North American digits, or at least eight digits after +.

For per-country grouping, pass a custom formatter built on a phone library in the app.

Editing behavior

The caret stays next to the digit being edited, including after paste.
Backspace or Delete with the caret next to a separator moves the caret over it and deletes nothing.
Deleting drops trailing separators, so (555) returns to (555.
An IME composition is formatted when it ends.

Input purpose

Adornments

leadingIcon and trailingIcon are decorative and hidden from assistive technology. Pass a plain Icon: Field draws every icon it places, including those in the clear, reveal and action Buttons, at 16px in the subtle foreground. An icon turns to the default foreground only while its Button is selected or pressed, such as a revealed password. When the field is disabled, directly or through a disabled Fieldset, every icon, a trailing chevron included, paints the disabled foreground.
prefix and suffix are static text segments.
action adds one Button at the tail: a text label, or an icon with an accessible label. Search and Password own the tail, so action is a type error with them.

Empty State / Accessibility

Field / API and Development

On this page