# Reactive Forms _Reactive forms_ is an Angular technique for creating forms in a _reactive_ style. This guide explains reactive forms as you follow the steps to build a "Hero Detail Editor" form. {@a toc} Try the Reactive Forms live-example. You can also run the Reactive Forms Demo version and choose one of the intermediate steps from the "demo picker" at the top. {@a intro} ## Introduction to Reactive Forms Angular offers two form-building technologies: _reactive_ forms and _template-driven_ forms. The two technologies belong to the `@angular/forms` library and share a common set of form control classes. But they diverge markedly in philosophy, programming style, and technique. They even have their own modules: the `ReactiveFormsModule` and the `FormsModule`. ### Reactive forms Angular _reactive_ forms facilitate a _reactive style_ of programming that favors explicit management of the data flowing between a non-UI _data model_ (typically retrieved from a server) and a UI-oriented _form model_ that retains the states and values of the HTML controls on screen. Reactive forms offer the ease of using reactive patterns, testing, and validation. With _reactive_ forms, you create a tree of Angular form control objects in the component class and bind them to native form control elements in the component template, using techniques described in this guide. You create and manipulate form control objects directly in the component class. As the component class has immediate access to both the data model and the form control structure, you can push data model values into the form controls and pull user-changed values back out. The component can observe changes in form control state and react to those changes. One advantage of working with form control objects directly is that value and validity updates are [always synchronous and under your control](guide/reactive-forms#async-vs-sync "Async vs sync"). You won't encounter the timing issues that sometimes plague a template-driven form and reactive forms can be easier to unit test. In keeping with the reactive paradigm, the component preserves the immutability of the _data model_, treating it as a pure source of original values. Rather than update the data model directly, the component extracts user changes and forwards them to an external component or service, which does something with them (such as saving them) and returns a new _data model_ to the component that reflects the updated model state. Using reactive form directives does not require you to follow all reactive priniciples, but it does facilitate the reactive programming approach should you choose to use it. ### Template-driven forms _Template-driven_ forms, introduced in the [Template guide](guide/forms), take a completely different approach. You place HTML form controls (such as `` and `` element for the hero name. A `FormControl` constructor accepts three, optional arguments: the initial data value, an array of validators, and an array of async validators.
This simple control doesn't have data or validators. In real apps, most form controls have both. For in-depth information on `Validators`, see the [Form Validation](guide/form-validation) guide.
{@a create-template} ## Create the template Now update the component's template with the following markup. To let Angular know that this is the input that you want to associate to the `name` `FormControl` in the class, you need `[formControl]="name"` in the template on the ``.
Disregard the `form-control` CSS class. It belongs to the Bootstrap CSS library, not Angular, and styles the form but in no way impacts the logic.
{@a import} ## Import the `ReactiveFormsModule` The `HeroDetailComponent` template uses the `formControlName` directive from the `ReactiveFormsModule`. Do the following two things in `app.module.ts`: 1. Use a JavaScript `import` statement to access the `ReactiveFormsModule`. 1. Add `ReactiveFormsModule` to the `AppModule`'s `imports` list. {@a update} ## Display the `HeroDetailComponent` Revise the `AppComponent` template so it displays the `HeroDetailComponent`. {@a essentials} ## Essential form classes This guide uses four fundamental classes to build a reactive form:
Class Description
AbstractControl [`AbstractControl`](api/forms/AbstractControl "API Reference: FormControl") is the abstract base class for the three concrete form control classes; `FormControl`, `FormGroup`, and `FormArray`. It provides their common behaviors and properties.
FormControl [`FormControl`](api/forms/FormControl "API Reference: FormControl") tracks the value and validity status of an individual form control. It corresponds to an HTML form control such as an `` or `
FormGroup [`FormGroup`](api/forms/FormGroup "API Reference: FormGroup") tracks the value and validity state of a group of `AbstractControl` instances. The group's properties include its child controls. The top-level form in your component is a `FormGroup`.
FormArray [`FormArray`](api/forms/FormArray "API Reference: FormArray") tracks the value and validity state of a numerically indexed array of `AbstractControl` instances.
## Style the app To use the bootstrap CSS classes that are in the template HTML of both the `AppComponent` and the `HeroDetailComponent`, add the `bootstrap` CSS stylesheet to the head of `styles.css`: Now that everything is wired up, serve the app with: ng serve The browser should display something like this:
Single FormControl
{@a formgroup} ## Add a FormGroup Usually, if you have multiple `FormControls`, you register them within a parent `FormGroup`. To add a `FormGroup`, add it to the imports section of `hero-detail.component.ts`: In the class, wrap the `FormControl` in a `FormGroup` called `heroForm` as follows: Now that you've made changes in the class, they need to be reflected in the template. Update `hero-detail.component.html` by replacing it with the following. Notice that now the single `` is in a `
` element. `formGroup` is a reactive form directive that takes an existing `FormGroup` instance and associates it with an HTML element. In this case, it associates the `FormGroup` you saved as `heroForm` with the `` element. Because the class now has a `FormGroup`, you must update the template syntax for associating the `` with the corresponding `FormControl` in the component class. Without a parent `FormGroup`, `[formControl]="name"` worked earlier because that directive can stand alone, that is, it works without being in a `FormGroup`. With a parent `FormGroup`, the `name` `` needs the syntax `formControlName=name` in order to be associated with the correct `FormControl` in the class. This syntax tells Angular to look for the parent `FormGroup`, in this case `heroForm`, and then _inside_ that group to look for a `FormControl` called `name`. {@a json} ## Taking a look at the form model When the user enters data into an ``, the value goes into the **_form model_**. To see the form model, add the following line after the closing `` tag in the `hero-detail.component.html`: The `heroForm.value` returns the _form model_. Piping it through the `JsonPipe` renders the model as JSON in the browser:
JSON output
The initial `name` property value is the empty string. Type into the name `` and watch the keystrokes appear in the JSON. In real life apps, forms get big fast. `FormBuilder` makes form development and maintenance easier. {@a formbuilder} ## Introduction to `FormBuilder` The `FormBuilder` class helps reduce repetition and clutter by handling details of control creation for you. To use `FormBuilder`, import it into `hero-detail.component.ts`. You can remove `FormControl`: Use it to refactor the `HeroDetailComponent` into something that's easier to read and write, by following this plan: * Explicitly declare the type of the `heroForm` property to be `FormGroup`; you'll initialize it later. * Inject a `FormBuilder` into the constructor. * Add a new method that uses the `FormBuilder` to define the `heroForm`; call it `createForm()`. * Call `createForm()` in the constructor. The revised `HeroDetailComponent` looks like this: `FormBuilder.group` is a factory method that creates a `FormGroup`.   `FormBuilder.group` takes an object whose keys and values are `FormControl` names and their definitions. In this example, the `name` control is defined by its initial data value, an empty string. Defining a group of controls in a single object makes your code more compact and readable because you don't have to write repeated `new FormControl(...)` statements. {@a validators} ### `Validators.required` Though this guide doesn't go deeply into validations, here is one example that demonstrates the simplicity of using `Validators.required` in reactive forms. First, import the `Validators` symbol. To make the `name` `FormControl` required, replace the `name` property in the `FormGroup` with an array. The first item is the initial value for `name`; the second is the required validator, `Validators.required`.
Reactive validators are simple, composable functions. Configuring validation is different in template-driven forms in that you must wrap validators in a directive.
Update the diagnostic message at the bottom of the template to display the form's validity status. The browser displays the following:
Single FormControl
`Validators.required` is working. The status is `INVALID` because the `` has no value. Type into the `` to see the status change from `INVALID` to `VALID`. In a real app, you'd replace the diagnosic message with a user-friendly experience. Using `Validators.required` is optional for the rest of the guide. It remains in each of the following examples with the same configuration. For more on validating Angular forms, see the [Form Validation](guide/form-validation) guide. ### More `FormControl`s This section adds additional `FormControl`s for the address, a super power, and a sidekick. Additionally, the address has a state property. The user will select a state with a `` elements, a ``. To make this change visually obvious, add an `

` header near the top with the text, _Secret Lair_. The new address HTML looks like this: After these changes, the JSON output in the browser shows the revised form model with the nested address `FormGroup`:
JSON output
This shows that the template and the form model are talking to one another. {@a properties} ## Inspect `FormControl` Properties You can inspect an individual `FormControl` within a form by extracting it with the `get()` method. You can do this within the component class or display it on the page by adding the following to the template, immediately after the `{{form.value | json}}` interpolation as follows: To get the state of a `FormControl` that’s inside a `FormGroup`, use dot notation to traverse to the control.
*Note*: If you're coding along, remember to remove this reference to `address.street` when you get to the section on `FormArray`. In that section, you change the name of address in the component class and it will throw an error if you leave it in the template.
You can use this technique to display any property of a `FormControl` such as one of the following:
Property Description
myControl.value the value of a `FormControl`.
myControl.status the validity of a `FormControl`. Possible values: `VALID`, `INVALID`, `PENDING`, or `DISABLED`.
myControl.pristine `true` if the user has _not_ changed the value in the UI. Its opposite is `myControl.dirty`.
myControl.untouched `true` if the control user has not yet entered the HTML control and triggered its blur event. Its opposite is `myControl.touched`.
Read about other `FormControl` properties in the [_AbstractControl_](api/forms/AbstractControl) API reference. One common reason for inspecting `FormControl` properties is to make sure the user entered valid values. Read more about validating Angular forms in the [Form Validation](guide/form-validation) guide. {@a data-model-form-model} ## The data model and the form model At the moment, the form is displaying empty values. The `HeroDetailComponent` should display values of a hero, possibly a hero retrieved from a remote server. In this app, the `HeroDetailComponent` gets its hero from a parent `HeroListComponent`. The `hero` from the server is the **_data model_**. The `FormControl` structure is the **_form model_**. The component must copy the hero values in the data model into the form model. There are two important implications: 1. The developer must understand how the properties of the data model map to the properties of the form model. 2. User changes flow from the DOM elements to the form model, not to the data model. The form controls never update the _data model_. The form and data model structures don't need to match exactly. You often present a subset of the data model on a particular screen. But it makes things easier if the shape of the form model is close to the shape of the data model. In this `HeroDetailComponent`, the two models are quite close. Here are the definitions of `Hero` and `Address` in `data-model.ts`: Here, again, is the component's `FormGroup` definition. There are two significant differences between these models: 1. The `Hero` has an `id`. The form model does not because you generally don't show primary keys to users. 1. The `Hero` has an array of addresses. This form model presents only one address, which is covered in the section on [`FormArray`](guide/reactive-forms#form-array "Form arrays") below. Keeping the two models close in shape facilitates copying the data model properties to the form model with the `patchValue()` and `setValue()` methods in the next section. First, refactor the `address` `FormGroup` definition as follows: Also be sure to update the `import` from `data-model` so you can reference the `Hero` and `Address` classes: {@a set-data} ## Populate the form model with `setValue()` and `patchValue()`
*Note*: If you're coding along, this section is optional as the rest of the steps do not rely on it.
Previously, you created a control and initialized its value at the same time. You can also initialize or reset the values later with the `setValue()` and `patchValue()` methods. ### `setValue()` With `setValue()`, you assign every form control value at once by passing in a data object whose properties exactly match the form model behind the `FormGroup`. The `setValue()` method checks the data object thoroughly before assigning any form control values. It will not accept a data object that doesn't match the `FormGroup` structure or is missing values for any control in the group. This way, it can return helpful error messages if you have a typo or if you've nested controls incorrectly. Conversely, `patchValue()` will fail silently. Notice that you can almost use the entire `hero` as the argument to `setValue()` because its shape is similar to the component's `FormGroup` structure. You can only show the hero's first address and you must account for the possibility that the `hero` has no addresses at all, as in the conditional setting of the `address` property in the data object argument: ### `patchValue()` With **`patchValue()`**, you can assign values to specific controls in a `FormGroup` by supplying an object of key/value pairs for them. This example sets only the form's `name` control. With `patchValue()` you have more flexibility to cope with divergent data and form models. But unlike `setValue()`, `patchValue()` cannot check for missing control values and doesn't throw helpful errors. {@a hero-list} ## Create the `HeroListComponent` and `HeroService` To demonstrate further reactive forms techniques, it is helpful to add more functionality to the example by adding a `HeroListComponent` and a `HeroService`. The `HeroDetailComponent` is a nested sub-component of the `HeroListComponent` in a _master/detail_ view. Together they look like this:
HeroListComponent
First, add a `HeroListComponent` with the following command: ng generate component HeroList Give the `HeroListComponent` the following contents: Next, add a `HeroService` using the following command: ng generate service Hero Then, give it the following contents: The `HeroListComponent` uses an injected `HeroService` to retrieve heroes from the server and then presents those heroes to the user as a series of buttons. The `HeroService` emulates an HTTP service. It returns an `Observable` of heroes that resolves after a short delay, both to simulate network latency and to indicate visually the necessarily asynchronous nature of the application. When the user clicks on a hero, the component sets its `selectedHero` property which is bound to the `hero` `@Input()` property of the `HeroDetailComponent`. The `HeroDetailComponent` detects the changed hero and resets its form with that hero's data values. A refresh button clears the hero list and the current selected hero before refetching the heroes. Notice that `hero-list.component.ts` imports `Observable` and the `finalize` operator, while `hero.service.ts` imports `Observable`, `of`, and the `delay` operator from `rxjs`. The remaining `HeroListComponent` and `HeroService` implementation details are beyond the scope of this tutorial. However, the techniques involved are covered elsewhere in the documentation, including the _Tour of Heroes_ [here](tutorial/toh-pt3 "ToH: Multiple Components") and [here](tutorial/toh-pt4 "ToH: Services"). To use the `HeroService`, import it into `AppModule` and add it to the `providers` array. To use the `HeroListComponent`, import it, declare it, and export it: Next, update the `HeroListComponent` template with the following: These changes need to be reflected in the `AppComponent` template. Replace the contents of `app.component.html` with updated markup to use the `HeroListComponent`, instead of the `HeroDetailComponent`: Finally, add an `@Input()` property to the `HeroDetailComponent` so `HeroDetailComponent` can receive the data from `HeroListComponent`. Remember to add the `Input` symbol to the `@angular/core ` `import` statement in the list of JavaScript imports too. Now you should be able to click on a button for a hero and a form renders. ## When to set form model values (`ngOnChanges`) When to set form model values depends upon when the component gets the data model values. The `HeroListComponent` displays hero names to the user. When the user clicks on a hero, the `HeroListComponent` passes the selected hero into the `HeroDetailComponent` by binding to its `hero` `@Input()` property. In this approach, the value of `hero` in the `HeroDetailComponent` changes every time the user selects a new hero. You can call `setValue()` using the [ngOnChanges](guide/lifecycle-hooks#onchanges) lifecycle hook, which Angular calls whenever the `@Input()` `hero` property changes. ### Reset the form First, import the `OnChanges` symbol in `hero-detail.component.ts`. Next, let Angular know that the `HeroDetailComponent` implements `OnChanges`: Add the `ngOnChanges` method to the class as follows: Notice that it calls `rebuildForm()`, which is a method where you can set the values. You can name `rebuildForm()` anything that makes sense to you. It isn't built into Angular, but is a method you create to effectively leverage the `ngOnChanges` lifecycle hook. The `rebuildForm()` method does two things; resets the hero's name and the address. {@a form-array} ## Use _FormArray_ to present an array of `FormGroups` A `FormGroup` is a named object whose property values are `FormControls` and other `FormGroups`. Sometimes you need to present an arbitrary number of controls or groups. For example, a hero may have zero, one, or any number of addresses. The `Hero.addresses` property is an array of `Address` instances. An `address` `FormGroup` can display one `Address`. An Angular `FormArray` can display an array of `address` `FormGroups`. To get access to the `FormArray` class, import it into `hero-detail.component.ts`: To work with a `FormArray` do the following: 1. Define the items in the array; that is, `FormControls` or `FormGroups`. 1. Initialize the array with items created from data in the data model. 1. Add and remove items as the user requires. Define a `FormArray` for `Hero.addresses` and let the user add or modify addresses. You’ll need to redefine the form model in the `HeroDetailComponent` `createForm()` method, which currently only displays the first hero address in an `address` `FormGroup`: ### From `address` to `secretLairs` From the user's point of view, heroes don't have _addresses_. Addresses are for mere mortals. Heroes have _secret lairs_! Replace the address `FormGroup` definition with a `secretLairs` `FormArray` definition: In `hero-detail.component.html` change `formGroupName="address"` to `formArrayName="secretLairs"`.
Changing the form control name from `address` to `secretLairs` underscores an important point: the _form model_ doesn't have to match the _data model_. Obviously, there has to be a relationship between the two. But it can be anything that makes sense within the application domain. _Presentation_ requirements often differ from _data_ requirements. The reactive forms approach both emphasizes and facilitates this distinction.
### Initialize the `secretLairs` _FormArray_ The default form displays a nameless hero with no addresses. You need a method to populate (or repopulate) the `secretLairs` with actual hero addresses whenever the parent `HeroListComponent` sets the `HeroDetailComponent.hero` `@Input()` property to a new `Hero`. The following `setAddresses()` method replaces the `secretLairs` `FormArray` with a new `FormArray`, initialized by an array of hero address `FormGroups`. Add this to the `HeroDetailComponent` class: Notice that you replace the previous `FormArray` with the `FormGroup.setControl()` method, not with `setValue()`. You're replacing a _control_, not the _value_ of a control. Notice also that the `secretLairs` `FormArray` contains `FormGroups`, not `Addresses`. Next, call `setAddresses()` from within `rebuildForm()`: ### Get the _FormArray_ The `HeroDetailComponent` should be able to display, add, and remove items from the `secretLairs` `FormArray`. Use the `FormGroup.get()` method to acquire a reference to that `FormArray`. Wrap the expression in a `secretLairs` convenience property for clarity and re-use. Add the following to `HeroDetailComponent`. ### Display the _FormArray_ The current HTML template displays a single `address` `FormGroup`. Revise it to display zero, one, or more of the hero's `address` `FormGroups`. This is mostly a matter of wrapping the previous template HTML for an address in a `
` and repeating that `
` with `*ngFor`. There are three key points when writing the `*ngFor`: 1. Add another wrapping `
`, around the `
` with `*ngFor`, and set its `formArrayName` directive to `"secretLairs"`. This step establishes the `secretLairs` `FormArray` as the context for form controls in the inner, repeated HTML template. 1. The source of the repeated items is the `FormArray.controls`, not the `FormArray` itself. Each control is an `address` `FormGroup`, exactly what the previous (now repeated) template HTML expected. 1. Each repeated `FormGroup` needs a unique `formGroupName`, which must be the index of the `FormGroup` in the `FormArray`. You'll re-use that index to compose a unique label for each address. Here's the skeleton for the secret lairs section of the HTML template: Here's the complete template for the secret lairs section. Add this to `HeroDetailComponent` template, replacing the `forGroupName=address` `
`: ### Add a new lair to the _FormArray_ Add an `addLair()` method that gets the `secretLairs` `FormArray` and appends a new `address` `FormGroup` to it. Place a button on the form so the user can add a new _secret lair_ and wire it to the component's `addLair()` method. Put it just before the closing `
` of the `secretLairs` `FormArray`.
Be sure to add the `type="button"` attribute because without an explicit type, the button type defaults to "submit". When you later add a form submit action, every "submit" button triggers the submit action which might do something like save the current changes. You do not want to save changes when the user clicks the _Add a Secret Lair_ button.
### Try it! Back in the browser, select the hero named "Magneta". "Magneta" doesn't have an address, as you can see in the diagnostic JSON at the bottom of the form.
JSON output of addresses array
Click the "_Add a Secret Lair_" button. A new address section appears. Well done! ### Remove a lair This example can _add_ addresses but it can't _remove_ them. For extra credit, write a `removeLair` method and wire it to a button on the repeating address HTML. {@a observe-control} ## Observe control changes Angular calls `ngOnChanges()` when the user picks a hero in the parent `HeroListComponent`. Picking a hero changes the `HeroDetailComponent.hero` `@Input()` property. Angular does _not_ call `ngOnChanges()` when the user modifies the hero's `name` or `secretLairs`. Fortunately, you can learn about such changes by subscribing to one of the `FormControl` properties that raises a change event. These are properties, such as `valueChanges`, that return an RxJS `Observable`. You don't need to know much about RxJS `Observable` to monitor form control values. Add the following method to log changes to the value of the `name` `FormControl`. Call it in the constructor, after `createForm()`. The `logNameChange()` method pushes name-change values into a `nameChangeLog` array. Display that array at the bottom of the component template with this `*ngFor` binding: Return to the browser, select a hero; for example, Magneta, and start typing in the `name` ``. You should see a new name in the log after each keystroke. ### When to use it An interpolation binding is the easier way to display a name change. Subscribing to an observable `FormControl` property is handy for triggering application logic within the component class. {@a save} ## Save form data The `HeroDetailComponent` captures user input but it doesn't do anything with it. In a real app, you'd probably save those hero changes, revert unsaved changes, and resume editing. After you implement both features in this section, the form will look like this:
Form with save & revert buttons
### Save When the user submits the form, the `HeroDetailComponent` will pass an instance of the hero _data model_ to a save method on the injected `HeroService`. Add the following to `HeroDetailComponent`. This original `hero` had the pre-save values. The user's changes are still in the _form model_. So you create a new `hero` from a combination of original hero values (the `hero.id`) and deep copies of the changed form model values, using the `prepareSaveHero()` helper. Make sure to import `HeroService` and add it to the constructor:
**Address deep copy** Had you assigned the `formModel.secretLairs` to `saveHero.addresses` (see line commented out), the addresses in `saveHero.addresses` array would be the same objects as the lairs in the `formModel.secretLairs`. A user's subsequent changes to a lair street would mutate an address street in the `saveHero`. The `prepareSaveHero` method makes copies of the form model's `secretLairs` objects so that can't happen.
### Revert (cancel changes) The user cancels changes and reverts the form to the original state by pressing the Revert button. Reverting is easy. Simply re-execute the `rebuildForm()` method that built the form model from the original, unchanged `hero` data model. ### Buttons Add the "Save" and "Revert" buttons near the top of the component's template: The buttons are disabled until the user "dirties" the form by changing a value in any of its form controls (`heroForm.dirty`). Clicking a button of type `"submit"` triggers the `ngSubmit` event which calls the component's `onSubmit` method. Clicking the revert button triggers a call to the component's `revert` method. Users now can save or revert changes. Try the . {@a source-code} The key files of the final version are as follows: You can download the complete source for all steps in this guide from the Reactive Forms Demo live example.