Form Field

Import

Import the FormField primitives from ng-primitives/form-field.

import {
  NgpFormField,
  NgpLabel,
  NgpDescription,
  NgpError,
  NgpFormControl,
} from 'ng-primitives/form-field';

Usage

Assemble the form-field directives in your template.

<div ngpFormField>
  <label ngpLabel>Label</label>
  <!-- Typically ngpFormControl would not be used directly, but a primitive like ngpInput would be used instead -->
  <input ngpFormControl />
  <p ngpDescription>Description</p>
  <p ngpError ngpErrorValidator="required">Error</p>
</div>

Reusable Component

Create a reusable component that uses the NgpFormField directive.

Schematics

Generate a reusable form-field component using the Angular CLI.

ng g ng-primitives:primitive form-field

Options

• path: The path at which to create the component file.
• prefix: The prefix to apply to the generated component selector.
• component-suffix: The suffix to apply to the generated component class name.
• file-suffix: The suffix to apply to the generated component file name. Defaults to component.
• styles: How component styles should be generated. css (default) includes the full example styles; unstyled omits them entirely so you can style the component yourself.
• example-styles (deprecated): still supported for compatibility - true maps to styles: css, false maps to styles: unstyled.

Examples

Control inside a child component

The form field reads the status and errors of the NgControl in its own template. When the control lives inside a child component, for example one chosen with @if or created with NgComponentOutlet, ngpFormControl registers its NgControl with the nearest form field, and the form field uses it as a fallback. A control in the form field's own template always takes precedence. A form field holds one control; in dev mode, a second registration logs a warning.

<!-- parent template -->
<div ngpFormField>
  <label ngpLabel>Name</label>
  <app-name-input [control]="name" />
  <p ngpError ngpErrorValidator="required">Name is required.</p>
</div>

<!-- app-name-input template -->
<input ngpFormControl [formControl]="control()" />

API Reference

The following directives are available to import from the ng-primitives/form-field package:

NgpFormField

NgpLabel

NgpDescription

NgpError

NgpFormControl

Accessibility

The label and description elements should be associated with the form control using the aria-labelledby and aria-describedby attributes, respectively. This will ensure that screen readers can provide the necessary context to users.

The form control exposes aria-invalid="true" to assistive technology once it is invalid and has been touched, so validation errors are not announced before the user has had a chance to interact with the field.