minLength()

🧭 API map

I want to…	Details
See every accepted call style	Signatures
See common and advanced usage	Usage and behavior
Customize messages	Message configuration
Understand reactive constraints	Reactive behavior
Return to the complete catalog	Built-in validators

📐 Signatures

minLength(minimum)
minLength(minimum, message)
minLength(minimum, options)

Reactive constraint arguments use a zero-argument function. The function may read signals and, where supported, return undefined to disable the constraint temporarily.

📖 Usage and behavior

Requires a numeric length or size to meet a minimum, including zero-length values:

min-length.example.ts

import { field, form, minLength, required } from '@ngblocks/form-nodes';

const profile = form({
  username: field('', [minLength(3)]),
  nickname: field<string>(null, [minLength(3)]),
  displayName: field('', [required, minLength(3)]),
});

profile.username(); // ''
profile.username.hasError('minLength'); // true
profile.nickname.valid(); // true: null has no length to check
profile.displayName.errors().map(error => error.kind); // ['required', 'minLength']

if (!profile.username.hasError('minLength') || !profile.nickname.valid()
  || profile.displayName.errors().map(error => error.kind).join(',') !== 'required,minLength') {
  throw new Error('Empty text must fail its minimum length, while null stays optional.');
}

profile.username.set('Ada');
profile.displayName.set('Ada');
profile.valid(); // true
if (!profile.valid()) throw new Error('Strings meeting the minimum must be valid.');

profile.nickname.set('');
profile.nickname.valid(); // false: clearing to an empty string differs from null
if (profile.nickname.valid()) throw new Error('An empty nickname must fail its minimum length.');

It supports strings, arrays, sets, maps, and other values with numeric length or size. null and undefined pass; empty strings and collections have length zero and fail a positive minimum. minLength(0) permits empty values. Whitespace is counted without trimming. Explicitly undefined-valued fields such as field<string>(undefined, [minLength(3)]) are also supported.

A failure is { kind: 'minLength', minLength, actual, message }. The resolved limit contributes to minLength() metadata, but does not mark the node as required.

Difference from Angular forms

Angular Reactive Forms and Signal Forms v22.1.6 skip empty strings in minLength. Form Nodes measures them, consistently with empty collections. Add required to reject nullish values too. An empty string with both validators produces both error kinds. See the migration guide.

Optional empty text

To allow either an empty string or a string meeting the minimum, make that exception explicit:

min-length-optional.example.ts

import { field, form, minLength } from '@ngblocks/form-nodes';

const profile = form({
  nickname: field('', [
    minLength(3, { when: ({ value }) => value() !== '' }),
  ]),
});

profile.nickname.valid(); // true: an empty nickname is explicitly allowed
if (!profile.valid()) throw new Error('An optional empty nickname must be valid.');

profile.nickname.set('Al');
profile.nickname.hasError('minLength'); // true
if (!profile.nickname.hasError('minLength')) throw new Error('A populated nickname must meet the minimum.');

profile.nickname.set('Alex');
profile.nickname.valid(); // true
if (!profile.valid()) throw new Error('A sufficiently long nickname must be valid.');

profile.nickname.set('');
profile.nickname.minLength(); // null: the inactive rule also removes its constraint metadata
if (!profile.valid() || profile.nickname.minLength() !== null) {
  throw new Error('Clearing an optional nickname must deactivate its length rule.');
}

While when is false, the rule contributes neither an error nor minimum-length metadata. This also removes this rule's contribution to the native minlength constraint on bound controls.

💬 Message configuration

Every failure has a default English message. Pass a string as the final argument or use an options object for a static or reactive message:

minLength(3, 'Enter at least three characters.')

A message function may read signals. Returning undefined continues through node, Angular provider, process-wide, and built-in message fallbacks. See Validator messages.

⚡ Reactive behavior

The minimum may be a signal or a zero-argument function. Changes revalidate even an empty string; returning undefined disables the constraint:

min-length-reactive.example.ts

import { signal } from '@angular/core';
import { field, form, minLength } from '@ngblocks/form-nodes';

const minimum = signal<number | undefined>(1);
const profile = form({
  nickname: field('', [minLength(minimum)]),
});

profile.nickname.valid(); // false
if (profile.valid()) throw new Error('Empty text must fail a positive minimum.');

minimum.set(0);
profile.nickname.valid(); // true
if (!profile.valid()) throw new Error('A zero minimum must allow empty text.');

minimum.set(3);
profile.nickname.getError('minLength')?.actual; // 0
if (!profile.nickname.hasError('minLength')) throw new Error('A changed minimum must revalidate empty text.');

minimum.set(undefined);
profile.nickname.valid(); // true: the constraint is disabled
if (!profile.valid() || profile.nickname.minLength() !== null) {
  throw new Error('An undefined minimum must disable validation and constraint metadata.');
}

Reactive constraint functions and message functions track the signals they read. When a resolved constraint becomes unavailable, validators that support optional constraint sources temporarily stop contributing their error and metadata.

The validator runs synchronously as part of its node's validator source. Disabled, readonly, and hidden nodes skip validation until they become interactive again.

For an inclusive range in one validator, use lengthBetween().

🔗 Related reference

• Built-in validators
• Validation
• validator()