Angular Form - Getting Started
The Form component creates a data entry UI for the underlying data object. The interface consists of automatically-arranged label-editor pairs that correspond to data fields. You can change data values, validate user input, and send the resulting data to the server.
This tutorial shows basic Form component configuration.
Refer to the following sections for more information about each configuration step. The full code is available in the following GitHub repository: getting-started-with-form.
Create a Form
Add DevExtreme to your Angular application and use the following code to create a Form:
- <dx-form id="form">
- <!-- Configuration goes here -->
- </dx-form>
- import { Component } from '@angular/core';
- @Component({
- selector: 'app-root',
- templateUrl: './app.component.html',
- styleUrls: ['./app.component.css']
- })
- export class AppComponent {
- }
- import { BrowserModule } from '@angular/platform-browser';
- import { NgModule } from '@angular/core';
- import { AppComponent } from './app.component';
- import { DxFormModule } from 'devextreme-angular';
- @NgModule({
- declarations: [
- AppComponent
- ],
- imports: [
- BrowserModule,
- DxFormModule
- ],
- providers: [ ],
- bootstrap: [AppComponent]
- })
- export class AppModule { }
- #form {
- height: 400px;
- }
Populate the Form Fields
To create a data entry UI, assign an object to the formData property. The Form creates a simple item (a label-editor pair) for each field in the formData object.
The Form chooses default editors based on value types: TextBox for string values, NumberBox for numbers, DateBox for dates. You can use the editorType property to specify an editor explicitly. In the following example, the Form uses the default editors:
- <dx-form
- [formData]="employee">
- </dx-form>
- import { Component } from '@angular/core';
- @Component({
- selector: 'app-root',
- templateUrl: './app.component.html',
- styleUrls: ['./app.component.css']
- })
- export class AppComponent {
- employee = {
- name: 'John Heart',
- officeNumber: 901,
- hireDate: new Date(2012, 4, 13)
- }
- }
- import { BrowserModule } from '@angular/platform-browser';
- import { NgModule } from '@angular/core';
- import { AppComponent } from './app.component';
- import { DxFormModule } from 'devextreme-angular';
- @NgModule({
- declarations: [
- AppComponent
- ],
- imports: [
- BrowserModule,
- DxFormModule
- ],
- providers: [ ],
- bootstrap: [AppComponent]
- })
- export class AppModule { }
When you implement this code, the Form is created with the following simple items: TextBox for name
, NumberBox for officeNumber
, and DateBox for the hireDate
data field.
Configure Simple Items
Use the items[] array to configure all form items. This array can contain strings (formData field names) and objects (item configurations). Use a string to create a label-editor pair (a simple item) with default configuration. To change the default settings, declare an item configuration object: specify the dataField and other properties. The example below configures the HireDate
item:
- <dx-form
- [formData]="employee">
- <dxi-item dataField="name"></dxi-item>
- <dxi-item dataField="officeNumber"></dxi-item>
- <dxi-item
- dataField="hireDate"
- [editorOptions]="hireDateOptions">
- </dxi-item>
- </dx-form>
- import { Component } from '@angular/core';
- @Component({
- selector: 'app-root',
- templateUrl: './app.component.html',
- styleUrls: ['./app.component.css']
- })
- export class AppComponent {
- employee = {
- name: 'John Heart',
- officeNumber: 901,
- hireDate: new Date(2012, 4, 13)
- }
- hireDateOptions = {
- disabled: true
- }
- }
- import { BrowserModule } from '@angular/platform-browser';
- import { NgModule } from '@angular/core';
- import { AppComponent } from './app.component';
- import { DxFormModule } from 'devextreme-angular';
- @NgModule({
- declarations: [
- AppComponent
- ],
- imports: [
- BrowserModule,
- DxFormModule
- ],
- providers: [ ],
- bootstrap: [AppComponent]
- })
- export class AppModule { }
In Columns
The Form can organize items into a fixed number of columns or automatically adjust the layout based on the screen width. To keep the fixed number of columns, initialize the colCount property as done in the code below. To create an adaptive layout, configure the screenByWidth and colCountByScreen properties.
An item can span multiple columns. The example below sets the colSpan property for the Notes
item to 2
so that it spans two columns.
- <dx-form
- [formData]="employee"
- [colCount]="2">
- <dxi-item dataField="name"></dxi-item>
- <dxi-item dataField="position"></dxi-item>
- <dxi-item dataField="hireDate"></dxi-item>
- <dxi-item dataField="officeNumber"></dxi-item>
- <dxi-item
- dataField="notes"
- [colSpan]="2">
- </dxi-item>
- </dx-form>
- import { Component } from '@angular/core';
- @Component({
- selector: 'app-root',
- templateUrl: './app.component.html',
- styleUrls: ['./app.component.css']
- })
- export class AppComponent {
- employee = {
- name: 'John Heart',
- position: 'CEO',
- hireDate: new Date(2012, 4, 13),
- officeNumber: 901,
- notes: 'John has been in the Audio/Video industry since 1990.'
- }
- }
- import { BrowserModule } from '@angular/platform-browser';
- import { NgModule } from '@angular/core';
- import { AppComponent } from './app.component';
- import { DxFormModule } from 'devextreme-angular';
- @NgModule({
- declarations: [
- AppComponent
- ],
- imports: [
- BrowserModule,
- DxFormModule
- ],
- providers: [ ],
- bootstrap: [AppComponent]
- })
- export class AppModule { }
In Groups
You can use groups to organize the data entry form. To add a group, create a group item and nest other items in it as shown in the code below. Items of any type can be nested, including other group items. You can configure each group's layout separately.
The following code creates two groups, each occupies a separate column. The resulting layout looks as follows:
- <dx-form
- [formData]="employee"
- [colCount]="2">
- <dxi-item
- itemType="group"
- caption="Personal Information">
- <dxi-item dataField="name"></dxi-item>
- <dxi-item dataField="position"></dxi-item>
- <dxi-item dataField="hireDate"></dxi-item>
- <dxi-item dataField="officeNumber"></dxi-item>
- </dxi-item>
- <dxi-item itemType="group" caption="Contacts">
- <dxi-item dataField="phone"></dxi-item>
- <dxi-item dataField="skype"></dxi-item>
- <dxi-item dataField="email"></dxi-item>
- </dx-item>
- </dx-form>
- import { Component } from '@angular/core';
- @Component({
- selector: 'app-root',
- templateUrl: './app.component.html',
- styleUrls: ['./app.component.css']
- })
- export class AppComponent {
- employee = {
- name: 'John Heart',
- position: 'CEO',
- hireDate: new Date(2012, 4, 13),
- officeNumber: 901,
- phone: '+1(213) 555-9392',
- skype: 'jheart_DX_skype',
- email: 'jheart@dx-email.com'
- }
- }
- import { BrowserModule } from '@angular/platform-browser';
- import { NgModule } from '@angular/core';
- import { AppComponent } from './app.component';
- import { DxFormModule } from 'devextreme-angular';
- @NgModule({
- declarations: [
- AppComponent
- ],
- imports: [
- BrowserModule,
- DxFormModule
- ],
- providers: [ ],
- bootstrap: [AppComponent]
- })
- export class AppModule { }
In Tabs
The Form uses the TabPanel component to display tabs. You can specify the tab panel's settings in the tabPanelOptions object. A tab can contain any item type.
The following example shows a tabbed item nested in the Personal Information
group. The resulting Form looks like this:
The code also shows how to configure the tab panel's height property in the tabPanelOptions object.
- <dx-form
- [formData]="employee"
- [colCount]="2">
- <dxi-item
- itemType="group"
- caption="Employee">
- <dxi-item dataField="name"></dxi-item>
- <dxi-item dataField="position"></dxi-item>
- <dxi-item dataField="hireDate"></dxi-item>
- <dxi-item dataField="officeNumber"></dxi-item>
- </dxi-item>
- <dxi-item itemType="group" caption="Personal Information">
- <dxi-item itemType="tabbed">
- <dxo-tab-panel-options [height]="260">
- </dxo-tab-panel-options>
- <dxi-tab title="Contacts">
- <dxi-item dataField="skype"></dxi-item>
- <dxi-item dataField="phone"></dxi-item>
- <dxi-item dataField="email"></dxi-item>
- </dxi-tab>
- <dxi-tab title="Note">
- <dxi-item dataField="notes"></dxi-item>
- </dxi-tab>
- </dxi-item>
- </dxi-item>
- </dx-form>
- import { Component } from '@angular/core';
- @Component({
- selector: 'app-root',
- templateUrl: './app.component.html',
- styleUrls: ['./app.component.css']
- })
- export class AppComponent {
- employee = {
- name: 'John Heart',
- position: 'CEO',
- hireDate: new Date(2012, 4, 13),
- officeNumber: 901,
- phone: '+1(213) 555-9392',
- skype: 'jheart_DX_skype',
- email: 'jheart@dx-email.com',
- notes: 'John has been in the Audio/Video industry since 1990.'
- }
- }
- import { BrowserModule } from '@angular/platform-browser';
- import { NgModule } from '@angular/core';
- import { AppComponent } from './app.component';
- import { DxFormModule } from 'devextreme-angular';
- @NgModule({
- declarations: [
- AppComponent
- ],
- imports: [
- BrowserModule,
- DxFormModule
- ],
- providers: [ ],
- bootstrap: [AppComponent]
- })
- export class AppModule { }
Add an Empty Space
If you need to add an empty space between neighboring items, use an empty item. To create an empty item, assign "empty" to the itemType property. To define how many columns the empty item should span, specify the colSpan option. For a list of available properties, refer to the Empty Item section.
In the following example, the empty item spans two columns. The resulting layout looks as follows:
- <dx-form
- [formData]="employee"
- [colCount]="2">
- <dxi-item dataField="name"></dxi-item>
- <dxi-item dataField="position"></dxi-item>
- <dxi-item dataField="hireDate"></dxi-item>
- <dxi-item dataField="officeNumber"></dxi-item>
- <dxi-item
- itemType="empty"
- [colSpan]="2">
- </dxi-item>
- <dxi-item dataField="skype"></dxi-item>
- <dxi-item dataField="phone"></dxi-item>
- <dxi-item dataField="email"></dxi-item>
- </dx-form>
- import { Component } from '@angular/core';
- @Component({
- selector: 'app-root',
- templateUrl: './app.component.html',
- styleUrls: ['./app.component.css']
- })
- export class AppComponent {
- employee = {
- // ...
- }
- }
- import { BrowserModule } from '@angular/platform-browser';
- import { NgModule } from '@angular/core';
- import { AppComponent } from './app.component';
- import { DxFormModule } from 'devextreme-angular';
- @NgModule({
- declarations: [
- AppComponent
- ],
- imports: [
- BrowserModule,
- DxFormModule
- ],
- providers: [ ],
- bootstrap: [AppComponent]
- })
- export class AppModule { }
Configure Item Labels
You can configure individual labels in the label object. This object's section lists all available properties.
The following properties apply to all labels in the Form:
The following code shows how to configure the labelLocation property to place labels on top of editors. The example sets the label.alignment property to align the Notes
item label's text to the center:
- <dx-form
- [formData]="employee"
- [colCount]="2"
- labelLocation="top">
- <dxi-item dataField="name"></dxi-item>
- <dxi-item dataField="position"></dxi-item>
- <dxi-item dataField="hireDate"></dxi-item>
- <dxi-item dataField="officeNumber"></dxi-item>
- <dxi-item
- dataField="notes"
- [colSpan]="2">
- <dxo-label alignment="center">
- </dxo-label>
- </dxi-item>
- </dx-form>
- import { Component } from '@angular/core';
- @Component({
- selector: 'app-root',
- templateUrl: './app.component.html',
- styleUrls: ['./app.component.css']
- })
- export class AppComponent {
- employee = {
- // ...
- }
- }
- import { BrowserModule } from '@angular/platform-browser';
- import { NgModule } from '@angular/core';
- import { AppComponent } from './app.component';
- import { DxFormModule } from 'devextreme-angular';
- @NgModule({
- declarations: [
- AppComponent
- ],
- imports: [
- BrowserModule,
- DxFormModule
- ],
- providers: [ ],
- bootstrap: [AppComponent]
- })
- export class AppModule { }
Modify the Form at Runtime
You can change any properties of the form, its items or editors at runtime. To update a property value, bind it to a component property. The code below modifies the readOnly property's value:
- <dx-form
- [formData]="employee"
- [readOnly]="isFormReadOnly">
- <!-- ... -->
- </dx-form>
- <dx-check-box
- text="Enable read-only mode"
- [(value)]="isFormReadOnly">
- </dx-check-box>
- import { Component } from '@angular/core';
- @Component({
- selector: 'app-root',
- templateUrl: './app.component.html',
- styleUrls: ['./app.component.css']
- })
- export class AppComponent {
- employee = {
- // ...
- }
- isFormReadOnly = false
- }
- import { BrowserModule } from '@angular/platform-browser';
- import { NgModule } from '@angular/core';
- import { AppComponent } from './app.component';
- import { DxFormModule, DxCheckBoxModule } from 'devextreme-angular';
- @NgModule({
- declarations: [
- AppComponent
- ],
- imports: [
- BrowserModule,
- DxFormModule,
- DxCheckBoxModule
- ],
- providers: [ ],
- bootstrap: [AppComponent]
- })
- export class AppModule { }
Validate the Form Data
DevExtreme includes a validation engine that checks edited values before they are saved. This engine supports different validation rule types.
To apply validation rules to a simple item, specify them in the validationRules[] array. You can specify an item's isRequired property to implicitly apply the RequiredRule.
The following example sets the isRequired property for the Name
item. It also adds the NumericRule for officeNumber
and EmailRule for Email
.
- <dx-form
- [formData]="employee"
- [colCount]="2">
- <dxi-item dataField="name" [isRequired]="true">
- </dxi-item>
- <dxi-item dataField="officeNumber">
- <dxi-validation-rule type="numeric">
- </dxi-validation-rule>
- </dxi-item>
- <dxi-item dataField="email">
- <dxi-validation-rule type="email">
- </dxi-validation-rule>
- </dxi-item>
- </dx-form>
- import { Component } from '@angular/core';
- @Component({
- selector: 'app-root',
- templateUrl: './app.component.html',
- styleUrls: ['./app.component.css']
- })
- export class AppComponent {
- employee = {
- // ...
- }
- }
- import { BrowserModule } from '@angular/platform-browser';
- import { NgModule } from '@angular/core';
- import { AppComponent } from './app.component';
- import { DxFormModule } from 'devextreme-angular';
- @NgModule({
- declarations: [
- AppComponent
- ],
- imports: [
- BrowserModule,
- DxFormModule
- ],
- providers: [ ],
- bootstrap: [AppComponent]
- })
- export class AppModule { }
You can also call the validate() Form's method to validate all editors simultaneously.
Submit the Form
To submit a form, add a Button Item and set its useSubmitBehavior property to true. The Form can be submitted to a server only if input validation is successful.
The useSubmitBehavior property requires that you wrap the dxForm in the HTML form element. You should also set the preventDefault property to true to override the HTML form submit event as shown in the code example.
The code below shows how to add a submit button, but does not show how to implement the backend. The example displays a confirmation message after the timeout:
- <form action="/employee-page" (submit)="handleSubmit($event)">
- <dx-form
- [formData]="employee"
- [colCount]="2">
- <dxi-item
- itemType="group"
- caption="Personal Information"
- [colCount]="2">
- <dxi-item dataField="name" [isRequired]="true">
- </dxi-item>
- <dxi-item dataField="officeNumber">
- <dxi-validation-rule type="numeric">
- </dxi-validation-rule>
- </dxi-item>
- <dxi-item dataField="email">
- <dxi-validation-rule type="email">
- </dxi-validation-rule>
- </dxi-item>
- </dxi-item>
- <dxi-item
- itemType="button"
- [buttonOptions]="submitButtonOptions">
- </dxi-item>
- </dx-form>
- </form>
- import { Component } from '@angular/core';
- @Component({
- selector: 'app-root',
- templateUrl: './app.component.html',
- styleUrls: ['./app.component.css']
- })
- export class AppComponent {
- employee = {
- // ...
- }
- submitButtonOptions = {
- text: "Submit the Form",
- useSubmitBehavior: true
- }
- handleSubmit = function(e) {
- setTimeout(() => {
- alert("Submitted");
- }, 1000);
- e.preventDefault();
- }
- }
- import { BrowserModule } from '@angular/platform-browser';
- import { NgModule } from '@angular/core';
- import { AppComponent } from './app.component';
- import { DxFormModule } from 'devextreme-angular';
- @NgModule({
- declarations: [
- AppComponent
- ],
- imports: [
- BrowserModule,
- DxFormModule
- ],
- providers: [ ],
- bootstrap: [AppComponent]
- })
- export class AppModule { }
Alternatively, if you want to implement custom validation logic, handle the Button click event:
- <form action="/employee-page" id="form-container">
- <dx-form ... >
- <dxi-item
- itemType="button"
- [buttonOptions]="submitButtonOptions">
- </dxi-item>
- </dx-form>
- </form>
- import { Component } from '@angular/core';
- @Component({
- selector: 'app-root',
- templateUrl: './app.component.html',
- styleUrls: ['./app.component.css']
- })
- export class AppComponent {
- submitButtonOptions = {
- text: "Submit the Form",
- onClick: function() {
- const validationResult = formInstance.validate(); // get Form instance beforehand
- if (validationResult.isValid)
- document.getElementById("form-container").submit();
- else
- alert("Form is invalid");
- }
- }
- }
For more information on the Form UI component, refer to the following resources:
If you have technical questions, please create a support ticket in the DevExpress Support Center.