Field

Groups a label, form control, description, and validation message. Field wires accessible relationships between labels and controls, tracks focused, filled, dirty, touched, valid, and invalid states, and supports native and custom validation.

import { Field } from "@areia/slots";

document.querySelector("#root")!.innerHTML = `
  <div data-slot="field" class="grid w-72 gap-1">
    <label data-slot="field-label" class="font-bold">Email</label>
    <input
      data-slot="field-control"
      type="email"
      name="email"
      required
      class="win95-input"
    />
    <p data-slot="field-description" class="text-xs text-neutral-700">Use a work email address.</p>
    <div data-slot="field-error" class="text-xs text-red-800"></div>
  </div>
`;

const root = document.querySelector('[data-slot="field"]')!;
const controller = Field.createField(root, {
  name: "email",
  validationMode: "onBlur",
});

Import

import { Field } from "@areia/slots";

Usage

Add data-slot="field" to a container element and place the sub-slot elements inside. Call Field.createField(root) to initialize the controller.

import { Field } from "@areia/slots";

// Auto-bind a single root
const root = document.querySelector('[data-slot="field"]');
const controller = Field.createField(root, {
  name: "username",
  validationMode: "onBlur",
});

// Auto-bind all unbound roots in scope
const controllers = Field.create();

Expected Markup

The controller expects a root element with data-slot="field" and the following sub-slots.

<div data-slot="field">
  <label data-slot="field-label">Email</label>
  <input
    data-slot="field-control"
    type="email"
    name="email"
    required
  />
  <p data-slot="field-description">Use a work email address.</p>
  <div data-slot="field-error"></div>
  <output data-slot="field-validity"></output>
</div>

Data Slots

Generated Attributes

The controller writes the following attributes on initialization and updates them as state changes on the root and all sub-slot elements:

ARIA wiring applied by the controller:

• for / id association between labels and the control.
• aria-labelledby on the control referencing labels.
• aria-describedby on the control referencing descriptions and errors.
• aria-invalid on the control.

Events

Outbound

Inbound

API Reference

Options

Controller

FieldValidityData

Snapshot returned by controller.validity and controller.validate().

Controller

The controller is returned by Field.createField() and provides imperative control over the field's state.

import { Field } from "@areia/slots";

const root = document.querySelector('[data-slot="field"]');
const controller = Field.createField(root, {
  name: "email",
  validate: (value) =>
    value.includes("@") ? null : "Enter a valid email address.",
});

// Read state
console.log(
  controller.valid,
  controller.dirty,
  controller.filled,
);

// Validate on demand
const result = await controller.validate();
if (!result.valid) {
  console.error(result.errors);
}

// Force an error from server state
controller.setInvalid(true, "Email already taken.");

// Clear forced errors
controller.clearInvalid();

// Tear down
controller.destroy();

Form Reset

When the control is inside a <form>, the controller listens for reset events and resets dirty, touched, and validity state automatically.