JavaScript/jQuery Form - Configure Simple Items

Create a Simple Item

By default, the Form generates a simple item for each field of the formData object. In case you need to create items for specific fields only, add the names of these fields to the items array.

jQuery
JavaScript
$(function() {
    $("#formContainer").dxForm({
        formData: {
            firstName: "John",
            lastName: "Heart",
            position: "CEO",
            officeNo: 901
        },
        items: ["firstName", "lastName", "position"]
    });
});
Angular
HTML
TypeScript
<dx-form
    [(formData)]="employee"
    [items]="['firstName', 'lastName', 'position']">
</dx-form>
import { DxFormModule } from "devextreme-angular";
// ...
export class AppComponent {
    employee = {
        firstName: "John",
        lastName: "Heart",
        position: "CEO",
        officeNo: 901
    }
}
@NgModule({
    imports: [
        // ...
        DxFormModule
    ],
    // ...
})
Vue
App.vue
<template>
    <DxForm
        :form-data="employee"
        :items="['firstName', 'lastName', 'position']">
    </DxForm>
</template>

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

import DxForm from 'devextreme-vue/form';

export default {
    components: {
        DxForm
    },
    data() {
        return {
            employee: {
                firstName: "John",
                lastName: "Heart",
                position: "CEO",
                officeNo: 901
            }
        }
    }
}
</script>
React
App.js
import React from 'react';

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

import Form from 'devextreme-react/form';

class App extends React.Component {
    employee = {
        firstName: "John",
        lastName: "Heart",
        position: "CEO",
        officeNo: 901
    }

    render() {
        return (
            <Form
                formData={this.employee}
                items={['firstName', 'lastName', 'position']}>
            </Form>
        );
    }
}
export default App;

A simple form item is a label-editor pair. The label is the field name that undergoes a slight conversion, for example, the field name "firstName" becomes the "First Name" label. For more information on configuring labels, visit the Configure Item Labels section.

The editor that will be used in a particular simple item depends on the type of data that its field contains. However, you can force an item to use an editor of your choice. For this purpose, specify the item's editorType property. To configure the editor, use the editorOptions object. Note that you also need to specify the dataField property to bind the item to a formData field.

jQuery
JavaScript
$(function() {
    $("#formContainer").dxForm({
        formData: {
            name: "John Heart",
            hireDate: new Date(2012, 4, 13),
            notes: "John has been in the Audio/Video industry since 1990. He has led DevAv as its CEO since 2003."
        },
        items: [ "name", {
            dataField: "hireDate",
            editorType: "dxCalendar",
            editorOptions: {
                value: new Date()
            }
        }, {
            dataField: "notes",
            editorType: "dxTextArea",
            editorOptions: {
                placeholder: "Add notes..."
            }
        }]
    });
});
Angular
HTML
TypeScript
<dx-form
    [(formData)]="employee">
    <dxi-item dataField="name"></dxi-item>
    <dxi-item dataField="hireDate"
        editorType="dxCalendar"
        [editorOptions]="{ value: new Date() }">
    </dxi-item>
    <dxi-item dataField="notes"
        editorType="dxTextArea"
        [editorOptions]="{ placeholder: 'Add notes...' }">
    </dxi-item>
</dx-form>
import { DxFormModule, DxCalendarModule, DxTextAreaModule } from "devextreme-angular";
// ...
export class AppComponent {
    employee = {
        name: "John Heart",
        hireDate: new Date(2012, 4, 13),
        notes: "John has been in the Audio/Video industry since 1990. He has led DevAv as its CEO since 2003."
    }
}
@NgModule({
    imports: [
        // ...
        DxFormModule,
        DxCalendarModule,
        DxTextAreaModule
    ],
    // ...
})
Vue
App.vue
<template>
    <DxForm
        :form-data="employee">
        <DxSimpleItem data-field="name" />
        <DxSimpleItem
            data-field="hireDate"
            editor-type="dxCalendar"
            :editor-options="calendarOptions"
        />
        <DxSimpleItem
            data-field="notes"
            editor-type="dxTextArea"
            :editor-options="textAreaOptions"
        />
    </DxForm>
</template>

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

import DxForm, {
    DxSimpleItem
} from 'devextreme-vue/form';
import DxCalendar from 'devextreme-vue/calendar';
import DxTextArea from 'devextreme-vue/text-area';

export default {
    components: {
        DxForm,
        DxSimpleItem,
        DxCalendar,
        DxTextArea
    },
    data() {
        return {
            employee: {
                name: "John Heart",
                hireDate: new Date(2012, 4, 13),
                notes: "John has been in the Audio/Video industry since 1990. He has led DevAv as its CEO since 2003."
            },
            calendarOptions: { value: new Date() },
            textAreaOptions: { placeholder: 'Add notes...' }
        }
    }
}
</script>
React
App.js
import React from 'react';

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

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

import Calendar from 'devextreme-react/calendar';
import TextArea from 'devextreme-react/text-area';

const calendarOptions = { value: new Date() };
const textAreaOptions = { placeholder: 'Add notes...' };

class App extends React.Component {
    employee = {
        name: "John Heart",
        hireDate: new Date(2012, 4, 13),
        notes: "John has been in the Audio/Video industry since 1990. He has led DevAv as its CEO since 2003."
    }

    render() {
        return (
            <Form
                formData={this.employee}>
                <SimpleItem dataField="name" />
                <SimpleItem
                    dataField="hireDate"
                    editorType="dxCalendar"
                    editorOptions={calendarOptions}
                />
                <SimpleItem
                    dataField="notes"
                    editorType="dxTextArea"
                    editorOptions={textAreaOptions}
                />
            </Form>
        );
    }
}
export default App;

View Demo

Customize a Simple Item

If none of the available editors suit your requirements, you can define a custom one or even place anything you find useful instead. For this purpose, implement a custom template and pass it to the template property.

jQuery
JavaScript
$(function() {
    $("#formContainer").dxForm({
        formData: {
            name: "John Heart",
            picture: "https://js.devexpress.com/Content/images/doc/24_1/PhoneJS/person2.png",
            notes: "John has been in the Audio/Video industry since 1990. He has led DevAv as its CEO since 2003."
        },
        items: ["name", { 
            dataField: "notes",
            template: function (data, itemElement) {
                itemElement.append( $("<div id='textAreaContainer'>")
                           .dxTextArea({
                               value: data.component.option('formData')[data.dataField],
                               onValueChanged: function(e) {
                                   data.component.updateData(data.dataField, e.value);
                               }
                           });
                )
            }
        }, {
            dataField: "picture",
            template: function (data, itemElement) {
                itemElement.append("<img src='" + data.editorOptions.value + "'>");
            }
        }]
    });
});
Angular
HTML
TypeScript
<dx-form
    [(formData)]="employee">
    <dxi-item dataField="name"></dxi-item>
    <dxi-item 
        dataField="notes"
        [template]="'notesTemplate'">
    </dxi-item>
    <dxi-item 
        dataField="picture" 
        [template]="'pictureTemplate'">
    </dxi-item>
    <div *dxTemplate="let data of 'notesTemplate'">
        <dx-text-area [(value)]="employee.notes"></dx-text-area>
    </div>
    <div *dxTemplate="let data of 'pictureTemplate'">
        <img src="{{data.editorOptions.value}}">
    </div>
</dx-form>
import { DxFormModule, DxTextAreaModule } from "devextreme-angular";
// ...
export class AppComponent {
    employee = {
        name: "John Heart",
        picture: "https://js.devexpress.com/Content/images/doc/24_1/PhoneJS/person2.png",
        notes: "John has been in the Audio/Video industry since 1990. He has led DevAv as its CEO since 2003."
    }
}
@NgModule({
    imports: [
        // ...
        DxFormModule,
        DxTextAreaModule
    ],
    // ...
})
Vue
App.vue
<template>
    <DxForm
        :form-data="employee">
        <DxSimpleItem
            data-field="name"
        />
        <DxSimpleItem
            data-field="notes"
            template="notes"
        />
        <DxSimpleItem
            data-field="picture"
            template="picture"
        />
        <template #notes>
            <DxTextArea
                v-model:value="employee.notes"
            />
        </template>
        <template #picture="{ data }">
            <img :src="data.editorOptions.value">
        </template>
    </DxForm>
</template>

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

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

export default {
    components: {
        DxForm,
        DxSimpleItem,
        DxTextArea
    },
    data() {
        return {
            employee: {
                name: "John Heart",
                picture: "https://js.devexpress.com/Content/images/doc/24_1/PhoneJS/person2.png",
                notes: "John has been in the Audio/Video industry since 1990. He has led DevAv as its CEO since 2003."
            }
        }
    }
}
</script>
React
App.js
import React from 'react';

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

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

const renderPicture = (data) => <img src={data.editorOptions.value} />

class App extends React.Component {     
    constructor(props) {
        super(props);
        this.state = {
             employee: {
                name: "John Heart",
                picture: "https://js.devexpress.com/Content/images/doc/24_1/PhoneJS/person2.png",
                notes: "John has been in the Audio/Video industry since 1990. He has led DevAv as its CEO since 2003."
            }       
        };
    }

    setNotes = (e) => {
        this.setState(prevState => ({
            employee: {
                ...prevState.employee,
                notes: e.value
            }
        }))
    }

    renderNotes = (data) => {
        return (
            <TextArea
                value={this.state.employee.notes}
                onValueChanged={this.setNotes}
            />
        );
    }

    render() {
        return (
            <Form
                formData={this.state.employee}>
                <SimpleItem dataField="name" />
                <SimpleItem
                    dataField="notes"
                    render={this.renderNotes}
                />
                <SimpleItem
                    dataField="picture"
                    render={renderPicture}
                />
            </Form>
        );
    }
}
export default App;

View Demo View on GitHub

A simple item can be accompanied by a line of text that gives a hint, for example, of the values that this item accepts. To specify this text, use the helpText property. If filling an item is required, assign true to its isRequired property. In this case, a special mark appears near the item. For more information, see the Additional Marks topic.

jQuery
JavaScript
$(function() {
    $("#formContainer").dxForm({
        formData: {
            name: "John Heart",
            phone: "+1(360)684-1334"
        },
        items: [{ 
            dataField: "name",
            isRequired: true
        }, {
            dataField: "phone",
            helpText: "Example: +1(111)111-1111"
        }]
    });
});
Angular
HTML
TypeScript
<dx-form
    [(formData)]="employee">
    <dxi-item dataField="name" [isRequired]="true"></dxi-item>
    <dxi-item dataField="phone" helpText="Example: +1(111)111-1111"></dxi-item>
</dx-form>
import { DxFormModule } from "devextreme-angular";
// ...
export class AppComponent {
    employee = {
        name: "John Heart",
        phone: "+1(360)684-1334"
    }
}
@NgModule({
    imports: [
        // ...
        DxFormModule
    ],
    // ...
})
Vue
App.vue
<template>
    <DxForm
        :form-data="employee">
        <DxSimpleItem
            data-field="name"
            :is-required="true"
        />
        <DxSimpleItem
            data-field="phone"
            help-text="Example: +1(111)111-1111"
        />
    </DxForm>
</template>

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

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

export default {
    components: {
        DxForm,
        DxSimpleItem
    },
    data() {
        return {
            employee: {
                name: "John Heart",
                phone: "+1(360)684-1334"
            }
        }
    }
}
</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 {     
    employee = {
        name: "John Heart",
        phone: "+1(360)684-1334"
    }  

    render() {
        return (
            <Form
                formData={this.employee}>
                <SimpleItem
                    dataField="name"
                    isRequired={true}
                />
                <SimpleItem
                    dataField="phone"
                    helpText="Example: +1(111)111-1111"
                />
            </Form>
        );
    }
}
export default App;

You can modify automatically generated items using the customizeItem function. This function is called for each item before it is rendered. To access the item, use the function's parameter. Its structure mirrors the Simple Item structure, therefore, you can modify any property available for a simple item.

jQuery
JavaScript
$(function() {
    $("#formContainer").dxForm({
        formData: {
            firstName: "John",
            lastName: "Heart",
            email: "jheart@dx-email.com",
            phone: "+1(213) 555-9392"
        },
        customizeItem: function (item) {
            if(item.itemType == "simple") {
                item.label = {
                    location: "top"
                };
                if(item.dataField === "email" || item.dataField === "phone") {
                    item.colSpan = 3;
                }
                if(item.dataField === "phone") {
                    item.helpText = "Example: +1 (111) 111-1111";
                }
            }
        }
    });
});
Angular
HTML
TypeScript
<dx-form
    [(formData)]="employee"
    [customizeItem]="form_customizeItem">
</dx-form>
import { DxFormModule } from "devextreme-angular";
// ...
export class AppComponent {
    employee = {
        firstName: "John",
        lastName: "Heart",
        email: "jheart@dx-email.com",
        phone: "+1(213) 555-9392"
    }
    form_customizeItem(item) {
        if(item.itemType == "simple") {
            item.label = {
                location: "top"
            };
            if(item.dataField === "email" || item.dataField === "phone") {
                item.colSpan = 3;
            }
            if(item.dataField === "phone") {
                item.helpText = "Example: +1 (111) 111-1111";
            }
        }
    }
}
@NgModule({
    imports: [
        // ...
        DxFormModule
    ],
    // ...
})
Vue
App.vue
<template>
    <DxForm
        :form-data="employee"
        :customize-item="customizeItem">
    </DxForm>
</template>

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

import DxForm from 'devextreme-vue/form';

export default {
    components: {
        DxForm
    },
    data() {
        return {
            employee: {
                firstName: "John",
                lastName: "Heart",
                email: "jheart@dx-email.com",
                phone: "+1(213) 555-9392"
            }
        }
    },
    methods: {
        customizeItem(item) {
            if(item.itemType == "simple") {
                item.label = {
                    location: "top"
                }
                if(item.dataField === "email" || item.dataField === "phone") {
                    item.colSpan = 3;
                }
                if(item.dataField === "phone") {
                    item.helpText = "Example: +1 (111) 111-1111";
                }
            }
        }
    }
}
</script>
React
App.js
import React from 'react';

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

import Form from 'devextreme-react/form';

class App extends React.Component {     
    employee = {
        firstName: "John",
        lastName: "Heart",
        email: "jheart@dx-email.com",
        phone: "+1(213) 555-9392"
    }

    customizeItem(item) {
        if(item.itemType == "simple") {
            item.label = {
                location: "top"
            }
            if(item.dataField === "email" || item.dataField === "phone") {
                item.colSpan = 3;
            }
            if(item.dataField === "phone") {
                item.helpText = "Example: +1 (111) 111-1111";
            }
        }
    }

    render() {
        return (
            <Form
                formData={this.employee}
                customizeItem={this.customizeItem}>
            </Form>
        );
    }
}
export default App;
NOTE
The customizeItem function is called for each item including group, tabbed and empty items, although such items can be declared only in the items array, and there is no need to customize them afterwards. Therefore, we recommend you to check the itemType property to ensure that the item you are going to customize is indeed a simple item.
See Also

Create an Unbound Simple Item

If you do not need a simple item to be bound to a formData field, create an unbound item. It can be useful if you need, for example, to hide or show some additional information. To create such an item, specify its name, but do not set its dataField property. You will be able to access the item by this name if you need to.

In the following example, the order item contains the DataGrid UI component. This UI component is shown only when the CheckBox in the show-order item is checked. Both the order and show-order items are unbound items.

jQuery
JavaScript
$(function () {
    var isOrderShown = false;
    var form = $("#form").dxForm({
        formData: {
            firstName: "John",
            lastName: "Smith"
        },
        items: [
            "firstName", "lastName", {
                name: "show-order",
                label: {
                    text: "Show the order"
                },
                template: function (data, $itemElement) {
                    $("<div>").appendTo($itemElement).dxCheckBox({
                        value: isOrderShown,
                        onValueChanged: function(e) {
                            isOrderShown = e.value;
                            form.itemOption("order", "visible", isOrderShown);
                        }
                    });
                }
            }, {
                name: "order",
                visible: isOrderShown,
                template: function (data, $itemElement) {
                    $("<div id='dataGrid'>")
                        .appendTo($itemElement)
                        .dxDataGrid({
                            dataSource: [{
                                productName: "DesktopLCD 19",
                                cost: 68,
                                salePrice: 110
                            }, {
                                productName: "DesktopLCD 21",
                                cost: 75,
                                salePrice: 120
                            }]
                        });
                }
            }
        ]
    }).dxForm("instance");
});
Angular
HTML
TypeScript
<dx-form
    [(formData)]="employee">
    <dxi-item dataField="firstName"></dxi-item>
    <dxi-item dataField="lastName"></dxi-item>
    <dxi-item name="show-order">
        <dxo-label text="Show the Order"></dxo-label>
        <div *dxTemplate>
            <dx-check-box
                [(value)]="order.visible">
            </dx-check-box>
        </div>
    </dxi-item>
    <dxi-item #order name="order"
        [visible]="false">
        <div *dxTemplate>
            <dx-data-grid
                [dataSource]="orders">
            </dx-data-grid>
        </div>
    </dxi-item>
</dx-form>
import { DxFormModule, DxCheckBoxModule, DxDataGridModule } from "devextreme-angular";
// ...
export class AppComponent {
    employee = {
        firstName: "John",
        lastName: "Smith"
    }
    orders = [{
        productName: "DesktopLCD 19",
        cost: 68,
        salePrice: 110
    }, {
        productName: "DesktopLCD 21",
        cost: 75,
        salePrice: 120
    }]
}
@NgModule({
    imports: [
        // ...
        DxFormModule,
        DxCheckBoxModule,
        DxDataGridModule
    ],
    // ...
})
Vue
App.vue
<template>
    <DxForm
        :form-data="employee">
        <DxSimpleItem data-field="firstName" />
        <DxSimpleItem data-field="lastName" />
        <DxSimpleItem name="showOrder">
            <DxLabel text="Show the Order" />
            <template #default>
                <DxCheckBox v-model:value="isOrderVisible" />
            </template>
        </DxSimpleItem>
        <DxSimpleItem 
            name="order"
            :visible="isOrderVisible">
            <template #default>
                <DxDataGrid :data-source="orders" />
            </template>
        </DxSimpleItem>
    </DxForm>
</template>

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

import DxForm, {
    DxSimpleItem,
    DxLabel
} from 'devextreme-vue/form';
import DxCheckBox from 'devextreme-vue/check-box';
import DxDataGrid from 'devextreme-vue/data-grid';

export default {
    components: {
        DxForm,
        DxSimpleItem,
        DxLabel,
        DxCheckBox,
        DxDataGrid
    },
    data() {
        return {
            employee: {
                firstName: "John",
                lastName: "Smith"
            },
            orders: [{
                productName: "DesktopLCD 19",
                cost: 68,
                salePrice: 110
            }, {
                productName: "DesktopLCD 21",
                cost: 75,
                salePrice: 120
            }],
            isOrderVisible: false
        }
    }
}
</script>
React
App.js
import React from 'react';

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

import Form, {
    SimpleItem,
    Label
} from 'devextreme-react/form';
import CheckBox from 'devextreme-react/check-box';
import DataGrid from 'devextreme-react/data-grid';

class App extends React.Component {
    constructor(props) {
        super(props);
        this.state = {
            isOrderVisible: false
        };
        this.renderCheckBox = this.renderCheckBox.bind(this);
        this.handleCheckBoxValueChange = this.handleCheckBoxValueChange.bind(this);
        this.renderDataGrid = this.renderDataGrid.bind(this);
    }

    employee = {
        firstName: "John",
        lastName: "Smith"
    }
    orders = [{
        productName: "DesktopLCD 19",
        cost: 68,
        salePrice: 110
    }, {
        productName: "DesktopLCD 21",
        cost: 75,
        salePrice: 120
    }]

    renderCheckBox = () => {
        return (
            <CheckBox
                value={this.state.isOrderVisible}
                onValueChanged={this.handleCheckBoxValueChange}
            />
        );
    }

    handleCheckBoxValueChange = (e) => {
        this.setState({
            isOrderVisible: e.value
        });
    }

    renderDataGrid = () => {
        return <DataGrid dataSource={this.orders} />
    }

    render() {
        return (
            <Form
                formData={this.employee}>
                <SimpleItem dataField="firstName" />
                <SimpleItem dataField="lastName" />
                <SimpleItem
                    name="showOrder"
                    render={this.renderCheckBox}>
                    <Label text="Show the Order" />
                </SimpleItem>
                <SimpleItem 
                    name="order"
                    visible={this.state.isOrderVisible}
                    render={this.renderDataGrid}
                />
            </Form>
        );
    }
}
export default App;
See Also