@angular/forms
Version:
Angular - directives and services for creating forms
1,366 lines (1,354 loc) • 204 kB
TypeScript
/**
* @license Angular v20.3.9
* (c) 2010-2025 Google LLC. https://angular.dev/
* License: MIT
*/
import * as i0 from '@angular/core';
import { InjectionToken, Renderer2, ElementRef, OnDestroy, OnChanges, SimpleChanges, OnInit, Injector, EventEmitter, ChangeDetectorRef, AfterViewInit, Version, ModuleWithProviders } from '@angular/core';
import { Observable } from 'rxjs';
/**
* @description
*
* Adds `novalidate` attribute to all forms by default.
*
* `novalidate` is used to disable browser's native form validation.
*
* If you want to use native validation with Angular forms, just add `ngNativeValidate` attribute:
*
* ```html
* <form ngNativeValidate></form>
* ```
*
* @publicApi
* @ngModule ReactiveFormsModule
* @ngModule FormsModule
*/
declare class ɵNgNoValidate {
static ɵfac: i0.ɵɵFactoryDeclaration<ɵNgNoValidate, never>;
static ɵdir: i0.ɵɵDirectiveDeclaration<ɵNgNoValidate, "form:not([ngNoForm]):not([ngNativeValidate])", never, {}, {}, never, never, false, never>;
}
/**
* @description
* Defines an interface that acts as a bridge between the Angular forms API and a
* native element in the DOM.
*
* Implement this interface to create a custom form control directive
* that integrates with Angular forms.
*
* @see {@link DefaultValueAccessor}
*
* @publicApi
*/
interface ControlValueAccessor {
/**
* @description
* Writes a new value to the element.
*
* This method is called by the forms API to write to the view when programmatic
* changes from model to view are requested.
*
* @usageNotes
* ### Write a value to the element
*
* The following example writes a value to the native DOM element.
*
* ```ts
* writeValue(value: any): void {
* this._renderer.setProperty(this._elementRef.nativeElement, 'value', value);
* }
* ```
*
* @param obj The new value for the element
*/
writeValue(obj: any): void;
/**
* @description
* Registers a callback function that is called when the control's value
* changes in the UI.
*
* This method is called by the forms API on initialization to update the form
* model when values propagate from the view to the model.
*
* When implementing the `registerOnChange` method in your own value accessor,
* save the given function so your class calls it at the appropriate time.
*
* @usageNotes
* ### Store the change function
*
* The following example stores the provided function as an internal method.
*
* ```ts
* registerOnChange(fn: (_: any) => void): void {
* this._onChange = fn;
* }
* ```
*
* When the value changes in the UI, call the registered
* function to allow the forms API to update itself:
*
* ```ts
* host: {
* '(change)': '_onChange($event.target.value)'
* }
* ```
*
* @param fn The callback function to register
*/
registerOnChange(fn: any): void;
/**
* @description
* Registers a callback function that is called by the forms API on initialization
* to update the form model on blur.
*
* When implementing `registerOnTouched` in your own value accessor, save the given
* function so your class calls it when the control should be considered
* blurred or "touched".
*
* @usageNotes
* ### Store the callback function
*
* The following example stores the provided function as an internal method.
*
* ```ts
* registerOnTouched(fn: any): void {
* this._onTouched = fn;
* }
* ```
*
* On blur (or equivalent), your class should call the registered function to allow
* the forms API to update itself:
*
* ```ts
* host: {
* '(blur)': '_onTouched()'
* }
* ```
*
* @param fn The callback function to register
*/
registerOnTouched(fn: any): void;
/**
* @description
* Function that is called by the forms API when the control status changes to
* or from 'DISABLED'. Depending on the status, it enables or disables the
* appropriate DOM element.
*
* @usageNotes
* The following is an example of writing the disabled property to a native DOM element:
*
* ```ts
* setDisabledState(isDisabled: boolean): void {
* this._renderer.setProperty(this._elementRef.nativeElement, 'disabled', isDisabled);
* }
* ```
*
* @param isDisabled The disabled status to set on the element
*/
setDisabledState?(isDisabled: boolean): void;
}
/**
* Base class for all ControlValueAccessor classes defined in Forms package.
* Contains common logic and utility functions.
*
* Note: this is an *internal-only* class and should not be extended or used directly in
* applications code.
*/
declare class BaseControlValueAccessor {
private _renderer;
private _elementRef;
/**
* The registered callback function called when a change or input event occurs on the input
* element.
* @docs-private
*/
onChange: (_: any) => void;
/**
* The registered callback function called when a blur event occurs on the input element.
* @docs-private
*/
onTouched: () => void;
constructor(_renderer: Renderer2, _elementRef: ElementRef);
/**
* Helper method that sets a property on a target element using the current Renderer
* implementation.
* @docs-private
*/
protected setProperty(key: string, value: any): void;
/**
* Registers a function called when the control is touched.
* @docs-private
*/
registerOnTouched(fn: () => void): void;
/**
* Registers a function called when the control value changes.
* @docs-private
*/
registerOnChange(fn: (_: any) => {}): void;
/**
* Sets the "disabled" property on the range input element.
* @docs-private
*/
setDisabledState(isDisabled: boolean): void;
static ɵfac: i0.ɵɵFactoryDeclaration<BaseControlValueAccessor, never>;
static ɵdir: i0.ɵɵDirectiveDeclaration<BaseControlValueAccessor, never, never, {}, {}, never, never, true, never>;
}
/**
* Base class for all built-in ControlValueAccessor classes (except DefaultValueAccessor, which is
* used in case no other CVAs can be found). We use this class to distinguish between default CVA,
* built-in CVAs and custom CVAs, so that Forms logic can recognize built-in CVAs and treat custom
* ones with higher priority (when both built-in and custom CVAs are present).
*
* Note: this is an *internal-only* class and should not be extended or used directly in
* applications code.
*/
declare class BuiltInControlValueAccessor extends BaseControlValueAccessor {
static ɵfac: i0.ɵɵFactoryDeclaration<BuiltInControlValueAccessor, never>;
static ɵdir: i0.ɵɵDirectiveDeclaration<BuiltInControlValueAccessor, never, never, {}, {}, never, never, true, never>;
}
/**
* Used to provide a `ControlValueAccessor` for form controls.
*
* See `DefaultValueAccessor` for how to implement one.
*
* @publicApi
*/
declare const NG_VALUE_ACCESSOR: InjectionToken<readonly ControlValueAccessor[]>;
/**
* @description
* The `ControlValueAccessor` for writing select control values and listening to select control
* changes. The value accessor is used by the `FormControlDirective`, `FormControlName`, and
* `NgModel` directives.
*
* @usageNotes
*
* ### Using select controls in a reactive form
*
* The following examples show how to use a select control in a reactive form.
*
* {@example forms/ts/reactiveSelectControl/reactive_select_control_example.ts region='Component'}
*
* ### Using select controls in a template-driven form
*
* To use a select in a template-driven form, simply add an `ngModel` and a `name`
* attribute to the main `<select>` tag.
*
* {@example forms/ts/selectControl/select_control_example.ts region='Component'}
*
* ### Customizing option selection
*
* Angular uses object identity to select option. It's possible for the identities of items
* to change while the data does not. This can happen, for example, if the items are produced
* from an RPC to the server, and that RPC is re-run. Even if the data hasn't changed, the
* second response will produce objects with different identities.
*
* To customize the default option comparison algorithm, `<select>` supports `compareWith` input.
* `compareWith` takes a **function** which has two arguments: `option1` and `option2`.
* If `compareWith` is given, Angular selects option by the return value of the function.
*
* ```ts
* const selectedCountriesControl = new FormControl();
* ```
*
* ```html
* <select [compareWith]="compareFn" [formControl]="selectedCountriesControl">
* @for(country of countries; track $index) {
* <option[ngValue]="country">{{country.name}}</option>
* }
* </select>
*
* compareFn(c1: Country, c2: Country): boolean {
* return c1 && c2 ? c1.id === c2.id : c1 === c2;
* }
* ```
*
* **Note:** We listen to the 'change' event because 'input' events aren't fired
* for selects in IE, see:
* https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event#browser_compatibility
*
* @ngModule ReactiveFormsModule
* @ngModule FormsModule
* @publicApi
*/
declare class SelectControlValueAccessor extends BuiltInControlValueAccessor implements ControlValueAccessor {
/** @docs-private */
value: any;
/**
* @description
* Tracks the option comparison algorithm for tracking identities when
* checking for changes.
*/
set compareWith(fn: (o1: any, o2: any) => boolean);
private _compareWith;
private readonly appRefInjector;
private readonly destroyRef;
private readonly cdr;
private _queuedWrite;
/**
* Sets the "value" property on the select element.
* @docs-private
*/
writeValue(value: any): void;
/**
* Registers a function called when the control value changes.
* @docs-private
*/
registerOnChange(fn: (value: any) => any): void;
static ɵfac: i0.ɵɵFactoryDeclaration<SelectControlValueAccessor, never>;
static ɵdir: i0.ɵɵDirectiveDeclaration<SelectControlValueAccessor, "select:not([multiple])[formControlName],select:not([multiple])[formControl],select:not([multiple])[ngModel]", never, { "compareWith": { "alias": "compareWith"; "required": false; }; }, {}, never, never, false, never>;
}
/**
* @description
* Marks `<option>` as dynamic, so Angular can be notified when options change.
*
* @see {@link SelectControlValueAccessor}
*
* @ngModule ReactiveFormsModule
* @ngModule FormsModule
* @publicApi
*/
declare class NgSelectOption implements OnDestroy {
private _element;
private _renderer;
private _select;
/**
* @description
* ID of the option element
*/
id: string;
constructor(_element: ElementRef, _renderer: Renderer2, _select: SelectControlValueAccessor);
/**
* @description
* Tracks the value bound to the option element. Unlike the value binding,
* ngValue supports binding to objects.
*/
set ngValue(value: any);
/**
* @description
* Tracks simple string values bound to the option element.
* For objects, use the `ngValue` input binding.
*/
set value(value: any);
/** @docs-private */
ngOnDestroy(): void;
static ɵfac: i0.ɵɵFactoryDeclaration<NgSelectOption, [null, null, { optional: true; host: true; }]>;
static ɵdir: i0.ɵɵDirectiveDeclaration<NgSelectOption, "option", never, { "ngValue": { "alias": "ngValue"; "required": false; }; "value": { "alias": "value"; "required": false; }; }, {}, never, never, false, never>;
}
/**
* @description
* The `ControlValueAccessor` for writing multi-select control values and listening to multi-select
* control changes. The value accessor is used by the `FormControlDirective`, `FormControlName`, and
* `NgModel` directives.
*
* @see {@link SelectControlValueAccessor}
*
* @usageNotes
*
* ### Using a multi-select control
*
* The follow example shows you how to use a multi-select control with a reactive form.
*
* ```ts
* const countryControl = new FormControl();
* ```
*
* ```html
* <select multiple name="countries" [formControl]="countryControl">
* @for(country of countries; track $index) {
* <option [ngValue]="country">{{ country.name }}</option>
* }
* </select>
* ```
*
* ### Customizing option selection
*
* To customize the default option comparison algorithm, `<select>` supports `compareWith` input.
* See the `SelectControlValueAccessor` for usage.
*
* @ngModule ReactiveFormsModule
* @ngModule FormsModule
* @publicApi
*/
declare class SelectMultipleControlValueAccessor extends BuiltInControlValueAccessor implements ControlValueAccessor {
/**
* The current value.
* @docs-private
*/
value: any;
/**
* @description
* Tracks the option comparison algorithm for tracking identities when
* checking for changes.
*/
set compareWith(fn: (o1: any, o2: any) => boolean);
private _compareWith;
/**
* Sets the "value" property on one or of more of the select's options.
* @docs-private
*/
writeValue(value: any): void;
/**
* Registers a function called when the control value changes
* and writes an array of the selected options.
* @docs-private
*/
registerOnChange(fn: (value: any) => any): void;
static ɵfac: i0.ɵɵFactoryDeclaration<SelectMultipleControlValueAccessor, never>;
static ɵdir: i0.ɵɵDirectiveDeclaration<SelectMultipleControlValueAccessor, "select[multiple][formControlName],select[multiple][formControl],select[multiple][ngModel]", never, { "compareWith": { "alias": "compareWith"; "required": false; }; }, {}, never, never, false, never>;
}
/**
* @description
* Marks `<option>` as dynamic, so Angular can be notified when options change.
*
* @see {@link SelectMultipleControlValueAccessor}
*
* @ngModule ReactiveFormsModule
* @ngModule FormsModule
* @publicApi
*/
declare class ɵNgSelectMultipleOption implements OnDestroy {
private _element;
private _renderer;
private _select;
id: string;
constructor(_element: ElementRef, _renderer: Renderer2, _select: SelectMultipleControlValueAccessor);
/**
* @description
* Tracks the value bound to the option element. Unlike the value binding,
* ngValue supports binding to objects.
*/
set ngValue(value: any);
/**
* @description
* Tracks simple string values bound to the option element.
* For objects, use the `ngValue` input binding.
*/
set value(value: any);
/** @docs-private */
ngOnDestroy(): void;
static ɵfac: i0.ɵɵFactoryDeclaration<ɵNgSelectMultipleOption, [null, null, { optional: true; host: true; }]>;
static ɵdir: i0.ɵɵDirectiveDeclaration<ɵNgSelectMultipleOption, "option", never, { "ngValue": { "alias": "ngValue"; "required": false; }; "value": { "alias": "value"; "required": false; }; }, {}, never, never, false, never>;
}
/**
* @description
* Provide this token to control if form directives buffer IME input until
* the "compositionend" event occurs.
* @publicApi
*/
declare const COMPOSITION_BUFFER_MODE: InjectionToken<boolean>;
/**
* The default `ControlValueAccessor` for writing a value and listening to changes on input
* elements. The accessor is used by the `FormControlDirective`, `FormControlName`, and
* `NgModel` directives.
*
*
* @usageNotes
*
* ### Using the default value accessor
*
* The following example shows how to use an input element that activates the default value accessor
* (in this case, a text field).
*
* ```ts
* const firstNameControl = new FormControl();
* ```
*
* ```html
* <input type="text" [formControl]="firstNameControl">
* ```
*
* This value accessor is used by default for `<input type="text">` and `<textarea>` elements, but
* you could also use it for custom components that have similar behavior and do not require special
* processing. In order to attach the default value accessor to a custom element, add the
* `ngDefaultControl` attribute as shown below.
*
* ```html
* <custom-input-component ngDefaultControl [(ngModel)]="value"></custom-input-component>
* ```
*
* @ngModule ReactiveFormsModule
* @ngModule FormsModule
* @publicApi
*/
declare class DefaultValueAccessor extends BaseControlValueAccessor implements ControlValueAccessor {
private _compositionMode;
/** Whether the user is creating a composition string (IME events). */
private _composing;
constructor(renderer: Renderer2, elementRef: ElementRef, _compositionMode: boolean);
/**
* Sets the "value" property on the input element.
* @docs-private
*/
writeValue(value: any): void;
static ɵfac: i0.ɵɵFactoryDeclaration<DefaultValueAccessor, [null, null, { optional: true; }]>;
static ɵdir: i0.ɵɵDirectiveDeclaration<DefaultValueAccessor, "input:not([type=checkbox])[formControlName],textarea[formControlName],input:not([type=checkbox])[formControl],textarea[formControl],input:not([type=checkbox])[ngModel],textarea[ngModel],[ngDefaultControl]", never, {}, {}, never, never, false, never>;
}
/**
* @description
* The `ControlValueAccessor` for writing a number value and listening to number input changes.
* The value accessor is used by the `FormControlDirective`, `FormControlName`, and `NgModel`
* directives.
*
* @usageNotes
*
* ### Using a number input with a reactive form.
*
* The following example shows how to use a number input with a reactive form.
*
* ```ts
* const totalCountControl = new FormControl();
* ```
*
* ```html
* <input type="number" [formControl]="totalCountControl">
* ```
*
* @ngModule ReactiveFormsModule
* @ngModule FormsModule
* @publicApi
*/
declare class NumberValueAccessor extends BuiltInControlValueAccessor implements ControlValueAccessor {
/**
* Sets the "value" property on the input element.
* @docs-private
*/
writeValue(value: number): void;
/**
* Registers a function called when the control value changes.
* @docs-private
*/
registerOnChange(fn: (_: number | null) => void): void;
static ɵfac: i0.ɵɵFactoryDeclaration<NumberValueAccessor, never>;
static ɵdir: i0.ɵɵDirectiveDeclaration<NumberValueAccessor, "input[type=number][formControlName],input[type=number][formControl],input[type=number][ngModel]", never, {}, {}, never, never, false, never>;
}
/**
* @description
* The `ControlValueAccessor` for writing a range value and listening to range input changes.
* The value accessor is used by the `FormControlDirective`, `FormControlName`, and `NgModel`
* directives.
*
* @usageNotes
*
* ### Using a range input with a reactive form
*
* The following example shows how to use a range input with a reactive form.
*
* ```ts
* const ageControl = new FormControl();
* ```
*
* ```html
* <input type="range" [formControl]="ageControl">
* ```
*
* @ngModule ReactiveFormsModule
* @ngModule FormsModule
* @publicApi
*/
declare class RangeValueAccessor extends BuiltInControlValueAccessor implements ControlValueAccessor {
/**
* Sets the "value" property on the input element.
* @docs-private
*/
writeValue(value: any): void;
/**
* Registers a function called when the control value changes.
* @docs-private
*/
registerOnChange(fn: (_: number | null) => void): void;
static ɵfac: i0.ɵɵFactoryDeclaration<RangeValueAccessor, never>;
static ɵdir: i0.ɵɵDirectiveDeclaration<RangeValueAccessor, "input[type=range][formControlName],input[type=range][formControl],input[type=range][ngModel]", never, {}, {}, never, never, false, never>;
}
/**
* @description
* A `ControlValueAccessor` for writing a value and listening to changes on a checkbox input
* element.
*
* @usageNotes
*
* ### Using a checkbox with a reactive form.
*
* The following example shows how to use a checkbox with a reactive form.
*
* ```ts
* const rememberLoginControl = new FormControl();
* ```
*
* ```html
* <input type="checkbox" [formControl]="rememberLoginControl">
* ```
*
* @ngModule ReactiveFormsModule
* @ngModule FormsModule
* @publicApi
*/
declare class CheckboxControlValueAccessor extends BuiltInControlValueAccessor implements ControlValueAccessor {
/**
* Sets the "checked" property on the input element.
* @docs-private
*/
writeValue(value: any): void;
static ɵfac: i0.ɵɵFactoryDeclaration<CheckboxControlValueAccessor, never>;
static ɵdir: i0.ɵɵDirectiveDeclaration<CheckboxControlValueAccessor, "input[type=checkbox][formControlName],input[type=checkbox][formControl],input[type=checkbox][ngModel]", never, {}, {}, never, never, false, never>;
}
/**
* @description
* Defines the map of errors returned from failed validation checks.
*
* @publicApi
*/
type ValidationErrors = {
[key: string]: any;
};
/**
* @description
* An interface implemented by classes that perform synchronous validation.
*
* @usageNotes
*
* ### Provide a custom validator
*
* The following example implements the `Validator` interface to create a
* validator directive with a custom error key.
*
* ```ts
* @Directive({
* selector: '[customValidator]',
* providers: [{provide: NG_VALIDATORS, useExisting: forwardRef(() => CustomValidatorDirective), multi: true}]
* })
* class CustomValidatorDirective implements Validator {
* validate(control: AbstractControl): ValidationErrors|null {
* return {'custom': true};
* }
* }
* ```
*
* @publicApi
*/
interface Validator {
/**
* @description
* Method that performs synchronous validation against the provided control.
*
* @param control The control to validate against.
*
* @returns A map of validation errors if validation fails,
* otherwise null.
*/
validate(control: AbstractControl): ValidationErrors | null;
/**
* @description
* Registers a callback function to call when the validator inputs change.
*
* @param fn The callback function
*/
registerOnValidatorChange?(fn: () => void): void;
}
/**
* A base class for Validator-based Directives. The class contains common logic shared across such
* Directives.
*
* For internal use only, this class is not intended for use outside of the Forms package.
*/
declare abstract class AbstractValidatorDirective implements Validator, OnChanges {
private _validator;
private _onChange;
/** @docs-private */
ngOnChanges(changes: SimpleChanges): void;
/** @docs-private */
validate(control: AbstractControl): ValidationErrors | null;
/** @docs-private */
registerOnValidatorChange(fn: () => void): void;
/**
* @description
* Determines whether this validator should be active or not based on an input.
* Base class implementation checks whether an input is defined (if the value is different from
* `null` and `undefined`). Validator classes that extend this base class can override this
* function with the logic specific to a particular validator directive.
*/
enabled(input: unknown): boolean;
static ɵfac: i0.ɵɵFactoryDeclaration<AbstractValidatorDirective, never>;
static ɵdir: i0.ɵɵDirectiveDeclaration<AbstractValidatorDirective, never, never, {}, {}, never, never, true, never>;
}
/**
* A directive which installs the {@link MaxValidator} for any `formControlName`,
* `formControl`, or control with `ngModel` that also has a `max` attribute.
*
* @see [Form Validation](guide/forms/form-validation)
*
* @usageNotes
*
* ### Adding a max validator
*
* The following example shows how to add a max validator to an input attached to an
* ngModel binding.
*
* ```html
* <input type="number" ngModel max="4">
* ```
*
* @ngModule ReactiveFormsModule
* @ngModule FormsModule
* @publicApi
*/
declare class MaxValidator extends AbstractValidatorDirective {
/**
* @description
* Tracks changes to the max bound to this directive.
*/
max: string | number | null;
static ɵfac: i0.ɵɵFactoryDeclaration<MaxValidator, never>;
static ɵdir: i0.ɵɵDirectiveDeclaration<MaxValidator, "input[type=number][max][formControlName],input[type=number][max][formControl],input[type=number][max][ngModel]", never, { "max": { "alias": "max"; "required": false; }; }, {}, never, never, false, never>;
}
/**
* A directive which installs the {@link MinValidator} for any `formControlName`,
* `formControl`, or control with `ngModel` that also has a `min` attribute.
*
* @see [Form Validation](guide/forms/form-validation)
*
* @usageNotes
*
* ### Adding a min validator
*
* The following example shows how to add a min validator to an input attached to an
* ngModel binding.
*
* ```html
* <input type="number" ngModel min="4">
* ```
*
* @ngModule ReactiveFormsModule
* @ngModule FormsModule
* @publicApi
*/
declare class MinValidator extends AbstractValidatorDirective {
/**
* @description
* Tracks changes to the min bound to this directive.
*/
min: string | number | null;
static ɵfac: i0.ɵɵFactoryDeclaration<MinValidator, never>;
static ɵdir: i0.ɵɵDirectiveDeclaration<MinValidator, "input[type=number][min][formControlName],input[type=number][min][formControl],input[type=number][min][ngModel]", never, { "min": { "alias": "min"; "required": false; }; }, {}, never, never, false, never>;
}
/**
* @description
* An interface implemented by classes that perform asynchronous validation.
*
* @usageNotes
*
* ### Provide a custom async validator directive
*
* The following example implements the `AsyncValidator` interface to create an
* async validator directive with a custom error key.
*
* ```ts
* import { of } from 'rxjs';
*
* @Directive({
* selector: '[customAsyncValidator]',
* providers: [{provide: NG_ASYNC_VALIDATORS, useExisting: CustomAsyncValidatorDirective, multi:
* true}]
* })
* class CustomAsyncValidatorDirective implements AsyncValidator {
* validate(control: AbstractControl): Observable<ValidationErrors|null> {
* return of({'custom': true});
* }
* }
* ```
*
* @publicApi
*/
interface AsyncValidator extends Validator {
/**
* @description
* Method that performs async validation against the provided control.
*
* @param control The control to validate against.
*
* @returns A promise or observable that resolves a map of validation errors
* if validation fails, otherwise null.
*/
validate(control: AbstractControl): Promise<ValidationErrors | null> | Observable<ValidationErrors | null>;
}
/**
* @description
* A directive that adds the `required` validator to any controls marked with the
* `required` attribute. The directive is provided with the `NG_VALIDATORS` multi-provider list.
*
* @see [Form Validation](guide/forms/form-validation)
*
* @usageNotes
*
* ### Adding a required validator using template-driven forms
*
* ```html
* <input name="fullName" ngModel required>
* ```
*
* @ngModule FormsModule
* @ngModule ReactiveFormsModule
* @publicApi
*/
declare class RequiredValidator extends AbstractValidatorDirective {
/**
* @description
* Tracks changes to the required attribute bound to this directive.
*/
required: boolean | string;
/** @docs-private */
enabled(input: boolean): boolean;
static ɵfac: i0.ɵɵFactoryDeclaration<RequiredValidator, never>;
static ɵdir: i0.ɵɵDirectiveDeclaration<RequiredValidator, ":not([type=checkbox])[required][formControlName],:not([type=checkbox])[required][formControl],:not([type=checkbox])[required][ngModel]", never, { "required": { "alias": "required"; "required": false; }; }, {}, never, never, false, never>;
}
/**
* A Directive that adds the `required` validator to checkbox controls marked with the
* `required` attribute. The directive is provided with the `NG_VALIDATORS` multi-provider list.
*
* @see [Form Validation](guide/forms/form-validation)
*
* @usageNotes
*
* ### Adding a required checkbox validator using template-driven forms
*
* The following example shows how to add a checkbox required validator to an input attached to an
* ngModel binding.
*
* ```html
* <input type="checkbox" name="active" ngModel required>
* ```
*
* @publicApi
* @ngModule FormsModule
* @ngModule ReactiveFormsModule
*/
declare class CheckboxRequiredValidator extends RequiredValidator {
static ɵfac: i0.ɵɵFactoryDeclaration<CheckboxRequiredValidator, never>;
static ɵdir: i0.ɵɵDirectiveDeclaration<CheckboxRequiredValidator, "input[type=checkbox][required][formControlName],input[type=checkbox][required][formControl],input[type=checkbox][required][ngModel]", never, {}, {}, never, never, false, never>;
}
/**
* A directive that adds the `email` validator to controls marked with the
* `email` attribute. The directive is provided with the `NG_VALIDATORS` multi-provider list.
*
* The email validation is based on the WHATWG HTML specification with some enhancements to
* incorporate more RFC rules. More information can be found on the [Validators.email
* page](api/forms/Validators#email).
*
* @see [Form Validation](guide/forms/form-validation)
*
* @usageNotes
*
* ### Adding an email validator
*
* The following example shows how to add an email validator to an input attached to an ngModel
* binding.
*
* ```html
* <input type="email" name="email" ngModel email>
* <input type="email" name="email" ngModel email="true">
* <input type="email" name="email" ngModel [email]="true">
* ```
*
* @publicApi
* @ngModule FormsModule
* @ngModule ReactiveFormsModule
*/
declare class EmailValidator extends AbstractValidatorDirective {
/**
* @description
* Tracks changes to the email attribute bound to this directive.
*/
email: boolean | string;
/** @docs-private */
enabled(input: boolean): boolean;
static ɵfac: i0.ɵɵFactoryDeclaration<EmailValidator, never>;
static ɵdir: i0.ɵɵDirectiveDeclaration<EmailValidator, "[email][formControlName],[email][formControl],[email][ngModel]", never, { "email": { "alias": "email"; "required": false; }; }, {}, never, never, false, never>;
}
/**
* @description
* A function that receives a control and synchronously returns a map of
* validation errors if present, otherwise null.
*
* @publicApi
*/
interface ValidatorFn {
(control: AbstractControl): ValidationErrors | null;
}
/**
* @description
* A function that receives a control and returns a Promise or observable
* that emits validation errors if present, otherwise null.
*
* @publicApi
*/
interface AsyncValidatorFn {
(control: AbstractControl): Promise<ValidationErrors | null> | Observable<ValidationErrors | null>;
}
/**
* A directive that adds minimum length validation to controls marked with the
* `minlength` attribute. The directive is provided with the `NG_VALIDATORS` multi-provider list.
*
* @see [Form Validation](guide/forms/form-validation)
*
* @usageNotes
*
* ### Adding a minimum length validator
*
* The following example shows how to add a minimum length validator to an input attached to an
* ngModel binding.
*
* ```html
* <input name="firstName" ngModel minlength="4">
* ```
*
* @ngModule ReactiveFormsModule
* @ngModule FormsModule
* @publicApi
*/
declare class MinLengthValidator extends AbstractValidatorDirective {
/**
* @description
* Tracks changes to the minimum length bound to this directive.
*/
minlength: string | number | null;
static ɵfac: i0.ɵɵFactoryDeclaration<MinLengthValidator, never>;
static ɵdir: i0.ɵɵDirectiveDeclaration<MinLengthValidator, "[minlength][formControlName],[minlength][formControl],[minlength][ngModel]", never, { "minlength": { "alias": "minlength"; "required": false; }; }, {}, never, never, false, never>;
}
/**
* A directive that adds maximum length validation to controls marked with the
* `maxlength` attribute. The directive is provided with the `NG_VALIDATORS` multi-provider list.
*
* @see [Form Validation](guide/forms/form-validation)
*
* @usageNotes
*
* ### Adding a maximum length validator
*
* The following example shows how to add a maximum length validator to an input attached to an
* ngModel binding.
*
* ```html
* <input name="firstName" ngModel maxlength="25">
* ```
*
* @ngModule ReactiveFormsModule
* @ngModule FormsModule
* @publicApi
*/
declare class MaxLengthValidator extends AbstractValidatorDirective {
/**
* @description
* Tracks changes to the maximum length bound to this directive.
*/
maxlength: string | number | null;
static ɵfac: i0.ɵɵFactoryDeclaration<MaxLengthValidator, never>;
static ɵdir: i0.ɵɵDirectiveDeclaration<MaxLengthValidator, "[maxlength][formControlName],[maxlength][formControl],[maxlength][ngModel]", never, { "maxlength": { "alias": "maxlength"; "required": false; }; }, {}, never, never, false, never>;
}
/**
* @description
* A directive that adds regex pattern validation to controls marked with the
* `pattern` attribute. The regex must match the entire control value.
* The directive is provided with the `NG_VALIDATORS` multi-provider list.
*
* @see [Form Validation](guide/forms/form-validation)
*
* @usageNotes
*
* ### Adding a pattern validator
*
* The following example shows how to add a pattern validator to an input attached to an
* ngModel binding.
*
* ```html
* <input name="firstName" ngModel pattern="[a-zA-Z ]*">
* ```
*
* @ngModule ReactiveFormsModule
* @ngModule FormsModule
* @publicApi
*/
declare class PatternValidator extends AbstractValidatorDirective {
/**
* @description
* Tracks changes to the pattern bound to this directive.
*/
pattern: string | RegExp;
static ɵfac: i0.ɵɵFactoryDeclaration<PatternValidator, never>;
static ɵdir: i0.ɵɵDirectiveDeclaration<PatternValidator, "[pattern][formControlName],[pattern][formControl],[pattern][ngModel]", never, { "pattern": { "alias": "pattern"; "required": false; }; }, {}, never, never, false, never>;
}
/**
* FormArrayValue extracts the type of `.value` from a FormArray's element type, and wraps it in an
* array.
*
* Angular uses this type internally to support Typed Forms; do not use it directly. The untyped
* case falls back to any[].
*/
type ɵFormArrayValue<T extends AbstractControl<any>> = ɵTypedOrUntyped<T, Array<ɵValue<T>>, any[]>;
/**
* FormArrayRawValue extracts the type of `.getRawValue()` from a FormArray's element type, and
* wraps it in an array. The untyped case falls back to any[].
*
* Angular uses this type internally to support Typed Forms; do not use it directly.
*/
type ɵFormArrayRawValue<T extends AbstractControl<any>> = ɵTypedOrUntyped<T, Array<ɵRawValue<T>>, any[]>;
/**
* Tracks the value and validity state of an array of `FormControl`,
* `FormGroup` or `FormArray` instances.
*
* A `FormArray` aggregates the values of each child `FormControl` into an array.
* It calculates its status by reducing the status values of its children. For example, if one of
* the controls in a `FormArray` is invalid, the entire array becomes invalid.
*
* `FormArray` accepts one generic argument, which is the type of the controls inside.
* If you need a heterogenous array, use {@link UntypedFormArray}.
*
* `FormArray` is one of the four fundamental building blocks used to define forms in Angular,
* along with `FormControl`, `FormGroup`, and `FormRecord`.
*
* @usageNotes
*
* ### Create an array of form controls
*
* ```ts
* const arr = new FormArray([
* new FormControl('Nancy', Validators.minLength(2)),
* new FormControl('Drew'),
* ]);
*
* console.log(arr.value); // ['Nancy', 'Drew']
* console.log(arr.status); // 'VALID'
* ```
*
* ### Create a form array with array-level validators
*
* You include array-level validators and async validators. These come in handy
* when you want to perform validation that considers the value of more than one child
* control.
*
* The two types of validators are passed in separately as the second and third arg
* respectively, or together as part of an options object.
*
* ```ts
* const arr = new FormArray([
* new FormControl('Nancy'),
* new FormControl('Drew')
* ], {validators: myValidator, asyncValidators: myAsyncValidator});
* ```
*
* ### Set the updateOn property for all controls in a form array
*
* The options object is used to set a default value for each child
* control's `updateOn` property. If you set `updateOn` to `'blur'` at the
* array level, all child controls default to 'blur', unless the child
* has explicitly specified a different `updateOn` value.
*
* ```ts
* const arr = new FormArray([
* new FormControl()
* ], {updateOn: 'blur'});
* ```
*
* ### Adding or removing controls from a form array
*
* To change the controls in the array, use the `push`, `insert`, `removeAt` or `clear` methods
* in `FormArray` itself. These methods ensure the controls are properly tracked in the
* form's hierarchy. Do not modify the array of `AbstractControl`s used to instantiate
* the `FormArray` directly, as that result in strange and unexpected behavior such
* as broken change detection.
*
* @publicApi
*/
declare class FormArray<TControl extends AbstractControl<any> = any> extends AbstractControl<ɵTypedOrUntyped<TControl, ɵFormArrayValue<TControl>, any>, ɵTypedOrUntyped<TControl, ɵFormArrayRawValue<TControl>, any>> {
/**
* Creates a new `FormArray` instance.
*
* @param controls An array of child controls. Each child control is given an index
* where it is registered.
*
* @param validatorOrOpts A synchronous validator function, or an array of
* such functions, or an `AbstractControlOptions` object that contains validation functions
* and a validation trigger.
*
* @param asyncValidator A single async validator or array of async validator functions
*
*/
constructor(controls: Array<TControl>, validatorOrOpts?: ValidatorFn | ValidatorFn[] | AbstractControlOptions | null, asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null);
controls: ɵTypedOrUntyped<TControl, Array<TControl>, Array<AbstractControl<any>>>;
/**
* Get the `AbstractControl` at the given `index` in the array.
*
* @param index Index in the array to retrieve the control. If `index` is negative, it will wrap
* around from the back, and if index is greatly negative (less than `-length`), the result is
* undefined. This behavior is the same as `Array.at(index)`.
*/
at(index: number): ɵTypedOrUntyped<TControl, TControl, AbstractControl<any>>;
/**
* Insert a new `AbstractControl` at the end of the array.
*
* @param control Form control to be inserted
* @param options Specifies whether this FormArray instance should emit events after a new
* control is added.
* * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
* `valueChanges` observables emit events with the latest status and value when the control is
* inserted. When false, no events are emitted.
*
* NOTE: Pushing to the FormArray will not mark it dirty. If you want to mark if dirty, call `markAsDirty()`.
*/
push(control: TControl | Array<TControl>, options?: {
emitEvent?: boolean;
}): void;
/**
* Insert a new `AbstractControl` at the given `index` in the array.
*
* @param index Index in the array to insert the control. If `index` is negative, wraps around
* from the back. If `index` is greatly negative (less than `-length`), prepends to the array.
* This behavior is the same as `Array.splice(index, 0, control)`.
* @param control Form control to be inserted
* @param options Specifies whether this FormArray instance should emit events after a new
* control is inserted.
* * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
* `valueChanges` observables emit events with the latest status and value when the control is
* inserted. When false, no events are emitted.
*
* NOTE: Inserting to the FormArray will not mark it dirty. If you want to mark if dirty, call `markAsDirty()`.
*/
insert(index: number, control: TControl, options?: {
emitEvent?: boolean;
}): void;
/**
* Remove the control at the given `index` in the array.
*
* @param index Index in the array to remove the control. If `index` is negative, wraps around
* from the back. If `index` is greatly negative (less than `-length`), removes the first
* element. This behavior is the same as `Array.splice(index, 1)`.
* @param options Specifies whether this FormArray instance should emit events after a
* control is removed.
* * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
* `valueChanges` observables emit events with the latest status and value when the control is
* removed. When false, no events are emitted.
*
* NOTE: Removing the FormArray will not mark it dirty. If you want to mark if dirty, call `markAsDirty()`.
*/
removeAt(index: number, options?: {
emitEvent?: boolean;
}): void;
/**
* Replace an existing control.
*
* @param index Index in the array to replace the control. If `index` is negative, wraps around
* from the back. If `index` is greatly negative (less than `-length`), replaces the first
* element. This behavior is the same as `Array.splice(index, 1, control)`.
* @param control The `AbstractControl` control to replace the existing control
* @param options Specifies whether this FormArray instance should emit events after an
* existing control is replaced with a new one.
* * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
* `valueChanges` observables emit events with the latest status and value when the control is
* replaced with a new one. When false, no events are emitted.
*/
setControl(index: number, control: TControl, options?: {
emitEvent?: boolean;
}): void;
/**
* Length of the control array.
*/
get length(): number;
/**
* Sets the value of the `FormArray`. It accepts an array that matches
* the structure of the control.
*
* This method performs strict checks, and throws an error if you try
* to set the value of a control that doesn't exist or if you exclude the
* value of a control.
*
* @usageNotes
* ### Set the values for the controls in the form array
*
* ```ts
* const arr = new FormArray([
* new FormControl(),
* new FormControl()
* ]);
* console.log(arr.value); // [null, null]
*
* arr.setValue(['Nancy', 'Drew']);
* console.log(arr.value); // ['Nancy', 'Drew']
* ```
*
* @param value Array of values for the controls
* @param options Configure options that determine how the control propagates changes and
* emits events after the value changes
*
* * `onlySelf`: When true, each change only affects this control, and not its parent. Default
* is false.
* * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
* `valueChanges`
* observables emit events with the latest status and value when the control value is updated.
* When false, no events are emitted.
* The configuration options are passed to the {@link AbstractControl#updateValueAndValidity
* updateValueAndValidity} method.
*/
setValue(value: ɵFormArrayRawValue<TControl>, options?: {
onlySelf?: boolean;
emitEvent?: boolean;
}): void;
/**
* Patches the value of the `FormArray`. It accepts an array that matches the
* structure of the control, and does its best to match the values to the correct
* controls in the group.
*
* It accepts both super-sets and sub-sets of the array without throwing an error.
*
* @usageNotes
* ### Patch the values for controls in a form array
*
* ```ts
* const arr = new FormArray([
* new FormControl(),
* new FormControl()
* ]);
* console.log(arr.value); // [null, null]
*
* arr.patchValue(['Nancy']);
* console.log(arr.value); // ['Nancy', null]
* ```
*
* @param value Array of latest values for the controls
* @param options Configure options that determine how the control propagates changes and
* emits events after the value changes
*
* * `onlySelf`: When true, each change only affects this control, and not its parent. Default
* is false.
* * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
* `valueChanges` observables emit events with the latest status and value when the control
* value is updated. When false, no events are emitted. The configuration options are passed to
* the {@link AbstractControl#updateValueAndValidity updateValueAndValidity} method.
*/
patchValue(value: ɵFormArrayValue<TControl>, options?: {
onlySelf?: boolean;
emitEvent?: boolean;
}): void;
/**
* Resets the `FormArray` and all descendants are marked `pristine` and `untouched`, and the
* value of all descendants to null or null maps.
*
* You reset to a specific form state by passing in an array of states
* that matches the structure of the control. The state is a standalone value
* or a form state object with both a value and a disabled status.
*
* @usageNotes
* ### Reset the values in a form array
*
* ```ts
* const arr = new FormArray([
* new FormControl(),
* new FormControl()
* ]);
* arr.reset(['name', 'last name']);
*
* console.log(arr.value); // ['name', 'last name']
* ```
*
* ### Reset the values in a form array and the disabled status for the first control
*
* ```ts
* arr.reset([
* {value: 'name', disabled: true},
* 'last'
* ]);
*
* console.log(arr.value); // ['last']
* console.log(arr.at(0).status); // 'DISABLED'
* ```
*
* @param value Array of values for the controls
* @param options Configure options that determine how the control propagates changes and
* emits events after the value changes
*
* * `onlySelf`: When true, each change only affects this control, and not its parent. Default
* is false.
* * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
* `valueChanges`
* observables emit events with the latest status and value when the control is reset.
* When false, no events are emitted.
* The configuration options are passed to the {@link AbstractControl#updateValueAndValidity
* updateValueAndValidity} method.
*/
reset(value?: ɵTypedOrUntyped<TControl, ɵFormArrayValue<TControl>, any>, options?: {
onlySelf?: boolean;
emitEvent?: boolean;
}): void;
/**
* The aggregate value of the array, including any disabled controls.
*
* Reports all values regardless of disabled status.
*/
getRawValue(): ɵFormArrayRawValue<TControl>;
/**
* Remove all controls in the `FormArray`.
*
* @param options Specifies whether this FormArray instance should emit events after all
* controls are removed.
* * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
* `valueChanges` observables emit events with the latest status and value when all controls
* in this FormArray instance are removed. When false, no events are emitted.
*
* @usageNotes
* ### Remove all elements from a FormArray
*
* ```ts
* const arr = new FormArray([
* new FormControl(),
* new FormControl()
* ]);
* console.log(arr.length); // 2
*
* arr.clear();
* console.log(arr.length); // 0
* ```
*
* It's a simpler and more efficient alternative to removing all elements one by one:
*
* ```ts
* const arr = new FormArray([
* new FormControl(),
* new FormControl()
* ]);
*
* while (arr.length) {
* arr.removeAt(0);
* }
* ```
*/
clear(options?: {
emitEvent?: boolean;
}): void;
private _registerControl;
}
interface UntypedFormArrayCtor {
new (controls: AbstractControl[], validatorOrOpts?: ValidatorFn | ValidatorFn[] | AbstractControlOptions | null, asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null): UntypedFormArray;
/**
* The presence of an explicit `prototype` property provides backwards-compatibility for apps that
* manually inspect the prototype chain.
*/
prototype: FormArray<any>;
}
/**
* UntypedFormArray is a non-strongly-typed version of `FormArray`, which
* permits heterogenous controls.
*/
type UntypedFormArray = FormArray<any>;
declare const UntypedFormArray: UntypedFormArrayCtor;
/**
* @description
* Asserts that the given control is an instance of `FormArray`
*
* @see [Utility functions for narrowing form control types](guide/forms/reactive-forms#utility-functions-for-narrowing-form-control-types)
*
* @publicApi
*/
declare const isFormArray: (control: unknown) => control is FormArray;
/**
* FormControlState is a boxed form value. It is an object with a `value` key and a `disabled` key.
*
* @publicApi
*/
interface FormControlState<T> {
value: T;