Controlled fields

In Formisch for Angular, every field bound with the [formischControl] directive is controlled for you. This is different from our other framework packages, where you have to bind the value of the element yourself.

How it works

The directive writes the field's input into the element after every render in which the input changed. It knows the quirks of each element type, so it sets value on a text input, checked on a checkbox or radio, and the selected state of the options of a <select />.

<input
  *formischField="['firstName'] of form; let field"
  [formischControl]="field"
  type="text"
/>

That single binding is all you need for initial values, for programmatic updates via setInput, and for reset to be reflected in the UI. There is no [value], [checked] or [(ngModel)] to add — and you must not add them, because the directive already owns the element's value.

Writing happens in Angular's render write phase, after sibling DOM such as the options of a <select /> has been created. That ordering is what makes a select show the right option on first render.

The directive additionally keeps the element's name attribute and its aria-invalid attribute in sync, and registers the element with the field so that focus and the automatic focus of the first invalid field on submit work.

Reading the value

To render the current value somewhere else — a character counter, a preview, a summary — read the input signal of the field:

<ng-container *formischField="['bio'] of form; let field">
  <textarea [formischControl]="field"></textarea>
  <span>{{ field.input()?.length ?? 0 }} / 500</span>
</ng-container>

Because it is a signal, only the parts of your template that actually read it update when the value changes.

Setting the value

To change a field's value from your component class, you have two options:

• field.setInput(value) on the field store when you already have the field
• The setInput method when you only have the form store

readonly form = injectForm({ schema: ProfileSchema });

resetUsername(): void {
  setInput(this.form, { path: ['username'], input: '' });
}

Both update the field input and validate it like an input event would, so whether validation runs is controlled by your validate and revalidate config. The bound element follows automatically.

Fields without a native element

If you use a UI library whose components do not expose their underlying native element, you cannot apply the [formischControl] directive. In that case, control the field yourself by reading field.input() and writing back with field.setInput(…):

<ng-container *formischField="['country'] of form; let field">
  <ui-select [value]="field.input()" (valueChange)="field.setInput($event)" />
  @if (field.errors(); as errors) {
    <div>{{ errors[0] }}</div>
  }
</ng-container>

Note that a field controlled this way is not registered as an element of the form. Features that need a DOM element — focusing the first invalid field on submit, and the focus method — will skip it.

Numbers and dates

An <input type="number" /> and an <input type="date" /> both expose their value as a string, and that string is what Formisch stores. Let your schema do the conversion so the validated output has the type you want:

const ProfileSchema = v.object({
  // Input: string from the number input, output: number
  age: v.pipe(
    v.string(),
    v.nonEmpty('Please enter your age.'),
    v.transform(Number),
    v.minValue(18)
  ),
  // Input and output: 'yyyy-mm-dd' string from the date input
  birthday: v.pipe(v.string(), v.nonEmpty('Please enter your birthday.')),
});

This keeps the field input a plain string that the element can hold, while your submit handler receives the transformed value.

File inputs

The HTML <input type="file" /> element is an exception, because browsers do not allow a file selection to be set programmatically. Formisch can only clear it. You can, however, control the UI around it. For inspiration, check out our file input component from the playground.

Next steps

Now that you understand controlled fields, you can explore more advanced topics like nested fields and field arrays to handle complex form structures.