TextField
BasicInputs
<co-text-field>TextField is a labelled one-line input with masks for phone, SSN, NPI, ZIP and EIN, plus error, helper, required and read-only lock states.
import { TextField } from 'health-components';
Examples
Showcase
Masks
With Error
Read Only
Sizes
Usage
<TextField label="Mobile Phone" mask="phone" required value={phone} onChange={setPhone} error={errors.phone} />
<TextField label="Member ID" value={memberId} readOnly={access === "view"} />
When to use
- Short free text and identifiers: name, phone, member ID, NPI, policy number.
When not to use
- Choosing from a known list: Select or Combobox.
- Dates: DatePicker.
- More than one line: TextArea.
Variants and states
| Variant | What it is |
|---|---|
| mask phone | (###) ###-####, numeric keypad on phones. |
| mask ssn | ###-##-####. Show only the last four after save. |
| mask npi | 10 digits. |
| mask zip | 5 digits or ZIP+4. |
| mask ein | XX-XXXXXXX. |
| error | Red border plus the message under the field, role alert. |
| helper | Muted hint under the field. |
| required | Red asterisk after the label plus aria-required. |
| readOnly lock | Grey fill, lock icon and "Your role can view but not edit" under the field. |
| sizes | sm 30px, md 36px, lg 48px (kiosk). |
Accessibility
- Every field has a visible label; placeholder is an example, never the label.
- Error and helper text are linked with aria-describedby; aria-invalid is set on error.
- A mask only arranges digits into the pattern. It proves the shape, not that the NPI or ZIP is real; check those on save and say so in the error ("This NPI is not in NPPES").
- Input borders use
border, which is below 3:1 onsurfacein every light style (source value kept). The label and the field fill carry the boundary; see README, Accessibility.
Do and don't
- Do: Error text names the field and the fix: "Enter the EIN as XX-XXXXXXX."
- Do: Read-only for a biller viewing demographics: lock state, value still selectable and copyable.
- Don't: "Invalid input".
- Don't: Hiding a field the role can view: that is the view level, so lock it; hide only at the none level.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
label * | string | — | Visible label; required |
mask | MaskKind | none | 'phone' | 'ssn' | 'npi' | 'zip' | 'ein' | 'date' |
value | string | undefined (uncontrolled) | Controlled value |
defaultValue | string | "" | Initial value (uncontrolled), formatted with the mask |
onChange | (value: string, event: ChangeEvent<HTMLInputElement>) => void | none | Called with the (masked) value and the change event |
error | string | none | Error message: red border, message under the field with role alert, aria-invalid |
helper | string | the mask hint | Muted hint under the field |
required | boolean | false | Red asterisk plus aria-required |
readOnly | boolean | false | Read-only lock state: grey fill, lock icon and lock message |
lockMessage | string | 'Your role can view but not edit' | Lock line text when readOnly |
size | TextFieldSize | 'md' | 'sm' 30px | 'md' 36px | 'lg' 48px (kiosk) |
iconLeft | IconName | none | Icon inside the input on the left |
suffix | string | none | Unit text inside the input on the right, such as "units" |
style | CSSProperties | — | Inline style of the root |
Also accepts native attributes, including defaultChecked, autoFocus, onInput, type, disabled, name, max, step, placeholder, accept, autoComplete, checked, maxLength, min, multiple, plus className and event handlers on the root element.
Angular, Vue and HTML
Register the elements once (Angular guide), then use <co-text-field>. Attributes take strings; arrays and objects are set as properties (Angular [prop], Vue :prop) or as JSON attributes. Callbacks are DOM events with the value in event.detail.
Angular template
<co-text-field label="…" mask="…" [style]="style" (co-change)="onChange($event.detail)"></co-text-field>
| Kind | Name | Description |
|---|---|---|
| attribute | label | Visible label; required |
| attribute | mask | 'phone' | 'ssn' | 'npi' | 'zip' | 'ein' | 'date'; default none |
| attribute | value | Controlled value; default undefined (uncontrolled) |
| attribute | default-value / defaultValue | Initial value (uncontrolled), formatted with the mask; default "" |
| attribute | error | Error message: red border, message under the field with role alert, aria-invalid; default none |
| attribute | helper | Muted hint under the field; default the mask hint |
| attribute | required | Red asterisk plus aria-required; default false |
| attribute | read-only / readOnly | Read-only lock state: grey fill, lock icon and lock message; default false |
| attribute | lock-message / lockMessage | Lock line text when readOnly; default 'Your role can view but not edit' |
| attribute | size | 'sm' 30px | 'md' 36px | 'lg' 48px (kiosk); default 'md' |
| attribute | icon-left / iconLeft | Icon inside the input on the left; default none |
| attribute | suffix | Unit text inside the input on the right, such as "units"; default none |
| property / JSON attribute | style | Inline style of the root |
| attribute | default-checked / defaultChecked | |
| attribute | auto-focus / autoFocus | |
| property / JSON attribute | type | |
| attribute | disabled | |
| attribute | name | |
| property / JSON attribute | max | |
| property / JSON attribute | step | |
| attribute | placeholder | |
| attribute | accept | |
| property / JSON attribute | auto-complete / autoComplete | |
| attribute | checked | |
| attribute | max-length / maxLength | |
| property / JSON attribute | min | |
| attribute | multiple | |
| event | co-change | Called with the (masked) value and the change event; default none (React: onChange) |
| event | co-input | (React: onInput) |