@ngneat/reactive-forms

(Angular Reactive) Forms with Benefits 😉

How many times have you told yourself "I wish Angular Reactive Forms would support types", or "I really want API to query the form reactively. It missed some methods."

Your wish is my command! This library extends every Angular AbstractControl, and provides features that don't exist in the original one. It adds types, reactive queries, and helper methods. The most important thing is that you can start using it today! In most cases, the only thing that you need to change is the import path. So don't worry, no form refactoring required - we've got you covered; One schematics command, and you're done!

Let's take a look at all the neat things we provide:

🔮 Features

✅ Offers (almost) seamless FormControl, FormGroup, FormArray Replacement
✅ Allows Typed Forms!
✅ Provides Reactive Queries
✅ Provides Helpful Methods
✅ Typed and DRY ControlValueAccessor
✅ Typed FormBuilder
✅ Persist the form's state to local storage

👉 npm install @ngneat/reactive-forms

Table of Contents

• Control Type
• Control Queries
• Control Methods
• Control Errors
• Control Operators
• ControlValueAccessor
• Form Builder
• Persist Form
• ESLint Rule
• Migration
• Compatibility

Control Type

Each AbstractControl takes a generic, which can be neither the value type (all AbstractControls) or the type of the controls (FormGroup/FormArray). This type is than used to enhance every method exposed by Angular or this library. Use it with a FormControl:

import { FormControl } from '@ngneat/reactive-forms';

const control = new FormControl<string>('');
control.valueChanges.subscribe(value => {
  // value is typed as string
});

Use it with a FormArray:

import { FormArray, FormControl } from '@ngneat/reactive-forms';

const control = new FormArray<string>([new FormControl()]);

control.value$.subscribe(value => {
  // value is typed as string[]
});

Use it with a FormGroup:

import { FormGroup, FormControl } from '@ngneat/reactive-forms';

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

const profileForm = new FormGroup<Profile>({
  firstName: new FormControl(''),
  lastName: new FormControl(''),
  address: new FormGroup({
    street: new FormControl(''),
    city: new FormControl('')
  })
});

// typed as Profile
profileForm.setValue(new Profile());
// typed as Partial<Profile>
profileForm.patchValue({ firstName: 'Netanel' });

Or alternatively, with the controls as the generic type:

import { FormGroup, FormControl } from '@ngneat/reactive-forms';

interface ProfileControls {
  firstName: string; // Note that for primitive types the type "FormControl" is infered, so no need to write that.
  lastName: string;
  address: FormGroup<
    street: string,
    city: string,
  >;
}

const profileForm = new FormGroup<ProfileControls>({
  firstName: new FormControl(''),
  lastName: new FormControl(''),
  address: new FormGroup({
    street: new FormControl(''),
    city: new FormControl('')
  })
});

// typed as Profile
profileForm.setValue(new Profile());
// typed as Partial<Profile>
profileForm.patchValue({ firstName: 'Netanel' });

(Note supplying the controls type will enable you to access individual controls later with type inference, and avoid unneeded casting.)

Control Queries

value$

Observes the control's value. Unlike the behavior of the built-in valueChanges observable, it emits the current rawValue immediately (which means you'll also get the values of disabled controls).

import { FormControl } from '@ngneat/reactive-forms';

const control = new FormControl('');
control.value$.subscribe(value => ...);

disabled$

Observes the control's disable status.

import { FormControl } from '@ngneat/reactive-forms';

const control = new FormControl('');
control.disabled$.subscribe(isDisabled => ...);

enabled$

Observes the control's enable status.

import { FormControl } from '@ngneat/reactive-forms';

const control = new FormControl('');
control.enabled$.subscribe(isEnabled => ...);

status$

Observes the control's status.

import { FormControl } from '@ngneat/reactive-forms';

const control = new FormControl('');
control.status$.subscribe(status => ...);

The status is typed as ControlState (valid, invalid, pending or disabled).

touch$

Observes the control's touched status.

import { FormControl } from '@ngneat/reactive-forms';

const control = new FormControl('');
control.touch$.subscribe(isTouched => ...);

This emits a value only when markAsTouched, or markAsUnTouched, has been called.

dirty$

Observes the control's dirty status.

import { FormControl } from '@ngneat/reactive-forms';

const control = new FormControl('');
control.dirty$.subscribe(isDirty => ...);

This emits a value only when markAsDirty, or markAsPristine, has been called.

errors$

Observes the control's errors.

import { FormControl } from '@ngneat/reactive-forms';

const control = new FormControl('');
control.errors$.subscribe(errors => ...);

select()

Selects a slice of the form's state based on the given predicate.

import { FormGroup } from '@ngneat/reactive-forms';

const control = new FormGroup<Person>(...);
control.select(state => state.name).subscribe(name => ...)

Control Methods

setValue()

In addition to the built-in method functionality, it can also take an observable.

import { FormGroup } from '@ngneat/reactive-forms';

const control = new FormGroup<Person>();
control.setValue(query.select('formValue'));

patchValue()

In addition to the built-in method functionality, it can also take an observable.

import { FormGroup } from '@ngneat/reactive-forms';

const control = new FormGroup<Person>();
control.patchValue(query.select('formValue'));

disabledWhile()

Takes an observable that emits a boolean indicating whether to disable the control.

import { FormControl } from '@ngneat/reactive-forms';

const control = new FormControl('');
control.disabledWhile(query.select('isDisabled'));

enabledWhile()

Takes an observable that emits a boolean indicating whether to enable the control.

import { FormControl } from '@ngneat/reactive-forms';

const control = new FormControl('');
control.enabledWhile(query.select('isEnabled'));

mergeValidators()

Unlike the built-in setValidator() method, it persists any existing validators.

import { FormControl } from '@ngneat/reactive-forms';

const control = new FormControl('', Validators.required);
control.mergeValidators(Validators.minLength(2));
control.mergeAsyncValidators(...);

markAllAsDirty()

Marks all the group's controls as dirty.

import { FormGroup } from '@ngneat/reactive-forms';

const control = new FormGroup<Person>();
control.markAllAsDirty();

validateOn()

Takes an observable that emits a response, which is either null or an error object (ValidationErrors). The control's setErrors() method is called whenever the source emits.

const passwordValidator = combineLatest([
  this.signup.select(state => state.password),
  this.signup.select(state => state.repeatPassword)
]).pipe(
  map(([password, repeat]) => {
    return password === repeat
      ? null
      : {
          isEqual: false
        };
  })
);

this.signup.validateOn(passwordValidator);

hasErrorAndTouched()

A syntactic sugar method to be used in the template:

import { FormControl } from '@ngneat/reactive-forms';

this.control = new FormControl('', Validators.required);

<span *ngIf="control.hasErrorAndTouched('required')"></span>

hasErrorAndDirty()

A syntactic sugar method to be used in the template:

import { FormControl } from '@ngneat/reactive-forms';

this.control = new FormControl('', Validators.required);

<span *ngIf="control.hasErrorAndDirty('required')"></span>

setEnable()

Sets whether the control is enabled.

import { FormControl } from '@ngneat/reactive-forms';

const control = new FormControl('');
control.setEnable();
control.setEnable(false);

setDisable()

Sets whether the control is disabled.

import { FormControl } from '@ngneat/reactive-forms';

const control = new FormControl('');
control.setDisable();
control.setDisable(false);

getControl()

A method with typed parameters which obtains a reference to a specific control. When supplying the controls type, type inference for the returned control will be available for up to 2 keys in path. (Thus, for example getControl('a', 'b', 'c') will always return AbstractControl )

import { FormGroup } from '@ngneat/reactive-forms';

const group = new FormGroup<ProfileControls>(...);
const address: FormControl<string> = group.getControl('name');
const city: FormControl<string> = group.getControl('address', 'city');

Note that if you're only passing the "value" type (e.g. FormGroup<Profile>), this method will always return AbstractControl. In that case the return type might need to be inferred.

mergeErrors()

Merge validation errors. Unlike setErrors(), this will not overwrite errors already held by the control.

import { FormGroup } from '@ngneat/reactive-forms';

const group = new FormGroup<Profile>(...);
group.mergeErrors({ customError: true });

removeError()

Remove an error by key from the control.

import { FormGroup } from '@ngneat/reactive-forms';

const group = new FormGroup<Profile>(...);
group.removeError('customError');

FormArray methods

remove()

Remove a control from an array based on its value

import { FormArray } from '@ngneat/reactive-forms';

const array = new FormArray<string>(...);
// Remove empty strings
array.remove('')

removeIf()

Remove a control from an array based on a predicate

import { FormArray } from '@ngneat/reactive-forms';

const array = new FormArray<Profile>(...);
// Only keep addresses in NYC
array.removeIf((control) => control.get('address').get('city').value !== 'New York')

Control Path

The array path variation of hasError(), getError(), and get() is now typed:

const num = group.get(['phone', 'num']);
const hasError = group.hasError('required', ['phone', 'num']);
const getError = group.getError('required', ['phone', 'num']);

Control Errors

Each AbstractControl takes a second generic, which serves as the type of the errors:

type MyErrors = { isEqual: false };

const control = new FormControl<string, MyErrors>();
control.getError('isEqual'); // keyof MyErrors
control.hasError('isEqual'); // keyof MyErrors

// error type is MyErrors['isEqual']
const error = control.getError('isEqual'); // keyof MyErrors

The library provides a type for the built-in Angular validators types:

import { FormControl, NgValidatorsErrors } from '@ngneat/reactive-forms';

const control = new FormControl<string, NgValidatorsErrors>();

Control Operators

Each valueChanges or values$ takes an operator diff(), which emits only changed parts of form:

import { FormGroup, FormControl, diff } from '@ngneat/reactive-forms';

const control = new FormGroup<string>({
  name: new FormControl(''),
  phone: new FormGroup({
    num: new FormControl(),
    prefix: new FormControl()
  }),
  skills: new FormArray([])
});
control.value$
  .pipe(diff())
  .subscribe(value => {
    // value is emitted only if it has been changed, and only the changed parts.
  });

ControlValueAccessor

The library exposes a typed version of ControlValueAccessor, which already implements registerOnChange and registerOnTouched under the hood:

import { ControlValueAccessor } from '@ngneat/reactive-forms';

@Component({
  selector: 'my-checkbox',
  host: { '(change)': 'onChange($event.target.checked)', '(blur)': 'onTouched()' },
  providers: [
    {
      provide: NG_VALUE_ACCESSOR,
      useExisting: MyCheckboxComponent,
      multi: true
    }
  ]
})
export class MyCheckboxComponent extends ControlValueAccessor<boolean> {
  writeValue(value: boolean) {

  }

  // `this.onChange`, and `this.onTouched` are already here!
}

Note that you can also use it as interface.

Form Builder

We also introduce a typed version of FormBuilder which returns a typed FormGroup, FormControl and FormArray with all our sweet additions:

import { FormBuilder } from '@ngneat/reactive-forms';

const fb = new FormBuilder();
// Returns a FormGroup<{name: string, id: number}>
const group = fb.group({ name: 'ngneat', id: 1 });

interface User {
  userName: string;
  email: string;
}

// We'll get an error because "id" does not exist in type `User`
const userGroup: FormGroup<User> = fb.group({ id: 1, userName: 'User', email: 'Email' });

note: While the FormGroups/FormControls/etc created with our FormBuilder will have all additions, currently TS will not infer this, so one should still 'cast' them again on use:

const group = fb.group({
  userName: null,
  email: null
});

// will get TS error
group.controls.email.errors$.subscribe();

// will not get TS error
(group.controls.email as FormControl<string>).errors$.subscribe();

Persist Form

Automatically persist the FormGroup's value to the given storage:

const group = new FormGroup<Profile>();
const unsubscribe = group.persist('profile').subscribe();

The persist function will also set the FromGroup value to the latest state available in the storage before subscribing to value changes.

PersistOptions

Change the target storage or debounceTime value by providing options as a second argument in the persist function call.

Option	Description	Default
debounceTime	Update delay in ms between value changes	250
manager	A manager implementing the PersistManager interface	LocalStorageManager
arrControlFactory	Factory functions for FormArray
persistDisabledControls	Defines whether values of disabled controls should be persisted	false

By default the library provides LocalStorageManager and SessionStorageManager. It's possible to store the form value into a custom storage. Just implement the PersistManager interface, and use it when calling the persist function.

export class StateStoreManager<T> implements PersistManager<T> {
  setValue(key: string, data: T) {
     ...
  }

  getValue(key: string) {
    ...
  }
}

export class FormComponent implements OnInit {
  group = new FormGroup<Profile>();

  ngOnInit() {
    this.group.persist('profile', { manager: new StateStoreManager() }).subscribe();
  }
}

Using FormArray Controls.

When working with a FormArray, it's required to pass a factory function that defines how to create the controls inside the FormArray.

interface Profile {
  skills: string[];
}

const group = new FormGroup<Profile>({
  skills: new FormArray([])
});

group.persist('profile', {
  arrControlFactory: {
     skills: value => new FormControl(value)
  }
});

Because the form is strongly typed, you can only configure factories for properties that are of type Array. The library makes it also possible to correctly infer the type of value for the factory function.

ESLint Rule

We provide a special lint rule that forbids the imports of any token we expose, such as the following: AbstractControl, AsyncValidatorFn, ControlValueAccessor, FormArray, FormBuilder, FormControl, FormGroup, ValidatorFn, from @angular/forms.

Check out the documentation.

Migration

The command will replace entities coming from @angular/reactive-forms with @ngneat/reactive-forms.

ng g @ngneat/reactive-forms:migrate

Further information about the script can be found here.

Compatibility

Reactive-forms is compatible with Angular versions 8 and later.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Netanel Basal 💻 📖 🤔 🚇	Colum Ferry 💻 📖	Dan Roujinsky 💻 📖 🤔	Inbal Sinai 📖	Itay Oded 💻 🤔 📖 ⚠️ 🔧	tehshin 💻 📖	Mario Arnautou 💻
Har-Shuv 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

Changelog

1.6.1 (2021-03-14)

Bug Fixes

• 🐛 expose diff operator (3fc264e), closes #83