Field

A labelled form control with description and validation messages. Input is the control.

Installation

npx nuecrea-ui add field

Usage

import * as Field from '@/components/ui/field';
import { Input } from '@/components/ui/input';

export default function FieldStory() {
  return (
    <main className="grid max-w-sm gap-6">
      <Field.Root validationMode="onBlur">
        <Field.Label>Email</Field.Label>
        <Input type="email" required placeholder="you@example.com" />
        <Field.Description>
          We only use this for receipts.
        </Field.Description>
        <Field.Error match="valueMissing">
          Enter your email.
        </Field.Error>
        <Field.Error match="typeMismatch">
          Enter a valid email address.
        </Field.Error>
      </Field.Root>
      <Field.Root disabled>
        <Field.Label>Workspace</Field.Label>
        <Input defaultValue="Nuecrea" />
        <Field.Description>Managed by your admin.</Field.Description>
      </Field.Root>
    </main>
  );
}

API reference

Field.Root

Groups the parts and owns field state. Renders <div>.

PropTypeDefaultDescription
namestring—Name submitted with the form; overrides the control's name.
disabledbooleanfalseDisables the control and marks every part.
invalidbooleanfalseForces the invalid state, e.g. for server errors.
validationMode'onSubmit' | 'onBlur' | 'onChange'"onSubmit"When validation first runs. After that the field revalidates on every change.
Data attributePresent when
data-disabledthe field is disabled
data-validvalidated and valid
data-invalidvalidated and invalid, or forced invalid
data-dirtythe value differs from the initial value
data-touchedthe control has been blurred
data-filledthe control has a value
data-focusedthe control is focused

Field.Label

Labels the control (for / aria-labelledby). Renders <label>.

Data attributePresent when
data-disabledthe field is disabled
data-validvalidated and valid
data-invalidvalidated and invalid, or forced invalid
data-dirtythe value differs from the initial value
data-touchedthe control has been blurred
data-filledthe control has a value
data-focusedthe control is focused

Input

The text control. Uses native constraint validation; Angular also reads reactive and signal forms errors. Renders <input>.

PropTypeDefaultDescription
valuestring—Controlled value.
defaultValuestring—Initial value when uncontrolled.
disabledbooleanfalseDisables the input.
EventPayloadDescription
onValueChangestringFired on every input.
Data attributePresent when
data-disabledthe field is disabled
data-validvalidated and valid
data-invalidvalidated and invalid, or forced invalid
data-dirtythe value differs from the initial value
data-touchedthe control has been blurred
data-filledthe control has a value
data-focusedthe control is focused

Field.Description

Help text, referenced by aria-describedby. Renders <p>.

Data attributePresent when
data-disabledthe field is disabled
data-validvalidated and valid
data-invalidvalidated and invalid, or forced invalid
data-dirtythe value differs from the initial value
data-touchedthe control has been blurred
data-filledthe control has a value
data-focusedthe control is focused

Field.Error

Shown while the field is invalid and `match` applies; referenced by aria-describedby while shown. Renders <div>.

PropTypeDefaultDescription
matchboolean | 'valueMissing' | 'typeMismatch' | 'tooShort' | 'tooLong' | 'patternMismatch' | 'rangeUnderflow' | 'rangeOverflow' | 'stepMismatch' | 'badInput' | 'customError'—Which error shows this message. Unset or true: any. Angular also accepts forms error keys (required, email, minlength…).
Data attributePresent when
data-validanimating out after the field became valid
data-invalidvalidated and invalid, or forced invalid
data-dirtythe value differs from the initial value
data-touchedthe control has been blurred
data-filledthe control has a value
data-focusedthe control is focused
data-starting-styleanimating in
data-ending-styleanimating out