Form Field
Composable label, message, adornment, and accessibility foundation for projected native or custom controls.
- Selector
- ui-form-field
- Package
- @ngnova/ui/form-field
Import
import { UiFormFieldComponent, UiFormFieldControlDirective, UiFormFieldPrefixDirective, UiFormFieldSuffixDirective } from '@ngnova/ui/form-field';Usage & variants
Live examples use the public ui-form-field API, paired with the exact snippet a product team would paste into an Angular app.
Workspace address field
Composable label, message, adornment, and accessibility foundation for projected native or custom controls.
Choose a short, recognizable name.
Production guidance
Use these notes to decide when the component belongs in a product workflow and what to verify before shipping.
When to use
Use to style a native input, select, textarea, or application-specific control that is not already covered by a dedicated NgNova component.
Watch for
Only one projected uiFormFieldControl is registered; use one Form Field per editable control.
Product recipes
Apply Form Field in distinct, copyable product scenarios—not just an isolated component state.
Composed native control
Prefix and suffix slots stay outside the editable value while the label and message target the real input.
1 2 3 4 5 6 7 8 9 10 11
<ui-form-field
label="Workspace"
helperText="Choose a short name."
[invalid]="workspace.invalid && workspace.touched"
errorText="Workspace is required."
required
>
<span uiFormFieldPrefix aria-hidden="true">@</span>
<input uiFormFieldControl [formControl]="workspace" />
<span uiFormFieldSuffix>.team</span>
</ui-form-field>Hidden search label
A hidden native label remains available to assistive technology.
1 2 3 4
<ui-form-field label="Search packages" hideLabel appearance="filled">
<svg uiFormFieldPrefix aria-hidden="true"><!-- search icon --></svg>
<input uiFormFieldControl type="search" [formControl]="query" />
</ui-form-field>Validated currency amount
Currency adornments stay outside the editable number while touched validation replaces the helper message.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
<ui-form-field
label="Monthly budget"
helperText="Enter the approved operating budget."
[invalid]="budget.invalid && budget.touched"
errorText="Enter a budget greater than zero."
required
>
<span uiFormFieldPrefix aria-hidden="true">$</span>
<input
uiFormFieldControl
type="number"
inputmode="decimal"
min="1"
step="100"
[formControl]="budget"
/>
<span uiFormFieldSuffix>USD</span>
</ui-form-field>Deployment environment
The same label and message foundation can compose a native select when a specialized value component is unnecessary.
1 2 3 4 5 6 7 8 9 10 11
<ui-form-field
label="Deployment environment"
helperText="Production deployments require approval."
appearance="filled"
>
<select uiFormFieldControl [formControl]="environment">
<option value="development">Development</option>
<option value="staging">Staging</option>
<option value="production">Production</option>
</select>
</ui-form-field>API Reference
Inputs and outputs are semver-sensitive public API. Keep examples aligned with this table.
Inputs
id generated string Stable base ID used for the control, helper, and error relationships.
label '' string Visible or visually hidden accessible control label.
helperText '' string Supporting guidance described by the projected control.
errorText '' string Polite validation message shown and described when invalid.
appearance 'outline' 'outline' | 'filled' Control frame surface treatment.
size 'md' 'sm' | 'md' | 'lg' Control frame height, spacing, and type scale.
invalid false boolean Applies invalid visuals and aria-invalid to the projected control.
required false boolean Shows the required indicator and applies aria-required to the projected control.
disabled false boolean Applies disabled presentation and aria-disabled; consumers retain native/FormControl ownership.
hideLabel false boolean Visually hides the label while retaining its native association.
uiFormFieldControl required directive Registers the projected native or custom control for label, message, and state relationships.
uiFormFieldPrefix optional directive Marks leading content outside the editable control value.
uiFormFieldSuffix optional directive Marks trailing content outside the editable control value.
| Name | Type | Default | Description |
|---|---|---|---|
id | string | generated | Stable base ID used for the control, helper, and error relationships. |
label | string | '' | Visible or visually hidden accessible control label. |
helperText | string | '' | Supporting guidance described by the projected control. |
errorText | string | '' | Polite validation message shown and described when invalid. |
appearance | 'outline' | 'filled' | 'outline' | Control frame surface treatment. |
size | 'sm' | 'md' | 'lg' | 'md' | Control frame height, spacing, and type scale. |
invalid | boolean | false | Applies invalid visuals and aria-invalid to the projected control. |
required | boolean | false | Shows the required indicator and applies aria-required to the projected control. |
disabled | boolean | false | Applies disabled presentation and aria-disabled; consumers retain native/FormControl ownership. |
hideLabel | boolean | false | Visually hides the label while retaining its native association. |
uiFormFieldControl | directive | required | Registers the projected native or custom control for label, message, and state relationships. |
uiFormFieldPrefix | directive | optional | Marks leading content outside the editable control value. |
uiFormFieldSuffix | directive | optional | Marks trailing content outside the editable control value. |
Accessibility
- The native label targets the projected control using a consumer ID when present or a generated stable ID.
- Helper and active error IDs merge with pre-existing aria-describedby tokens instead of replacing them.
- Required, invalid, and disabled state are reflected through ARIA; consumers must also apply native or Angular Forms state to the real control.
Keyboard behavior
- Form Field adds no keyboard model; the projected control retains its native or custom interaction.
- Interactive suffix actions need their own accessible name and must not steal the control label.
Testing guidance
- Use UiFormFieldHarness to locate by label, read or set the projected value, inspect messages, and assert required, invalid, and disabled ARIA state.
- Test consumer IDs, generated IDs, pre-existing descriptions, helper-to-error switching, hidden labels, adornments, sizes, appearances, and missing-control rendering.