Developer Experience (DX)

Next, let's look at how developers use the Field. It has one API for every control, with the names the controls already use, it's typed end to end, and it does its work through attributes, so none of the controls needs to know it's there.

import { useState } from "react";
import { Field } from "@/components/Field";
import { Input } from "@/components/Input";

export function Newsletter() {
  const [email, setEmail] = useState("");
  const [error, setError] = useState("");

  return (
    <Field id="email" label="Email address" hint="We'll only send you the newsletter" error={error} required>
      <Input
        type="email"
        autoComplete="email"
        value={email}
        onChange={(event) => setEmail(event.target.value)}
        onBlur={() => setError(validateEmail(email))}
      />
    </Field>
  );
}

validateEmail stands in for your own check, which returns an error message, or an empty string when the address looks right.

Consistent

The Field's props are the ones the controls already have, or would have if they rendered their own label. These names mean the same thing everywhere in Open Components:

The Input, the Textarea, the Checkbox and the Switch don't have a label, hint or error prop, so that each of them stays one control that fits any layout, and the Field puts them together. The Field also leaves a few props out, on purpose:

• There's no optional prop, or a marker for required. Which fields to mark is a decision about the whole form, so it's words you put in the label, like "Company (optional)".
• There's no invalid prop. An invalid control needs a message that says what to fix, so error is what makes it invalid.
• There's no labelPosition. Where the label goes follows from the control, as under Controls, so every switch and every text control in a product looks the same.
• There's no name or value, and nothing to bind. They belong to the control, which the form reads.

Type-safe

Props and slots are typed, so your editor can autocomplete them and your type checker (tsc, vue-tsc, svelte-check, ngc or astro check) catches mistakes like size="medium".

The Field fires no events of its own, since it holds no state. Listen to the control, as you would without a Field. We also export FieldProps, which comes in handy for data-driven forms:

import type { FieldProps } from "@/components/Field";

const fields: (FieldProps & { name: string })[] = [
  { name: "email", label: "Email address", required: true },
  { name: "company", label: "Company (optional)" },
];

Composable

The Field doesn't render the control. You do, and the Field adds what links it to its label, hint and error: an id, aria-describedby, aria-invalid, required and disabled, which every control already puts on its native element, and size, which every control already takes as a prop. None of them needs a prop, a context or any code that knows about the Field, and their own pages still hold inside one.

How the Field hands them over follows each framework's idiom. In React and Vue, it adds them to the one element you put inside it. In Angular, the Field is a directive on its own <div>, which finds the native control inside it and sets them there, so give the native control its id, since a static attribute stays on the Field's own element. Vanilla writes them out.

In Svelte, Solid and Astro, whose children have already rendered by the time the Field could change them, it hands them to a snippet or a function, which spreads them onto the control. The Field can't read that control's props, so give the Field its id, and spread what it hands you after your own attributes only where you want the Field's to win.

What you set yourself is kept, with a few rules for when you and the Field both set the same thing:

• The Field's id wins over the control's, and the control's id, then its name, are used when the Field has none.
• aria-describedby is joined: the Field's hint and error first, then whatever you set on the control.
• aria-invalid comes from the Field while it has an error, and is yours otherwise. A Textarea over its limit stays invalid either way.
• size from the Field wins over the control's, and the Field takes the control's own when it has none. A native <input>, <textarea> or <select> doesn't get it, since its own size is a number of characters or rows.
• Around a Radio Group, the Field's hint and error win over the group's own. It's best to set each one in one place.

Forms

The Field adds no element that a form reads, so the control's name and value reach the form the way they always do, and your form library binds the control, not the Field. That also means the label, the hint and the error are in the server's markup, and the form works before your JavaScript loads.

The error is yours to set, from whatever decides it: your own checks as people leave a control, the browser's validity on submit, or a response from your server. You'll find the whole flow, with focus and a status message on a failed submit, under Check values when people leave or submit.

With other components

The Field works with every form control in Open Components, and sets the same things on each one, in its own way:

The Select, on our Roadmap, will work with the Field the same way.

Controllable

The Field has no state of its own. Its label, hint and error are props, so it shows exactly what you pass it, and the control keeps its value, bound or not, as on its own page. When the error goes away, the control's invalid state and description go with it, in the same render, so the three can't disagree.

DX Checklist

FAQ