Angular Form - SimpleItem

This article describes configuration properties of a simple form item.

Type:

Object

A simple form item is an editor-label pair usually bound to a formData object field used to display and modify this field.

You can also create a simple item without binding it to a formData field. For example, it can be a check box that allows a user to confirm his agreement to process entered data.

For detailed information on configuring simple items, see the Configure Simple Items topic.

View Demo

colSpan

Specifies the number of columns spanned by the item.

Type:

Number

| undefined
Default Value: undefined

View Demo

See Also

cssClass

Specifies a CSS class to be applied to the form item.

Type:

String

| undefined
Default Value: undefined

In Form, you can customize the appearance of form items using CSS styles. To apply a style to an item, implement a CSS class, which may contain various properties, and assign the name of this class to the cssClass property of the item.

View Demo

dataField

Specifies the path to the formData object field bound to the current form item.

Type:

String

| undefined
Default Value: undefined

Use standard JavaScript syntax (item.nestedItem and array[itemIndex]) to specify the field path if your data includes nested items/arrays:

jQuery
index.js
data.js
$(function() {
    $("#formContainer").dxForm({
        // ...
        formData: employee,
        items: [{
            // ...
            dataField: "address[0].city",
        },
        // ...
        ]
    });
});
const employee = {
    id: '0',
    firstName: 'John',
    lastName: 'Heart',
    address: [
        {
            city: 'New York',
            state: 'NY'
        },
    ]
};
Angular
app.component.html
app.service.ts
<dx-form [formData]="employee" ... >
    <dxi-item dataField="address[0].city" ... ></dxi-item>
</dx-form>
import { Injectable } from '@angular/core';

export class Employee {
    id: number;
    firstName: string;
    lastName: string;
    address: Object[];
}

const employee: Employee = {
    id: '0',
    firstName: 'John',
    lastName: 'Heart',
    address: [
        {
            city: 'New York',
            state: 'NY'
        },
    ]
};

@Injectable()
export class Service {
    getEmployee() : Employee {
        return employee;
    }
}
Vue
App.vue
data.js
<template>
    <DxForm :form-data="employee" ...>
        <DxSimpleItem data-field="address[0].city" ... />
    </DxForm>
</template>
<script setup>
import DxForm, { DxSimpleItem } from 'devextreme-vue/form';
import service from './data.js';

const employee = service.getEmployee();
</script>
const employee = {
    id: '0',
    firstName: 'John',
    lastName: 'Heart',
    address: [
        {
            city: 'New York',
            state: 'NY'
        },
    ]
};

export default {
    getEmployee() {
        return employee;
    },
};
React
App.js
data.js
import React from 'react';
import Form, { SimpleItem } from 'devextreme-react/form';

const App = () => {
    return (
        <Form formData={employee} ...>
            <SimpleItem dataField="address[0].city" ... />
        </Form>
    );
};

export default App;
const employee = {
    id: '0',
    firstName: 'John',
    lastName: 'Heart',
    address: [
        {
            city: 'New York',
            state: 'NY'
        },
    ]
};

export default {
    getEmployee() {
        return employee;
    },
};
NOTE

The Form component does not support dataField field names that contain characters used to access nested items: ., [, and ]. The following code snippet demonstrates an unsupported field name:

jQuery
index.js
// Incorrect:
const employee = {
    id: '0',
    "address.city": 'New York', // Invalid naming.
};

$(function() {
    $("#formContainer").dxForm({
        // ...
        formData: employee,
        items: [{
            // ...
            dataField: "address.city", // Form attempts to access the "city" property inside of "address".
        }]
    });
});

// Correct:
const employee = {
    id: '0',
    addressCity: 'New York', // Supported naming.
};

$(function() {
    $("#formContainer").dxForm({
        // ...
        formData: employee,
        items: [{
            // ...
            dataField: "addressCity", // Form accesses "addressCity" correctly.
        }]
    });
});
Angular
app.component.html
app.component.ts
// Incorrect:
<dx-form [formData]="employee" ... >
    <dxi-item ...
        dataField="address.city" // Form attempts to access the "city" property inside of "address".
    >
    </dxi-item>
</dx-form>

// Correct:
<dx-form [formData]="employee" ... >
    <dxi-item ...
        dataField="addressCity" // Form accesses "addressCity" correctly.
    >
    </dxi-item>
</dx-form>
// Incorrect:
const employee: Employee = {
    id: '0',
    "address.city": 'New York', // Invalid naming.
};

// Correct:
const employee: Employee = {
    id: '0',
    addressCity: 'New York', // Supported naming.
};
Vue
App.vue
// Incorrect:
<template>
    <DxForm :form-data="employee" ...>
        <DxSimpleItem ... 
            data-field="address.city" // Form attempts to access the "city" property inside of "address".
        />
    </DxForm>
</template>
<script setup>
// ...
const employee = {
    id: '0',
    "address.city": 'New York', // Invalid naming.
};
</script>

// Correct:
<template>
    <DxForm :form-data="employee" ...>
        <DxSimpleItem ...
            data-field="addressCity" // Form accesses "addressCity" correctly.
        />
    </DxForm>
</template>
<script setup>
// ...
const employee = {
    id: '0',
    addressCity: 'New York', // Supported naming.
};
</script>
React
App.js
// Incorrect:
const App = () => {
    const employee = {
        id: '0',
        "address.city": 'New York', // Invalid naming.
    };

    return (
        <Form formData={employee} ...>
            <SimpleItem ...
                dataField="address.city" // Form attempts to access the "city" property inside of "address".
            />
        </Form>
    );
};

export default App;

// Correct: 
const App = () => {
    const employee = {
        id: '0',
        addressCity: 'New York', // Supported naming.
    };

    return (
        <Form formData={employee} ...>
            <SimpleItem ...
                dataField="addressCity" // Form accesses "addressCity" correctly.
            />
        </Form>
    );
};

export default App;

View Demo

editorOptions

Configures the form item's editor.

Type: any | undefined
Default Value: undefined

View Demo

Angular

editorOptions should contain the properties of the DevExtreme editor specified in the editorType. Because of this dependency, editorOptions cannot be typed and are not implemented as nested configuration components. Specify editorOptions with an object. Alternatively, you can configure a custom editor in a template.

app.component.html
app.module.ts
<dx-form ... >
    <dxi-form-item ...
        editorType="dxDateBox"
        [editorOptions]="{ width: '100%' }">
    </dxi-form-item>
</dx-form>
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 { }

If you want to define multiple editors and avoid inline declarations, combine all editor types into a union. Then, assign an object with this union type to each of your *editorOptions .

app.component.ts
app.component.html
import { Component } from '@angular/core';
import { DxDateBoxTypes } from 'devextreme-angular/ui/date-box';
import { DxTextBoxTypes } from 'devextreme-angular/ui/text-box';

type EditorProps = DxDateBoxTypes.Properties | DxTextBoxTypes.Properties;

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})

export class AppComponent {
    dateBoxOptions: EditorProps = { width: '100%', value: undefined };
    textBoxOptions: EditorProps = { mask: '+1 (X00) 000-0000', maskRules: { X: /[02-9]/ } };
}
<dx-form ... >
    <dxi-form-item ...
        editorType="dxDateBox"
        [editorOptions]="dateBoxOptions">
    </dxi-form-item>
    <dxi-form-item ...
        editorType="dxTextBox"
        [editorOptions]="textBoxOptions">
    </dxi-form-item>
</dx-form>
Vue

editorOptions should contain the properties of the DevExtreme editor specified in the editorType. Because of this dependency, editorOptions cannot be typed and are not implemented as nested configuration components. Specify editorOptions with an object. We recommend that you declare the object outside the configuration component to prevent possible issues caused by unnecessary re-rendering. Alternatively, you can configure a custom editor in a template.

App.vue
<template>
    <DxForm ... >
        <DxSimpleItem ...
            editor-type="dxDateBox"
            :editor-options="dateBoxOptions"
        />
    </DxForm>
</template>

<script>
import 'devextreme/dist/css/dx.light.css';

import DxForm, {
    DxSimpleItem
} from 'devextreme-vue/form';

export default {
    components: {
        DxForm,
        DxSimpleItem
    },
    data() {
        return {
            dateBoxOptions: { width: '100%'}
        }
    }
}
</script>

If you use TypeScript, want to define multiple editors, and avoid inline declarations, combine all editor types into a union. Then, assign an object with this union type to each of your editorOptions.

App.vue
<template>
<DxForm>
    <DxSimpleItem editor-type="dxDateBox" :editor-options="dateBoxOptions" />
    <DxSimpleItem editor-type="dxTextBox" :editor-options="textBoxOptions" />
</DxForm>
</template>

<script setup lang="ts">
import DxForm, { DxSimpleItem } from "devextreme-vue/form";
import type { DxDateBoxTypes } from "devextreme-vue/date-box";
import type { DxTextBoxTypes } from "devextreme-vue/text-box";
import 'devextreme/dist/css/dx.light.css';

type EditorProps = DxDateBoxTypes.Properties | DxTextBoxTypes.Properties;

const dateBoxOptions: EditorProps = { width: '100%', value: undefined };
const textBoxOptions: EditorProps = { mask: '+1 (X00) 000-0000', maskRules: { X: /[02-9]/ } };
</script>
React

editorOptions should contain the properties of the DevExtreme editor specified in the editorType. Because of this dependency, editorOptions cannot be typed and are not implemented as nested configuration components. Specify editorOptions with an object. We recommend that you declare the object outside the configuration component to prevent possible issues caused by unnecessary re-rendering. Alternatively, you can configure a custom editor in a template.

App.js
import React from 'react';

import 'devextreme/dist/css/dx.light.css';

import Form, {
    SimpleItem
} from 'devextreme-react/form';

class App extends React.Component {
    dateBoxOptions = { width: '100%' };

    render() {
        return (
            <Form ... >
                <SimpleItem ...
                    editorType="dxDateBox"
                    editorOptions={this.dateBoxOptions}
                />
            </Form>
        );
    }
}
export default App;

If you use TypeScript, want to define multiple editors, and avoid inline declarations, combine all editor types into a union. Next, assign each of your editorOptions an object with this union type.

App.tsx
import 'devextreme/dist/css/dx.light.css';
import Form, { SimpleItem } from 'devextreme-react/form';
import type { JSX } from 'react';
import type { DateBoxTypes } from 'devextreme-react/date-box';
import type { TextBoxTypes } from 'devextreme-react/text-box';

type EditorProps = DateBoxTypes.Properties | TextBoxTypes.Properties;

const dateBoxOptions: EditorProps = { width: '100%', value: undefined };
const textBoxOptions: EditorProps = { mask: '+1 (X00) 000-0000', maskRules: { X: /[02-9]/ } }; 

function App(): JSX.Element {
    return (
        <Form>
            <SimpleItem editorType="dxDateBox" editorOptions={dateBoxOptions} />
            <SimpleItem editorType="dxTextBox" editorOptions={textBoxOptions} />
        </Form>
    );
}

export default App;
NOTE
Some editor properties specified in editorOptions can be overwritten by Form settings, for instance, labels and placeholders. The id and name attributes of the inputAttr property are also overwritten. The Form generates these attributes automatically and uses them to address the DOM elements.

View on GitHub

See Also

editorType

Specifies which editor UI component is used to display and edit the form item value.

Type:

FormItemComponent

View Demo

You can use the following editors in DevExtreme Form:

IMPORTANT

If you use DevExtreme modules, import the editor's module when specifying this property. For example, if you use "dxLookup", specify the following import:

import "devextreme/ui/lookup";

You can omit modules for "dxTextBox", "dxDateBox", "dxCheckBox", and "dxNumberBox", because the Form UI component imports them automatically when creating form items.

NOTE
You can use a template to define an unsupported component.

View on GitHub

See Also

helpText

Specifies the help text displayed for the current form item.

Type:

String

| undefined
Default Value: undefined

View Demo

NOTE
In "static" or "floating" labelMode, form items use the optionalMark property value as help text if the helpText property is not specified.
See Also

isRequired

Specifies if the current form item is required.

Type:

Boolean

| undefined
Default Value: undefined

When this property is enabled, Form uses RequiredRule to validate the current item. The following values break RequiredRule:

NOTE

If you specify validationRules, Form ignores the isRequired property. To implement isRequired functionality, specify a RequiredRule validation rule:

jQuery
JavaScript
$(function() {
    $('#formContainer').dxForm({
        items: [{
            validationRules: [
                { type: 'required' }
            ]
        }, ... ]
    });
});
Angular
HTML
TypeScript
<dx-form ... >
    <dxi-item ... >
        <dxi-validation-rule type="required"></dxi-validation-rule>
    </dxi-item>
</dx-form>
import { DxFormModule } from 'devextreme-angular/ui/form';
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxFormModule
    ],
    // ...
})
Vue
App.vue
<template>
    <DxForm ... >
        <DxSimpleItem ... >
            <DxRequiredRule ... />
        </DxSimpleItem>
    </DxForm>
</template>
<script>
import { DxForm, DxSimpleItem, DxRequiredRule } from 'devextreme-vue/form';

export default {
    components: {
        DxForm,
        DxSimpleItem,
        DxRequiredRule
    }
}
</script>
React
App.js
import React from 'react';
import { Form, SimpleItem, RequiredRule } from 'devextreme-react/form';

function App () {
    return (
        <Form ...>
            <SimpleItem ...>
                <RequiredRule ... />
            </SimpleItem>
        </Form>
    );
};

export default App;
See Also

itemType

Specifies the item's type. Set it to "simple" to create a simple item.

Type:

FormItemType

Default Value: 'simple'
See Also

label

Specifies properties for the form item label.

Selector: dxo-label
Type:

Object

Default Value: undefined

View Demo

See Also

name

Specifies a name that identifies the form item.

Type:

String

| undefined
Default Value: undefined

Use the name instead of the data field to access unbound simple items in methods like getEditor(dataField), itemOption(id), etc.

template

A template that can be used to replace the default editor with custom content.

Type:

template

Template Data:
Name Type Description
component

Form

The Form instance.
dataField

String

The item's dataField.
editorOptions

Object

The item editor's configuration.
editorType

String

The editor's type.
name

String

The item's name.
jQuery
index.js
$(() => {
    const customer = {
        Email: "",
        FullName: "",
        BirthDate: null
    };

    const maxDate = new Date().setYear(new Date().getYear() - 21);

    $('#form').dxForm({
        formData: customer,
        validationGroup: "customerData",
        items: [{
            label: {
                text: "Date of birth"
            },
            template: (data) => {
                return $("<div>").dxDateBox({
                    value: customer.BirthDate,
                }).dxValidator({
                    validationGroup: "customerData",
                    validationRules: [{
                        type: 'required',
                        message: "Date of birth is required"
                    }, {
                        type: 'range',
                        max: maxDate,
                        message: 'You must be at least 21 years old'
                    }]
                });
            }
        }],
    });
});
Angular

This template can be used instead of editorType and editorOptions to configure a custom editor. It gives you the advantage of using nested configuration components. When you configure a custom editor in the template, consider the following specificities:

  • Wrap the custom editor into the <div *dxTemplate></div> tag.

  • Use two-way binding to bind the custom editor to a formData field.

  • If you use validation, define validation rules in the editor, not in the form item.

  • Use the same validationGroup as the Form to ensure the custom editor is validated simultaneously with other form editors.

The code below configures the DateBox UI component in the template. The UI component is bound to the BirthDate field of formData and has a validation group and two validation rules:

app.component.html
app.component.ts
app.module.ts
<dx-form
    [formData]="customer"
    validationGroup="customerData">
    <!-- ... -->
    <dxi-item>
        <dxo-label text="Date of birth"></dxo-label>
        <div *dxTemplate>
            <dx-date-box
                [(value)]="customer.BirthDate">
                <dx-validator
                    validationGroup="customerData">
                    <dxi-validation-rule 
                        type="required"
                        message="Date of birth is required">
                    </dxi-validation-rule>
                    <dxi-validation-rule 
                        type="range"
                        [max]="maxDate"
                        message="You must be at least 21 years old">
                    </dxi-validation-rule>
                </dx-validator>
            </dx-date-box>
        </div>
    </dxi-item>
</dx-form>
import { Component } from '@angular/core';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    customer = {
        Email: "",
        FullName: "",
        BirthDate: null
    };
    maxDate: Date = new Date().setYear(new Date().getYear() - 21);
}
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 { }
Vue

This template can be used instead of editorType and editorOptions to configure a custom editor. It gives you the advantage of using nested configuration components. When you configure a custom editor in the template, consider the following specificities:

  • Use two-way binding to bind the custom editor to a formData field.

  • If you use validation, define validation rules in the editor, not in the form item.

  • Use the same validationGroup as the Form to ensure the custom editor is validated simultaneously with other form editors.

The code below configures the DateBox UI component in the template. The UI component is bound to the BirthDate field of formData and has a validation group and two validation rules:

App.vue
<template>
    <DxForm
        :form-data="customer"
        validation-group="customerData">
        <!-- ... -->
        <DxSimpleItem>
            <DxLabel text="Date of birth" />
            <template #default>
                <DxDateBox
                    v-model:value="customer.BirthDate">
                    <DxValidator
                        validation-group="customerData">
                        <DxRequiredRule message="Date of birth is required" />
                        <DxRangeRule
                            :max="maxDate"
                            message="You must be at least 21 years old"
                        />
                    </DxValidator>
                </DxDateBox>
            </template>
        </DxSimpleItem>
    </DxForm>
</template>

<script>
import 'devextreme/dist/css/dx.light.css';

import DxForm, {
    DxSimpleItem,
    DxLabel
} from 'devextreme-vue/form';
import DxDateBox from 'devextreme-vue/date-box';
import DxValidator, {
    DxRequiredRule,
    DxRangeRule
} from 'devextreme-vue/validator';

export default {
    components: {
        DxForm,
        DxSimpleItem,
        DxLabel,
        DxDateBox,
        DxValidator,
        DxRequiredRule,
        DxRangeRule
    },
    data() {
        return {
            customer: {
                Email: "",
                FullName: "",
                BirthDate: null
            },
            maxDate: new Date().setYear(new Date().getYear() - 21);
        }
    }
}
</script>
React

This template can be used instead of editorType and editorOptions to configure a custom editor. It gives you the advantage of using nested configuration components. When you configure a custom editor in the template, consider the following specificities:

  • Use two-way binding to bind the custom editor to a formData field.

  • If you use validation, define validation rules in the editor, not in the form item.

  • Use the same validationGroup as the Form to ensure the custom editor is validated simultaneously with other form editors.

The code below configures the DateBox UI component in the template. The UI component is bound to the BirthDate field of formData and has a validation group and two validation rules:

App.js
import React, { useState } from 'react';

import 'devextreme/dist/css/dx.light.css';

import Form, {
    SimpleItem,
    Label
} from 'devextreme-react/form';
import DateBox from 'devextreme-react/date-box';
import Validator, {
    RequiredRule,
    RangeRule
} from 'devextreme-react/validator';

export default function App() {
    const [customer, setCustomer] = useState({
        Email: "",
        FullName: "",
        BirthDate: null
    });

    const maxDate = new Date().setYear(new Date().getYear() - 21);

    const updateBirthDate = e => {
        setCustomer(prevState => ({
            ...prevState,
            BirthDate: e.value;
        }));
    };

    return (
        <Form formData={customer} validationGroup="customerData">
            {/* ... */}
            <SimpleItem>
                <Label text="Date of birth" />
                <DateBox value={customer.BirthDate} onValueChanged={updateBirthDate}>
                    <Validator validationGroup="customerData">
                        <RequiredRule message="Date of birth is required" />
                        <RangeRule
                            max={maxDate}
                            message="You must be at least 21 years old"
                        />
                    </Validator>
                </DateBox>
            </SimpleItem>
        </Form>
    );
}

View on GitHub

NOTE
If you customize built-in DataGrid Form, refer to the following help topic for implementation specificities: DataGrid Form Editor Customization.
See Also

validationRules

An array of validation rules to be checked for the form item editor.

Selector: dxi-validation-rule
Type:

Array<RequiredRule | NumericRule | RangeRule | StringLengthRule | CustomRule | CompareRule | PatternRule | EmailRule | AsyncRule>

Default Value: undefined

There are several predefined rule types. Each rule type demands a specific set of rule properties. Refer to the Validation Rules section of the Validator API reference to learn how to define rules of different types.

View Demo

NOTE
If you use a template, you need to explicitly define Validator. Refer to the template API section for more information.
See Also

visible

Specifies whether or not the current form item is visible.

Type:

Boolean

Default Value: true

visibleIndex

Specifies the sequence number of the item in a form, group or tab.

Type:

Number

| undefined
Default Value: undefined

Items whose visible indexes are not specified are located at the end of the sequence and are ordered alphabetically.