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.

Also, when creating a Signal Form, the resulting form structure (FieldTree) will match the shape of the Data Model.

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 field tree, 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:

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

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 { Field, 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: [Field, 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 [field] 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 FieldPath and defines the logic for it.

FieldPath<T> is an object that represents a location in the FieldTree form structure and is used to bind logic to a particular part of the structure prior to the creation of the form.

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

Field State

Based on the Field Logic we have defined using the Schema, we get the Field State. To access the state associated with a field, call it as a function as you can see in the following demo:

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
}
            

import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { disabled, Field, form, required, schema } 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;
}

@Component({
  selector: 'field-logic',
  templateUrl: './field-logic.html',
  imports: [Field, FormInspectorComponent, DemoLayout],
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class FieldLogic {
  protected readonly myForm = form(
    signal<MyDataModel>({
      firstName: 'Delete me',
      lastName: 'Disabled',
    }),
    schema<MyDataModel>((schemaPath) => {
      required(schemaPath.firstName);
      disabled(schemaPath.lastName, 'Last name cannot be changed');
    }),
  );
}

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: