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

Default Value: undefined

component

An alias for the template property specified in React. Accepts a custom component. Refer to Using a Custom Component for more information.

cssClass

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

Type:

String

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

Default Value: undefined

editorOptions

Configures the form item's editor.

Type: any
Default Value: undefined

View Demo

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 in Angular, Vue, and React. In these frameworks, specify editorOptions with an object. We recommend that you declare the object outside the configuration component in Vue and React to prevent possible issues caused by unnecessary re-rendering. Alternatively, you can configure a custom editor in a template.

Angular
app.component.html
app.module.ts
<dx-form ... >
    <dxi-item ...
        editorType="dxDateBox"
        [editorOptions]="{ width: '100%' }">
    </dxi-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 { }
Vue
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>
React
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;
NOTE
If you set the id and name attributes using the inputAttr property, they will be overwritten. The Form generates these attributes automatically and uses them for addressing the DOM elements.
See Also

editorType

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

Type:

String

Accepted Values: 'dxAutocomplete' | 'dxCalendar' | 'dxCheckBox' | 'dxColorBox' | 'dxDateBox' | 'dxDropDownBox' | 'dxHtmlEditor' | 'dxLookup' | 'dxNumberBox' | 'dxRadioGroup' | 'dxRangeSlider' | 'dxSelectBox' | 'dxSlider' | 'dxSwitch' | 'dxTagBox' | 'dxTextArea' | 'dxTextBox'

View Demo

IMPORTANT
If you use DevExtreme modules, import the editor's module when specifying this property. You can omit modules for "dxTextBox", "dxDateBox", "dxCheckBox", and "dxNumberBox", because the Form UI component imports them automatically when creating form items.
See Also

helpText

Specifies the help text displayed for the current form item.

Type:

String

Default Value: undefined

isRequired

Specifies whether the current form item is required.

Type:

Boolean

Default Value: undefined

NOTE

If you specify validation rules using the validationRules property, the isRequired property is ignored. In this case, use the Require validation rule instead.

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";
// ...
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';

const 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:

String

Default Value: 'simple'
Accepted Values: 'empty' | 'group' | 'simple' | 'tabbed' | 'button'

label

Specifies properties for the form item label.

Type:

Object

Default Value: undefined

name

Specifies a name that identifies the form item.

Type:

String

Default Value: undefined

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

render

An alias for the template property specified in React. Accepts a rendering function. Refer to Using a Rendering Function for more information.

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.

In Angular, Vue, and 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:

Angular
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
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
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 Demo View Example

See Also

validationRules

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

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

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

Default Value: undefined

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