# Signal Forms
Signal Forms are the recommended approach for handling forms in modern Angular applications (v21+). They provide a reactive, type-safe, and model-driven way to manage form state using Angular Signals.
**CRITICAL**: You MUST use Angular's new Signal Forms API for all form-related functionality. Do NOT use null as a value or type of any fields.
## Imports
You can import the following from `@angular/forms/signals`:
```ts
import {
form,
FormField,
submit,
// Rules for field state
disabled,
hidden,
readonly,
debounce,
// Schema helpers
applyWhen,
applyEach,
schema,
// Custom validation
validate,
validateHttp,
validateStandardSchema,
// Metadata
metadata,
} from '@angular/forms/signals';
```
## Creating a Form
Use the `form()` function with a Signal model. The structure of the form is derived directly from the model.
```ts
import {Component, signal} from '@angular/core';
import {form, FormField} from '@angular/forms/signals';
@Component({
// ...
imports: [FormField],
})
export class Example {
// 1. Define your model with initial values (avoid undefined)
userModel = signal({
name: '', // CRITICAL: NEVER use null or undefined as initial values
email: '',
age: 0, // Use 0 for numbers, NOT null
address: {
street: '',
city: '',
},
hobbies: [] as string[], // Use [] for arrays, NOT null
});
// WRONG - DO NOT DO THIS:
// badModel = signal({
// name: null, // ERROR: use '' instead
// age: null, // ERROR: use 0 instead
// items: null // ERROR: use [] instead
// });
// 2. Create the form
userForm = form(this.userModel);
}
```
## Validation
Import validators from `@angular/forms/signals`.
```ts
import {required, email, min, max, minLength, maxLength, pattern} from '@angular/forms/signals';
```
Use them in the schema function passed to `form()`:
```ts
userForm = form(this.userModel, (schemaPath) => {
// Required
required(schemaPath.name, {message: 'Name is required'});
// Conditional required.
required(schemaPath.name, {
when({valueOf}) {
return valueOf(schemaPath.age) > 10;
},
});
// when is only available for required
// Do NOT do this: pattern(p.name, /xxx/, {when /* ERROR */)
// Email
email(schemaPath.email, {message: 'Invalid email'});
// Min/Max for numbers
min(schemaPath.age, 18);
max(schemaPath.age, 100);
// MinLength/MaxLength for strings/arrays
minLength(schemaPath.password, 8);
maxLength(schemaPath.description, 500);
// Pattern (Regex)
pattern(schemaPath.zipCode, /^\d{5}$/);
});
```
## FieldState vs FormField: The Parental Requirement
It's important to understand the difference between **FormField** (the structure) and **FieldState** (the actual data/signals).
**RULE**: You must **CALL** a field as a function to access its state signals (valid, touched, dirty, hidden, etc.).
```ts
// f is a FormField (structural)
const f = form(signal({cat: {name: 'pirojok-the-cat', age: 5}}));
f.cat.name; // FormField: You can't get flags from here!
f.cat.name.touched(); // ERROR: touched() does not exist on FormField
f.cat.name(); // FieldState: Calling it gives you access to signals
f.cat.name().touched(); // VALID: Accessing the signal
f.cat().name.touched(); // ERROR: f.cat() is state, it doesn't have children!
```
Similarly in a template:
```html
@if (bookingForm.hotelDetails.hidden()) { ... }
@if (bookingForm.hotelDetails().hidden()) { ... }
```
## Disabled / Readonly / Hidden
Control field status using rules in the schema.
```ts
import {disabled, readonly, hidden} from '@angular/forms/signals';
userForm = form(this.userModel, (schemaPath) => {
// Conditionally disabled
disabled(schemaPath.password, ({valueOf}) => !valueOf(schemaPath.createAccount));
// Conditionally hidden (does NOT remove from model, just marks as hidden)
hidden(schemaPath.shippingAddress, ({valueOf}) => valueOf(schemaPath.sameAsBilling));
// Readonly
readonly(schemaPath.username);
});
```
## Binding
Import `FormField` and use the `[formField]` directive.
```ts
import {FormField} from '@angular/forms/signals';
```
All props on state, such as `disabled`, `hidden`, `readonly` and `name` are bound automatically.
Do _NOT_ bind the `name` field.
**CRITICAL: FORBIDDEN ATTRIBUTES**
When using `[formField]`, you MUST NOT set the following attributes in the template (either static or bound):
- `min`, `max` (Use validators in the schema instead)
- `value`, `[value]`, `[attr.value]` (Already handled by `[formField]`)
- `[attr.min]`, `[attr.max]`
- `[disabled]`, `[readonly]` (Already handled by `[formField]`)
Do NOT do this: `` or ``.
```html
```
## Reactive Forms
**Do NOT import** `FormControl`, `FormGroup`, `FormArray`, or `FormBuilder` from `@angular/forms`. Signal Forms replace these concepts entirely.
Signal forms does NOT have a builder.
## Accessing State
Each field in the form is a function that returns its state.
```ts
// Access the field by calling it
const emailState = this.userForm.email();
// Value (WritableSignal)
const value = this.userForm().value();
// Validation State (Signals)
const isValid = this.userForm().valid();
const isInvalid = this.userForm().invalid();
const errors = this.userForm().errors(); // Array of errors
const isPending = this.userForm().pending(); // Async validation pending
// Interaction State (Signals)
const isTouched = this.userForm().touched();
const isDirty = this.userForm().dirty();
// Availability State (Signals)
const isDisabled = this.userForm().disabled();
const isHidden = this.userForm().hidden();
const isReadonly = this.userForm().readonly();
```
IMPORTANT!: Make sure to call the field to get it state.
```ts
form().invalid()
form.field().dirty()
form.field.subfield().touched()
form.a.b.c.d().value()
form.address.ssn().pending()
form().reset()
// The only exception is length:
form.children.length
form.length // NOTE: no parenthesis!
form.client.addresses.length // No "()"
@for (income of form.addresses; track $index) {/**/}
```
## Submitting
Use the `submit()` function. It automatically marks all fields as touched before running the action.
**CRITICAL**: The callback to `submit()` MUST be `async` and MUST return a Promise.
```ts
import { submit } from '@angular/forms/signals';
// CORRECT - async callback
onSubmit() {
submit(this.userForm, async () => {
// This only runs if the form is valid
await this.apiService.save(this.userModel());
console.log('Saved!');
});
}
// WRONG - missing async keyword
onSubmit() {
submit(this.userForm, () => { // ERROR: must be async
console.log('Saved!');
});
}
```
## Handling Errors
`field().errors()` returns the errors array of ValidationError:
```ts
interface ValidationError {
readonly kind: string;
readonly message?: string;
}
```
Do _NOT_ return null from validators.
When there are no errors, return undefined
### Context
Functions passed to rules like `validate()`, `disabled()`, `applyWhen` take a context object. It is **CRITICAL** to understand its structure:
```ts
validate(
schemaPath.username,
({
value, // Signal: Writable current value of the field
fieldTree, // FieldTree: Sub-fields (if it's a group/array)
state, // FieldState: Access flags like state.valid(), state.dirty()
valueOf, // (path) => T: Read values of OTHER fields (tracking dependencies), e.g. valueOf(schemaPath.password)
stateOf, // (path) => FieldState: Access state (valid/dirty) of OTHER fields, e.g. stateOf(schemaPath.password).valid()
pathKeys, // Signal: Path from root to this field
}) => {
// WRONG: if (touched()) ... (touched is not in context)
// RIGHT: if (state.touched()) ...
if (value() === 'admin') {
return {kind: 'reserved', message: 'Username admin is reserved'};
}
},
);
```
### IMPORTANT: Paths are NOT Signals
Inside the `form()` callback, `schemaPath` and its children (e.g., `schemaPath.user.name`) are **NOT** signals and are **NOT** callable.
```ts
// WRONG - This will throw an error:
applyWhen(p.ssn, () => p.ssn().touched(), (ssnField) => { ... });
// RIGHT - Use stateOf() to get the state of a path:
applyWhen(p.ssn, ({ stateOf }) => stateOf(p.ssn).touched(), (ssnField) => { ... });
// RIGHT - Use valueOf() to get the value of a path:
applyWhen(p.ssn, ({ valueOf }) => valueOf(p.ssn) !== '', (ssnField) => { ... });
```
### Multiple Items
- Use `applyEach` for applying rules per item.
- **CRITICAL**: `applyEach` callback takes ONLY ONE argument (the item path), NOT two:
```ts
// CORRECT - single argument
applyEach(s.items, (item) => {
required(item.name);
});
// WRONG - do NOT pass index
applyEach(s.items, (item, index) => {
// ERROR: callback takes 1 argument
required(item.name);
});
```
- In the template use `@for` to iterate over the items.
- To remove an item from an array, just remove appropriate item from the array in the data.
- **`select` binding**: You CAN bind to `