All docs
V21.1
24.2
24.1
23.2
23.1
22.2
22.1
21.2
21.1
20.2
20.1
The page you are viewing does not exist in version 20.1.
19.2
The page you are viewing does not exist in version 19.2.
19.1
The page you are viewing does not exist in version 19.1.
18.2
The page you are viewing does not exist in version 18.2.
18.1
The page you are viewing does not exist in version 18.1.
17.2
The page you are viewing does not exist in version 17.2.
A newer version of this page is available. Switch to the current version.

JavaScript/jQuery Form - Getting Started

NOTE
Before you start the tutorial, ensure DevExtreme is installed in your Angular, Vue, React, or jQuery application.

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 jQuery application and use the following code to create a Form:

index.js
index.html
index.css
  • $(function() {
  • $("#form").dxForm({
  • // Configuration goes here
  • });
  • });
  • <html>
  • <head>
  • <!-- ... -->
  • <script type="text/javascript" src="https://code.jquery.com/jquery-3.5.1.min.js"></script>
  •  
  • <link rel="stylesheet" href="https://cdn3.devexpress.com/jslib/21.1.11/css/dx.common.css">
  • <link rel="stylesheet" href="https://cdn3.devexpress.com/jslib/21.1.11/css/dx.light.css">
  • <link rel="stylesheet" href="index.css">
  •  
  • <script type="text/javascript" src="https://cdn3.devexpress.com/jslib/21.1.11/js/dx.all.js"></script>
  • <script type="text/javascript" src="index.js"></script>
  • </head>
  • <body class="dx-viewport">
  • <div id="form"></div>
  • </body>
  • </html>
  • #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:

index.js
  • $(function() {
  • $("#form").dxForm({
  • formData: {
  • name: "John Heart",
  • officeNumber: 901,
  • hireDate: new Date(2012, 4, 13)
  • }
  • });
  • });

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:

index.js
  • $(function() {
  • $("#form").dxForm({
  • formData: {
  • name: "John Heart",
  • officeNumber: 901,
  • hireDate: new Date(2012, 4, 13)
  • },
  • items: ["name", "officeNumber", {
  • dataField: "hireDate",
  • editorOptions: {
  • disabled: true
  • }
  • }]
  • });
  • });

Organize the Form Items

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.

index.js
  • $(function() {
  • $("#form").dxForm({
  • formData: {
  • name: "John Heart",
  • position: "CEO",
  • hireDate: new Date(2012, 4, 13),
  • officeNumber: 901,
  • notes: "John has been in the Audio/Video industry since 1990."
  • },
  • colCount: 2,
  • items: ["name", "position", "hireDate", "officeNumber", {
  • dataField: "notes",
  • colSpan: 2
  • }]
  • });
  • });

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:

DevExtreme Form: Grouped Items

index.js
  • $(function() {
  • $("#form").dxForm({
  • formData: {
  • 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"
  • },
  • colCount: 2,
  • items: [{
  • itemType: "group",
  • caption: "Personal Information",
  • items: ["name", "position", "hireDate", "officeNumber"]
  • }, {
  • itemType: "group",
  • caption: "Contacts",
  • items: ["phone", "skype", "email"]
  • }]
  • });
  • });

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:

DevExtreme Form: Tabbed Items

The code also shows how to configure the tab panel's height property in the tabPanelOptions object.

index.js
  • $(function() {
  • $("#form").dxForm({
  • formData: {
  • 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.'
  • },
  • items: [{
  • itemType: "group",
  • colCount: 2,
  • items: [{
  • itemType: "group",
  • caption: "Employee",
  • items: ["name", "position", "hireDate", "officeNumber"]
  • }, {
  • itemType: "group",
  • caption: "Personal Information",
  • items: [{
  • itemType: "tabbed",
  • tabPanelOptions: {
  • height: 260
  • },
  • tabs: [{
  • title: "Contacts",
  • items: ["skype", "phone", "email"]
  • }, {
  • title: "Note",
  • items: ["notes"]
  • }]
  • }]
  • }]
  • }]
  • });
  • });

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:

DevExtreme Form: Empty Item

index.js
  • $(function() {
  • $("#form").dxForm({
  • formData: {
  • // ...
  • },
  • colCount: 2,
  • items: ["name", "position", "hireDate", "officeNumber", {
  • itemType: "empty",
  • colSpan: 2
  • }, "phone", "skype", "email"]
  • });
  • });

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:

DevExtreme Form: Item Labels

index.js
  • $(function() {
  • $("#form").dxForm({
  • formData: {
  • // ...
  • },
  • labelLocation: "top",
  • colCount: 2,
  • items: ["name", "position", "hireDate", "officeNumber", {
  • dataField: "notes",
  • colSpan: 2,
  • label: {
  • alignment: "center"
  • }
  • }]
  • });
  • });

Modify the Form at Runtime

You can change any properties of the form, its items or editors at runtime. Use the option(optionName, optionValue) method to update a Form property, and the itemOption(id, option, value) to update the value of an item property. The code below modifies the readOnly property's value:

index.js
  • $(function() {
  • const form = $("#form").dxForm({
  • formData: {
  • // ...
  • },
  • items: [
  • // ...
  • ]
  • }).dxForm("instance");
  •  
  • $("#checkBox").dxCheckBox({
  • text: "Enable read-only mode",
  • value: false,
  • onValueChanged: function (e) {
  • form.option("readOnly", e.value);
  • }
  • });
  • });

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.

index.js
  • $(function() {
  • $("#form").dxForm({
  • formData: {
  • // ...
  • },
  • colCount: 2,
  • items: [{
  • dataField: "name",
  • isRequired: true
  • }, {
  • dataField: "officeNumber",
  • validationRules: [{
  • type: "numeric"
  • }]
  • }, {
  • dataField: "email",
  • validationRules: [{
  • type: "email"
  • }]
  • }]
  • });
  • });

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:

index.js
index.html
  • $(function() {
  • $("#form").dxForm({
  • formData: {
  • // ...
  • },
  • colCount: 2,
  • items: [{
  • itemType: "group",
  • caption: "Personal Information",
  • colCount: 2,
  • items: [{
  • dataField: "name",
  • isRequired: "true"
  • }, {
  • dataField: "officeNumber",
  • validationRules: [{
  • type: "numeric"
  • }]
  • }, {
  • dataField: "email",
  • validationRules: [{
  • type: "email"
  • }]
  • }]
  • }, {
  • itemType: "button",
  • buttonOptions: {
  • text: "Submit the Form",
  • useSubmitBehavior: true
  • }
  • }]
  • });
  •  
  • $("#form-container").on("submit", function(e) {
  • setTimeout(function () {
  • alert("Submitted");
  • }, 1000);
  •  
  • e.preventDefault();
  • });
  • });
  • <form action="/employee-page" id="form-container">
  • <div id="form"></div>
  • </form>

For further information on the Form UI component, refer to the following resources: