# Form Composition
`Watch` is convenient for a field that appears once, but repeating a render prop
doesn't scale past a couple of fields. For anything reused (a text input, an
address block, a line-item list, a submit button), build a named, typed
component around `useWatch` once and reuse it.
`watch` is convenient for a field that appears once, but repeating it doesn't
scale past a couple of fields. For anything reused (a text input, an address
block, a line-item list, a submit button), build a named custom element around
`WatchController` once and reuse it.
## Leaf fields: `TextField`, `NumberField`
[Basic](/form/guide/basic) builds `TextField` from scratch. `NumberField`
follows the same recipe, differing only in the input's markup and value parsing.
Once these exist, a form body reads as configuration rather than repeated
wiring:
```tsx
```
```lit
html`
`;
```
Both take an already-resolved `api: FieldApi` rather than
`parent`+`name`: the caller resolves the field (and its `validators`,
`dependents`, ...) once, at the call site, via `parent.field(name, options)`.
`TextField`/`NumberField` only need to know they're rendering _some_
`FieldApi`/`FieldApi`, not where in
the tree it lives or how it was configured.
Both take an already-resolved `.api: FieldApi` property rather
than `parent`+`name`: the caller resolves the field (and its `validators`,
`dependents`, ...) once, at the call site, via `parent.field(name, options)`.
`text-field`/`number-field` only need to know they're rendering _some_
`FieldApi`/`FieldApi`, not where in the tree
it lives or how it was configured.
## Nested fields: `AddressField`
A component composes fields (leaf or nested) under its own slice of the value,
as a resolved field. It doesn't need the dotted path leading to it, only that it
owns an `Address`:
```tsx
function AddressField(
{ api }: { api: FieldApi }
) {
return (
);
}
```
```lit
import { html, LitElement } from "lit";
import { customElement, property } from "lit/decorators.js";
import { type FieldApi } from "@kintools/form-lit";
import "./text-field.ts";
@customElement("address-field")
class AddressField extends LitElement {
@property({ attribute: false })
accessor api!: FieldApi;
override render() {
return html`
`;
}
}
// Usage.
html`
`;
```
### Reacting to the field's own state
`AddressField` above doesn't re-render when the passed-in `api` changes. To
re-render when something on that `api` changes, use `useWatch`:
`AddressField` above doesn't update when something on the passed-in `.api`
changes. To update when it does, use `WatchController`:
```tsx
function AddressField(
{ api }: { api: FieldApi },
) {
const [invalid, touched] = useWatch(
api,
(f) => [f.invalid, f.touched] as const,
);
return (
);
}
```
```lit
import { html, LitElement } from "lit";
import { customElement, property } from "lit/decorators.js";
import { type FieldApi, WatchController } from "@kintools/form-lit";
import "./text-field.ts";
@customElement("address-field")
class AddressField extends LitElement {
@property({ attribute: false })
accessor api!: FieldApi;
#watch = new WatchController(
this,
() => this.api,
(f) => [f.invalid, f.touched] as const,
);
override render() {
const [invalid, touched] = this.#watch.value;
return html`
`;
}
}
```
## Arrays: `ItemsField`
An array component composes the same way, plus array mutation helpers and a
stable React key. Use `field.id` (or `group.id`), not the array index, as the
`key`: index-as-key misattributes uncontrolled DOM state (focus, cursor
position) to the wrong row after a reorder, since the item that _renders_ at
index 2 changes but the component instance React reuses for index 2 doesn't:
An array component composes the same way, plus array mutation helpers and
`lit-html`'s
[`repeat`](https://lit.dev/docs/templates/lists/#the-repeat-directive)
directive, keyed on `field.id` (or `group.id`), not the array index:
index-as-key misattributes uncontrolled DOM state (focus, cursor position) to
the wrong row after a reorder, since the item that _renders_ at index 2 changes
but the element instance Lit reuses for index 2 doesn't:
```tsx
function ItemsField(
{ api }: { api: FieldApi },
) {
const value = useWatch(api, (g) => g.value);
return (
<>
{value.map((_, i) => {
const item = api.field(`${i}`);
return (
api.removeItem("", i)}
/>
);
})}
);
}
function ItemField(
{ item, onRemove }: {
item: FieldApi;
onRemove: () => void;
},
) {
return (
);
}
```
```lit
import { html, LitElement } from "lit";
import { customElement, property } from "lit/decorators.js";
import { repeat } from "lit/directives/repeat.js";
import { type FieldApi, WatchController } from "@kintools/form-lit";
import "./text-field.ts";
@customElement("items-field")
class ItemsField extends LitElement {
@property({ attribute: false })
accessor api!: FieldApi;
#watch = new WatchController(this, () => this.api, (g) => g.value);
override render() {
const value = this.#watch.value;
return html`
${repeat(
value,
(_item, i) => this.api.field(`${i}`).id,
(_item, i) => {
const item = this.api.field(`${i}`);
return html`
this.api.removeItem("", i)}
>
`;
},
)}
`;
}
}
@customElement("item-field")
class ItemField extends LitElement {
@property({ attribute: false })
accessor item!: FieldApi;
@property({ attribute: false })
accessor onRemove!: () => void;
override render() {
return html`
`;
}
}
```
`ItemsField` itself needs `useWatch(api, (g) => g.value)` to re-render when the
array changes; `api.field(i)` resolves the stable `item.id` without subscribing
to each item.
`ItemsField` itself needs a `select` of `(g) => g.value` to update when the
array changes; `api.field(i)` resolves the stable `item.id` without subscribing
to each item.
`Item` here is a nested object, so each element is decomposed into its own
`FieldApi` too, hence `ItemField` taking a resolved `item`. For a leaf item type
(e.g. `string[]`), the same `api.field(i)` call works unchanged: there's no
separate array-of-leaves API.
## `SubmitButton`
[Basic](/form/guide/basic) builds a `SubmitButton` that disables while
`submitting`. This one also disables while the form isn't `dirty` (nothing to
submit until something's changed), but the shape is the same:
`useWatch` directly, no render prop, so every form in the app agrees on when
submission is disabled:
`WatchController` directly, no `watch` directive, so every form in the app
agrees on when submission is disabled:
```tsx
function SubmitButton(
{ api, children }: { api: FormApi; children: React.ReactNode },
) {
const [submitting, dirty] = useWatch(
api,
(f) => [f.submitting, f.dirty] as const,
);
return (
);
}
```
```lit
import { html, LitElement } from "lit";
import { customElement, property } from "lit/decorators.js";
import { type FormApi, WatchController } from "@kintools/form-lit";
@customElement("submit-button")
class SubmitButton extends LitElement {
@property({ attribute: false })
accessor api!: FormApi;
#watch = new WatchController(
this,
() => this.api,
(f) => [f.submitting, f.dirty] as const,
);
override render() {
const [submitting, dirty] = this.#watch.value;
return html`
`;
}
}
```
## Putting it together
```tsx
function CheckoutForm() {
const form = useForm({
initialValue: {
email: "",
items: [],
shipping: emptyAddress,
},
onSubmit: async (form) => {
await placeOrder(form.value);
},
});
return (
);
}
```
```lit
import { html, LitElement } from "lit";
import { customElement } from "lit/decorators.js";
import { FormApi } from "@kintools/form-lit";
import { email, required } from "@kintools/form-validators";
import "./text-field.ts";
import "./address-field.ts";
import "./items-field.ts";
import "./submit-button.ts";
@customElement("checkout-form")
class CheckoutForm extends LitElement {
#form = new FormApi({
initialValue: {
email: "",
items: [],
shipping: emptyAddress,
},
onSubmit: async (form) => {
await placeOrder(form.value);
},
});
override render() {
return html`
`;
}
}
```
Reach for `` directly when prototyping or when a field appears once.
Promote to a named component the moment the same shape shows up twice.
Reach for `watch` directly when prototyping or when a field appears once.
Promote to a named custom element the moment the same shape shows up twice.