Angular Form - SimpleItem
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.
cssClass
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.
dataField
Specifies the path to the formData object field bound to the current form item.
For instance, use standard JavaScript syntax to specify the path to the field if your data includes nested items:
jQuery
$(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
<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
<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
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;
},
}; editorOptions
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.
<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
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.
<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
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.
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;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
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.
See Also
helpText
See Also
isRequired
If you specify validation rules using the validationRules property, the isRequired property is ignored. In this case, use the Require validation rule instead.
jQuery
$(function() {
$("#formContainer").dxForm({
// ...
items: [{
// ...
validationRules: [
{ type: "required" }
]
},
// ...
]
});
});Angular
<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
<template>
<DxForm ...>
<DxSimpleItem ...>
<DxRequiredRule .../>
</DxSimpleItem>
</DxForm>
</template>
<script>
import DxForm, { DxSimpleItem, DxRequiredRule } from 'devextreme-vue/form';
export default {
components: {
DxForm,
DxSimpleItem,
DxRequiredRule
}
}
</script>React
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
name
Use the name instead of the data field to access unbound simple items in methods like getEditor(dataField), itemOption(id), etc.
template
jQuery
$(() => {
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:
<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:
<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:
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>
);
}See Also
validationRules
Array<RequiredRule | NumericRule | RangeRule | StringLengthRule | CustomRule | CompareRule | PatternRule | EmailRule | AsyncRule>
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.
See Also
If you have technical questions, please create a support ticket in the DevExpress Support Center.