Core Concepts

Data Model

One of the most important concepts in the Angular Signal Forms is the Data Model. Everything starts from there. When we create a Signal Form, it uses the Data Model as the source of truth for the values of the form fields. There is no internal copy of the data maintained from the Signals Forms library. That means that updating the Data Model will update automatically a form field's value. In the same way, changing the value of form field, will directly modify the Data Model.

When creating a Signal Form, a structured called FieldTree is returned which will match the shape of the Data Model.

The FieldTree is an important concept in Angular Signal Forms. It is a Proxy of an internal FieldNode structure and allows us to navigate to specific fields at runtime and access the derived state for each one of them. We will explore it more in the following sections.

To create a form, use the form function and pass the Data Model which should be a WritableSignal as an argument.

If the form() factory is not defined inside an injection context (e.g contructor), an injector can be passed in the form options object form(signal({username: ''}, {injector: this.injector}));

Binding form fields to UI elements

After defining the data model and generating the form's FieldTree, the next step is to bind each field to its corresponding UI element. Angular provides the Field directive to accomplish this.

A UI element can be one of the three:

This directive will:

1. Create a two way binding between the native UI element's value and the form field's value.
2. Synchronize the field state (disabled, touched, required, etc.) with the native UI element.

You can see how the Field directive is used in the HTML file of the following example:

value: {
  "firstName": "Stef",
  "lastName": "Modify me",
  "address": {
    "street": "123 Main St",
    "city": "Anytown"
  }
}

[]

[]

[]

meta: {
  "pattern": [],
  "required": false
}
            

value: "Stef"

[]

[]

[]

meta: {
  "pattern": [],
  "required": false
}
            

value: "Modify me"

[]

[]

[]

meta: {
  "pattern": [],
  "required": false
}
            

value: {
  "street": "123 Main St",
  "city": "Anytown"
}

[]

[]

[]

meta: {
  "pattern": [],
  "required": false
}
            

value: "123 Main St"

[]

[]

[]

meta: {
  "pattern": [],
  "required": false
}
            

value: "Anytown"

[]

[]

[]

meta: {
  "pattern": [],
  "required": false
}
            

import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { FormField, form } from '@angular/forms/signals';
import { FormInspectorComponent } from '../../../ui/form-inspector.ts/form-inspector';
import { DemoLayout } from '../../../ui/demo-layout/demo-layout';

interface MyDataModel {
  firstName: string;
  lastName: string;
  address: {
    street: string;
    city: string;
  };
}

@Component({
  selector: 'field-tree',
  templateUrl: './field-tree.html',
  imports: [FormField, FormInspectorComponent, DemoLayout],
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class FieldTree {
  protected readonly myForm = form(
    signal<MyDataModel>({
      firstName: 'Stef',
      lastName: 'Modify me',
      address: { street: '123 Main St', city: 'Anytown' },
    }),
  );
}

Field Logic

Now that every field node is synchronized with the corresponding UI element using the [formField] directive, we can add logic to it. We can add the follwing types of logic in our form fields.

To add logic like this to our form we need to use a Schema. In the Schema we declaretively define the logic of our form. You can think the Schema as a function that accepts a SchemaPath and defines the logic for it.

SchemaPath is an object that represents a location in the FieldTree structure. It is used within a Schema to bind logic (such as validation or disabled rules) to that location.

We explore the Field Logic topic in depth in the next page, with additional examples and detailed explanations.

Field State

Based on the logic we have defined using the Schema and the state derived from user actions (touched, dirty), we get the FieldState for every node in the FieldTree. To retrieve the FieldState, navigate to a node in the FieldTree and invoke it as a function.

- `form.username()` — returns the `FieldState` object for the `username` field
- `form.username().disabled()` — reads the value of the `disabled` signal
- `form.username().errors()` — reads the value of the validation errors signal

value: {
  "firstName": "Delete me",
  "lastName": "Disabled"
}

[]

[]

[]

meta: {
  "pattern": [],
  "required": false
}
            

value: "Delete me"

[]

[]

[]

meta: {
  "pattern": [],
  "required": true
}
            

value: "Disabled"

[
  {
    "message": "Last name cannot be changed"
  }
]

[]

[]

meta: {
  "pattern": [],
  "required": false
}
            

<demo-layout>
  <form class="demo">
    <div class="mb-2">
      <label class="input-label" for="firstName"> First Name </label>
      <input
        [formField]="myForm.firstName"
        class="input-field"
        id="firstName"
        type="text"
        placeholder="First Name"
        autocomplete="firstName"
      />
      @if (myForm.firstName().invalid()) {
        <p class="input-error">Required field</p>
      }
    </div>
    <div class="mb-2">
      <label class="input-label" for="lastName"> Last Name </label>
      <input
        [formField]="myForm.lastName"
        class="input-field"
        id="lastName"
        placeholder="Last Name"
        autocomplete="lastName"
      />
    </div>
  </form>
  <form-inspector class="inspector" [root]="myForm"></form-inspector>
</demo-layout>

The Field State includes the following state which is derived from the Field Logic. Here is a reference of all the available Field states we can get: