Component v1.1.0 Forms

Form Field

Composable label, message, adornment, and accessibility foundation for projected native or custom controls.

API Stable 2.1 WCAG notes Ready Dark mode
Selector
ui-form-field
Package
@ngnova/ui/form-field

Import

Standalone Tailwind v4
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.

API Reference

Workspace address field

Composable label, message, adornment, and accessibility foundation for projected native or custom controls.

.team

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.

Angular template ui-form-field-recipe.example.html
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.

Angular template ui-form-field-recipe.example.html
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.

Angular template ui-form-field-recipe.example.html
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.

Angular template ui-form-field-recipe.example.html
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.

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.