# Typed names and handles

> Field names the compiler checks, and handles you can pass around.

Source: https://forms.lunarhue.dev/solid/composition/typed-paths

Every `name` prop is checked against the form's value type. A typo, or a
field the component can't edit, fails the build. For the parts of a form you
pass around, use a handle: a typed object for one field.

```tsx title="shipping.tsx"
import { createForm, createForms } from "@lunarhue/forms-solid";
import { TextField } from "./TextField";

const forms = createForms({ fields: { TextField } });

const order = forms.define({
  defaultValues: {
    shipping: { street: "", city: "" },
    billing: { street: "", city: "" },
  },
  onSubmit: (value) => value,
});

export default function ShippingForm() {
  const form = createForm(order, { id: "shipping" });
  // Handles: typed, stable objects for one part of the value.
  const shipping = form.root.at("shipping");
  const billing = form.root.at("billing");
  return (
    <form.Form>
      {(formProps) => (
        <form {...formProps}>
          {/* Names are dotted paths, checked against the value's type. */}
          <form.TextField name="shipping.street" label="Shipping street" />
          <form.TextField name="shipping.city" label="Shipping city" />
          <button type="button" onClick={() => billing.setValue(shipping.peek().value)}>
            Bill to the same address
          </button>
          {/* A handle works where a name does. */}
          <form.TextField handle={billing.at("street")} label="Billing street" />
          <form.TextField handle={billing.at("city")} label="Billing city" />
          <button type="submit">Save</button>
        </form>
      )}
    </form.Form>
  );
}
```

```tsx title="TextField.tsx"
import { type FieldApi, inputProps } from "@lunarhue/forms-solid";
import { For } from "solid-js";

interface TextFieldProps {
  readonly field: FieldApi<string>;
  readonly label: string;
}

export function TextField(props: TextFieldProps) {
  return (
    <div>
      <label for={props.field.id}>{props.label}</label>
      <input {...inputProps(props.field)} />
      <ul id={props.field.errorId}>
        <For each={props.field.shownErrors}>{(error) => <li>{error.message}</li>}</For>
      </ul>
    </div>
  );
}
```

## Names

A name is a dotted path through the value, such as `"shipping.city"`. With
the form above, a typo gets this:

```tsx
<form.TextField name="shipping.cty" label="City" />
```

```text
error TS2769: No overload matches this call.
  ...
    Type '"shipping.cty"' is not assignable to type '"billing.street"
    | "billing.city" | "shipping.street" | "shipping.city"'.
    Did you mean '"shipping.city"'?
```

The list holds only the names `TextField` can edit. `shipping` is a name too,
but its value is an object and `TextField` takes a `FieldApi<string>`, so it
isn't offered.

Names go through objects and stop at arrays. `tasks` names the array, but
there is no `tasks.0.title`. Rows are reached through
handles, see [Arrays](https://forms.lunarhue.dev/solid/plugins/arrays.md). A name has at most 8 segments.

## Handles

`form.root` is the handle of the whole value. `at(key)` returns a child's
handle, typed from the value, and also catches typos:

```ts
const shipping = form.root.at("shipping"); // handle to { street, city }
const city = shipping.at("city"); // handle to a string

form.root.at("shiping");
// Argument of type '"shiping"' is not assignable to parameter of type
// '"billing" | "shipping"'.
```

A handle holds no state. It is the same object on every call, it carries the
field's commands (`setValue`, `reset`, `validate`, `push` on arrays and so
on), and `peek()` reads the current snapshot in event handlers. Pass one as
`handle` instead of `name`:

```tsx
<form.TextField handle={form.root.at("shipping").at("city")} label="City" />
```

To render something from a handle's state, read it with
`createField(handle)`. Its members are reactive.

## Next

A component that renders a whole part of a form, such as an address, takes a
handle. [Fieldsets and scopes](https://forms.lunarhue.dev/solid/composition/fieldsets.md) types it.
