API and Development
Field, FieldMaskType, FieldStack, FieldType from @prepared911/ui/field.
| Prop | Type | Default | Notes |
|---|---|---|---|
label | LocalizedMessage | required | Visible label. |
type | FieldType | FieldType.Text | Text, Email, Url, Tel, Search, Password. InputWithSelect is reserved. |
value | string | null | ; | Controlled value. With a mask it is the formatted text. null is a controlled empty value. |
defaultValue | string | "" | Uncontrolled initial value and form-reset target. A mask formats it. |
onValueChange | (value, details: FieldValueChangeDetails) => void | ; | details.reason is InputChange, FormReset, ImperativeAction or None. A masked Field adds details.raw, and phone adds details.e164 and details.extension. |
mask | FieldMaskType | (text: string) => string | false | ; | See Masks. Tel, Url and Email default to their mask; false turns that off. |
locale | string | Nearest LocaleProvider, then "en-US" | BCP 47 locale for the Currency mask. |
description | LocalizedMessage | ; | Supporting copy below the control. Put the expected mask format here. |
error, invalid | LocalizedMessage, boolean | ; | Error copy shows when invalid is true. |
required, requiredHint | boolean, LocalizedMessage | ; | Label marker and form-level explanation. |
prefix, suffix | LocalizedMessage | DisplayValue | ; | Static text segments inside the control. |
leadingIcon, trailingIcon | ReactNode | ; | Decorative icons. Field sets their size (16px) and color (subtle). |
action | FieldAction | ; | One tail Button. Not available with Search or Password. |
size | InputSize | InputSize.Large | Control scale. |
clearLabel | LocalizedMessage | required for Search | Accessible name of the clear Button. |
revealLabel, hideLabel | LocalizedMessage | required for Password | Accessible names of the reveal Button. |
input attributes forward to the host, except style, children and onChange. autoComplete and name pass through and are never defaulted: set the purpose token (email, tel, postal-code, username, …) on every field about the user (WCAG 1.3.5).
Keyboard and spellcheck: Email, Url and Tel render type="email", "url" and "tel" with spellcheck="false". A built-in mask on a text Field sets the keyboard and turns spellcheck off (table below); a custom mask sets neither. A Password Field always renders spellcheck="false", concealed or revealed, and neither a mask nor a spellCheck you pass changes that. On any other Field, inputMode and spellCheck you pass win.
FieldMaskType | Display | details.raw | inputMode |
|---|---|---|---|
Phone | (555) 123-4567; +1 (555) 123-4567; other + numbers in groups of three; optional *1234 or #1234 extension | National digits (5551234567), or all digits after + for non-North-American numbers | tel |
PostalCode | 12345, 12345-6789 | Digits | numeric |
Currency | Locale grouping and decimal separator, at most two fraction digits, no symbol | Plain decimal, such as 1234.5 | decimal |
Url | Whitespace removed, case kept | The text as typed | url |
Email | Whitespace removed, case kept | The text as typed | email |
details.raw is the text as typed.
Phone details.e164 is +15551234567 once the number is complete (ten North American digits, or at least eight digits after +), and an empty string before that. details.extension holds the extension digits. The extension is not part of raw or e164.
The props of Button (children, or icon with label; onClick, intent, loading, disabled), without size, variant, type, className, ref and preventFocusOnPress, which Field sets. The action disables with the field and stays enabled when the field is read-only.
Field, FieldType, FieldMaskType, and the types FieldProps, FieldMask, FieldMaskDetails, FieldMaskFormatter, FieldAction, FieldAdornmentCopy, FieldValueChangeDetails, FieldValueChangeReason.
| Name | Type | Default | Description |
|---|---|---|---|
label | LocalizedMessage | — | Visible label copy. |
action | FieldAction | — | — |
autoComplete | HTMLInputAutoCompleteAttribute | — | Autofill purpose token. Set it on every field that collects information about the user: name, email, tel,
street-address, postal-code, username, current-password, new-password, one-time-code, or a section and
shipping or billing prefix before one. Input turns spellcheck off for identifier purposes. Do not pass off to
a field that collects personal data; no design-system control defaults to it except NumberField, which a token
replaces. |
className | string | — | Classes on the root wrapper. |
clearLabel | LocalizedMessage | (string & { readonly [LOCALIZED_MESSAGE_BRAND]: true; }) | — | Accessible name for the search clear control when type is {@link FieldType.Search}.
Accessible name for the clear control when the field has a value. |
defaultValue | string | — | Initial value when uncontrolled. |
description | LocalizedMessage | — | Supporting copy below the control. |
error | LocalizedMessage | — | Error copy when {@link invalid} is true. |
hideLabel | LocalizedMessage | (string & { readonly [LOCALIZED_MESSAGE_BRAND]: true; }) | — | Accessible name to hide a revealed password when type is {@link FieldType.Password}.
Accessible name when the secret is visible. |
invalid | boolean | — | When true, the control uses destructive border treatment and exposes error semantics. |
leadingIcon | ReactNode | — | Decorative icon before the input; not interactive. |
locale | string | — | BCP 47 locale for the Currency mask. Defaults to the nearest LocaleProvider, then en-US, so server
and client render the same text. The shell supplies the agency locale once; pass this only to override it. |
mask | false | FieldMask | — | Input mask. A {@link FieldMaskType } or a custom formatter. FieldType.Tel, Url and Email default to
their matching mask; false turns the default off. value and onValueChange carry the formatted text;
details.raw carries the unformatted value. |
name | string | — | Form control name, submitted with the form. Browsers also read it as an autofill hint, so pass a meaningful one. |
onValueChange | ((value: string | null, details: FieldValueChangeDetails) => void) | — | Value change callback with {@link FieldValueChangeReason}. |
placeholder | LocalizedMessage | — | Placeholder when empty. |
prefix | FieldAdornmentCopy | — | Static text before the input inside the control row. |
ref | Ref<HTMLInputElement> | — | Ref to the rendered input. |
required | boolean | — | When true, Label shows the marker and the control is required / aria-required. |
requiredHint | LocalizedMessage | — | Form-level explanation of required fields (Decision FLD-1). |
revealLabel | LocalizedMessage | (string & { readonly [LOCALIZED_MESSAGE_BRAND]: true; }) | — | Accessible name to reveal a password value when type is {@link FieldType.Password}.
Accessible name when the secret is hidden. |
select | FieldSelectProps | — | Select inside the control frame, before or after the input. |
size | InputSize | — | Control scale. Defaults to {@link InputSize.Large}. |
suffix | FieldAdornmentCopy | — | Static text after the input inside the control row. |
trailingIcon | ReactNode | — | Decorative icon after the input; not interactive. Sits before the suffix and tail Buttons. |
type | FieldType | — | Field variant. Defaults to {@link FieldType.Text}. |
value | string | null | — | Controlled value. null is a controlled empty value. |