devextreme/ui/form.d.ts

HTML5 JavaScript Component Suite for Responsive Web Development

/**
* DevExtreme (ui/form.d.ts)
* Version: 25.2.3
* Build date: Fri Dec 12 2025
*
* Copyright (c) 2012 - 2025 Developer Express Inc. ALL RIGHTS RESERVED
* Read about DevExtreme licensing here: https://js.devexpress.com/Licensing/
*/
import { AIIntegration, SmartPasteResultFieldType } from '../common/ai-integration';
import {
    UserDefinedElement,
    DxElement,
} from '../core/element';

import {
    DxPromise,
} from '../core/utils/deferred';

import {
    template,
    AsyncRule,
    CompareRule,
    CustomRule,
    EmailRule,
    HorizontalAlignment,
    Mode,
    NumericRule,
    PatternRule,
    RangeRule,
    RequiredRule,
    StringLengthRule,
    VerticalAlignment,
} from '../common';

import {
  AsyncCancelable,
  EventInfo,
  InitializedEventInfo,
  ChangedOptionInfo,
} from '../events';

import dxButton, {
    dxButtonOptions,
} from './button';

import Editor from './editor/editor';

import {
    dxTabPanelOptions,
} from './tab_panel';

import {
    ValidationResult,
} from './validation_group';

import Widget, {
    WidgetOptions,
} from './widget/ui.widget';

export {
    HorizontalAlignment,
    Mode,
    VerticalAlignment,
};

export type FormItemComponent = 'dxAutocomplete' | 'dxCalendar' | 'dxCheckBox' | 'dxColorBox' | 'dxDateBox' | 'dxDateRangeBox' | 'dxDropDownBox' | 'dxHtmlEditor' | 'dxLookup' | 'dxNumberBox' | 'dxRadioGroup' | 'dxRangeSlider' | 'dxSelectBox' | 'dxSlider' | 'dxSwitch' | 'dxTagBox' | 'dxTextArea' | 'dxTextBox';
export type FormItemType = 'empty' | 'group' | 'simple' | 'tabbed' | 'button';
export type LabelLocation = 'left' | 'right' | 'top';
export type FormLabelMode = 'static' | 'floating' | 'hidden' | 'outside';
export type FormPredefinedButtonItem = 'reset' | 'submit' | 'smartPaste';

export type AIResult = Record<string, SmartPasteResultFieldType>;

/**
 * 
 * @deprecated Attention! This type is for internal purposes only. If you used it previously, please submit a ticket to our {@link https://supportcenter.devexpress.com/ticket/create Support Center}. We will check if there is an alternative solution.
 */
export type SmartPasteInfo = {
  /**
   * Specifies Smart Paste results. Data from this object populates the Form.
   */
  readonly aiResult: AIResult;
};

/**
 * The argument type in the contentReady event.
 */
export type ContentReadyEvent = EventInfo<dxForm>;

/**
 * The argument type in the disposing event.
 */
export type DisposingEvent = EventInfo<dxForm>;

/**
 * The argument type in the editorEnterKey event.
 */
export type EditorEnterKeyEvent = EventInfo<dxForm> & {
    /**
     * 
     */
    readonly dataField?: string;
};

/**
 * The argument type in the fieldDataChanged event.
 */
export type FieldDataChangedEvent = EventInfo<dxForm> & {
    /**
     * 
     */
    readonly dataField?: string;
    /**
     * 
     */
    readonly value?: any;
};

/**
 * The argument type in the initialized event.
 */
export type InitializedEvent = InitializedEventInfo<dxForm>;

/**
 * The argument type in the optionChanged event.
 */
export type OptionChangedEvent = EventInfo<dxForm> & ChangedOptionInfo;

/**
 * The argument type in the smartPasting event.
 */
export type SmartPastingEvent = EventInfo<dxForm> & AsyncCancelable & SmartPasteInfo;

/**
 * The argument type in the smartPasted event.
 */
export type SmartPastedEvent = EventInfo<dxForm> & SmartPasteInfo;

export type GroupItemTemplateData = {
    readonly component: dxForm;
    readonly formData?: any;
};

export type GroupCaptionTemplateData = {
    readonly caption?: string;
    readonly component: dxForm;
    readonly name?: string;
};

export type SimpleItemTemplateData = {
    readonly component: dxForm;
    readonly dataField?: string;
    readonly editorOptions?: any;
    readonly editorType?: string;
    readonly name?: string;
};

export type SimpleItemLabelTemplateData = SimpleItemTemplateData & { text: string };

/**
 * 
 * @deprecated 
 * @deprecated Attention! This type is for internal purposes only. If you used it previously, please submit a ticket to our {@link https://supportcenter.devexpress.com/ticket/create Support Center}. We will check if there is an alternative solution.
 */
export interface dxFormOptions extends WidgetOptions<dxForm> {
    /**
     * Binds the Form to an AI service.
     */
    aiIntegration?: AIIntegration | undefined;
    /**
     * Specifies whether all item labels are aligned. Applies only to labels outside their editors (see labelMode).
     */
    alignItemLabels?: boolean;
    /**
     * Specifies whether item labels in all groups are aligned. Applies only to labels outside their editors (see labelMode).
     */
    alignItemLabelsInAllGroups?: boolean;
    /**
     * The count of columns in the form layout.
     */
    colCount?: number | Mode;
    /**
     * Specifies the number of Form columns for different screen sizes.
     */
    colCountByScreen?: any | undefined;
    /**
     * Specifies a function that customizes a form item after it has been created.
     */
    customizeItem?: ((item: Item) => void);
    /**
     * Provides the Form&apos;s data. Gets updated every time form fields change.
     */
    formData?: any;
    /**
     * Holds an array of form items.
     */
    items?: Array<Item> | undefined;
    /**
     * Specifies the location of a label against the editor. Applies only to labels outside their editors (see labelMode).
     */
    labelLocation?: LabelLocation;
    /**
     * Specifies a display mode for item labels.
     */
    labelMode?: FormLabelMode;
    /**
     * The minimum column width used for calculating column count in the form layout. Applies only if colCount property is &apos;auto&apos;.
     */
    minColWidth?: number;
    /**
     * A function that is executed when the Enter key has been pressed while an editor is focused.
     */
    onEditorEnterKey?: ((e: EditorEnterKeyEvent) => void);
    /**
     * A function that is executed when the value of a formData object field is changed.
     */
    onFieldDataChanged?: ((e: FieldDataChangedEvent) => void);
    /**
     * A function that is executed before an AI service populates the Form.
     */
    onSmartPasting?: ((e: SmartPastingEvent) => void);
    /**
     * A function that is executed after an AI service populates the Form.
     */
    onSmartPasted?: ((e: SmartPastedEvent) => void);
    /**
     * The text displayed for optional fields. Applies only if showOptionalMark is true.
     */
    optionalMark?: string;
    /**
     * Specifies whether all editors on the form are read-only. Applies only to non-templated items.
     */
    readOnly?: boolean;
    /**
     * The text displayed for required fields.
     */
    requiredMark?: string;
    /**
     * Specifies the message that is shown for end-users if a required field value is not specified.
     */
    requiredMessage?: string;
    /**
     * Specifies a function that categorizes screens by their width.
     */
    screenByWidth?: Function;
    /**
     * A Boolean value specifying whether to enable or disable form scrolling.
     */
    scrollingEnabled?: boolean;
    /**
     * Specifies whether a colon is displayed at the end of form labels. Applies only to labels outside their editors (see labelMode).
     */
    showColonAfterLabel?: boolean;
    /**
     * Specifies whether or not the optional mark is displayed for optional fields.
     */
    showOptionalMark?: boolean;
    /**
     * Specifies whether or not the required mark is displayed for required fields.
     */
    showRequiredMark?: boolean;
    /**
     * Specifies whether or not the total validation summary is displayed on the form.
     */
    showValidationSummary?: boolean;
    /**
     * Gives a name to the internal validation group.
     */
    validationGroup?: string | undefined;
    /**
     * Specifies whether current editor values differ from initial values.
     */
    readonly isDirty?: boolean;
}
/**
 * The Form UI component represents fields of a data object as a collection of label-editor pairs. These pairs can be arranged in several groups, tabs and columns.
 */
export default class dxForm extends Widget<dxFormOptions> {
    /**
     * Gets a button&apos;s instance.
     */
    getButton(name: string): dxButton | undefined;
    /**
     * Gets an editor instance. Takes effect only if the form item is visible.
     */
    getEditor(dataField: string): Editor | undefined;
    /**
     * Gets a form item&apos;s configuration.
     */
    itemOption(id: string): any;
    /**
     * Updates the value of a single item option.
     */
    itemOption(id: string, option: string, value: any): void;
    /**
     * Updates the values of several item properties.
     */
    itemOption(id: string, options: any): void;
    /**
     * Resets editor values to their default values.
     */
    clear(): void;
    /**
     * Resets editors to specified or initial values.
     */
    reset(editorsData?: Record<string, any>): void;
    /**
     * Populates the Form with AI-generated values based on supplied text.
     */
    smartPaste(text?: string): void;
    /**
     * Merges the passed `data` object with formData. Matching properties in formData are overwritten and new properties added.
     */
    updateData(data: any): void;
    /**
     * Updates a formData field and the corresponding editor.
     */
    updateData(dataField: string, value: any): void;
    /**
     * Updates the dimensions of the UI component contents.
     */
    updateDimensions(): DxPromise<void>;
    /**
     * Validates the values of all editors on the form against the list of the validation rules specified for each form item.
     */
    validate(): ValidationResult;
}

export type Item = SimpleItem | GroupItem | TabbedItem | EmptyItem | ButtonItem;

export type ButtonItem = dxFormButtonItem;

/**
 * @deprecated Use ButtonItem instead
 * @deprecated Attention! This type is for internal purposes only. If you used it previously, please submit a ticket to our {@link https://supportcenter.devexpress.com/ticket/create Support Center}. We will check if there is an alternative solution.
 */
export interface dxFormButtonItem {
    /**
     * Configures the button.
     */
    buttonOptions?: dxButtonOptions | undefined;
    /**
     * Specifies how many columns the item spans.
     */
    colSpan?: number | undefined;
    /**
     * Specifies a CSS class to be applied to the item.
     */
    cssClass?: string | undefined;
    /**
     * Specifies the button&apos;s horizontal alignment.
     */
    horizontalAlignment?: HorizontalAlignment;
    /**
     * Specifies the item&apos;s type. Set it to &apos;button&apos; to create a button item.
     */
    itemType?: FormItemType;
    /**
     * Specifies the item&apos;s identifier.
     */
    name?: FormPredefinedButtonItem | string | undefined;
    /**
     * Specifies the button&apos;s vertical alignment.
     */
    verticalAlignment?: VerticalAlignment;
    /**
     * Specifies whether the item is visible.
     */
    visible?: boolean;
    /**
     * Specifies the item&apos;s position regarding other items in a group, tab, or the whole UI component.
     */
    visibleIndex?: number | undefined;
}

export type EmptyItem = dxFormEmptyItem;

/**
 * @deprecated Use EmptyItem instead
 * @deprecated Attention! This type is for internal purposes only. If you used it previously, please submit a ticket to our {@link https://supportcenter.devexpress.com/ticket/create Support Center}. We will check if there is an alternative solution.
 */
export interface dxFormEmptyItem {
    /**
     * Specifies the number of columns spanned by the item.
     */
    colSpan?: number | undefined;
    /**
     * Specifies a CSS class to be applied to the form item.
     */
    cssClass?: string | undefined;
    /**
     * Specifies the item&apos;s type. Set it to &apos;empty&apos; to create an empty item.
     */
    itemType?: FormItemType;
    /**
     * Specifies a name that identifies the form item.
     */
    name?: string | undefined;
    /**
     * Specifies whether or not the current form item is visible.
     */
    visible?: boolean;
    /**
     * Specifies the sequence number of the item in a form, group or tab.
     */
    visibleIndex?: number | undefined;
}

export type GroupItem = dxFormGroupItem;

/**
 * @deprecated Use GroupItem instead
 * @deprecated Attention! This type is for internal purposes only. If you used it previously, please submit a ticket to our {@link https://supportcenter.devexpress.com/ticket/create Support Center}. We will check if there is an alternative solution.
 */
export interface dxFormGroupItem {
    /**
     * Specifies whether or not all group item labels are aligned.
     */
    alignItemLabels?: boolean;
    /**
     * Specifies the group caption.
     */
    caption?: string | undefined;
    /**
     * Specifies a template that can be used to replace group captions with custom content.
     */
    captionTemplate?: template | ((data: GroupCaptionTemplateData, itemElement: DxElement) => string | UserDefinedElement);
    /**
     * The count of columns in the group layout.
     */
    colCount?: number;
    /**
     * Specifies the relation between the screen size qualifier and the number of columns in the grouped layout.
     */
    colCountByScreen?: any | undefined;
    /**
     * Specifies the number of columns spanned by the item.
     */
    colSpan?: number | undefined;
    /**
     * Specifies a CSS class to be applied to the form item.
     */
    cssClass?: string | undefined;
    /**
     * Specifies the item&apos;s type. Set it to &apos;group&apos; to create a group item.
     */
    itemType?: FormItemType;
    /**
     * Holds an array of form items displayed within the group.
     */
    items?: Array<Item> | undefined;
    /**
     * Specifies a name that identifies the form item.
     */
    name?: string | undefined;
    /**
     * A template to be used for rendering a group item.
     */
    template?: template | ((data: GroupItemTemplateData, itemElement: DxElement) => string | UserDefinedElement);
    /**
     * Specifies whether or not the current form item is visible.
     */
    visible?: boolean;
    /**
     * Specifies the sequence number of the item in a form, group or tab.
     */
    visibleIndex?: number | undefined;
}

export type SimpleItem = dxFormSimpleItem;

/**
 * @deprecated Use SimpleItem instead
 * @deprecated Attention! This type is for internal purposes only. If you used it previously, please submit a ticket to our {@link https://supportcenter.devexpress.com/ticket/create Support Center}. We will check if there is an alternative solution.
 */
export interface dxFormSimpleItem {
    /**
     * Specifies options for an AI service that parses Smart Paste data.
     */
    aiOptions?: {
      /**
       * Specifies an individual item instruction for the AI service.
       */
      instruction?: string | undefined;
      /**
       * Marks the item as disabled for AI processing.
       */
      disabled?: boolean;
    };
    /**
     * Specifies the number of columns spanned by the item.
     */
    colSpan?: number | undefined;
    /**
     * Specifies a CSS class to be applied to the form item.
     */
    cssClass?: string | undefined;
    /**
     * Specifies the path to the formData object field bound to the current form item.
     */
    dataField?: string | undefined;
    /**
     * Configures the form item&apos;s editor.
     */
    editorOptions?: any | undefined;
    /**
     * Specifies which editor UI component is used to display and edit the form item value.
     */
    editorType?: FormItemComponent;
    /**
     * Specifies the help text displayed for the current form item.
     */
    helpText?: string | undefined;
    /**
     * Specifies if the current form item is required.
     */
    isRequired?: boolean | undefined;
    /**
     * Specifies the item&apos;s type. Set it to &apos;simple&apos; to create a simple item.
     */
    itemType?: FormItemType;
    /**
     * Specifies properties for the form item label.
     */
    label?: {
      /**
       * Specifies the label&apos;s horizontal alignment. Applies only to labels outside their editors (see labelMode).
       */
      alignment?: HorizontalAlignment;
      /**
       * Specifies the location of a label against the editor. Applies only to labels outside their editors (see labelMode).
       */
      location?: LabelLocation;
      /**
       * Specifies whether a colon is displayed at the end of the current label. Applies only to labels outside their editors (see labelMode).
       */
      showColon?: boolean;
      /**
       * A template that can be used to replace the label with custom content. Applies only to labels outside their editors (see labelMode).
       */
      template?: template | ((itemData: SimpleItemLabelTemplateData, itemElement: DxElement) => string | UserDefinedElement);
      /**
       * Specifies the label text.
       */
      text?: string | undefined;
      /**
       * Controls the visibility of the label outside the editor.
       */
      visible?: boolean;
    };
    /**
     * Specifies a name that identifies the form item.
     */
    name?: string | undefined;
    /**
     * A template that can be used to replace the default editor with custom content.
     */
    template?: template | ((data: SimpleItemTemplateData, itemElement: DxElement) => string | UserDefinedElement);
    /**
     * An array of validation rules to be checked for the form item editor.
     */
    validationRules?: Array<RequiredRule | NumericRule | RangeRule | StringLengthRule | CustomRule | CompareRule | PatternRule | EmailRule | AsyncRule>;
    /**
     * Specifies whether or not the current form item is visible.
     */
    visible?: boolean;
    /**
     * Specifies the sequence number of the item in a form, group or tab.
     */
    visibleIndex?: number | undefined;
}

export type TabbedItem = dxFormTabbedItem;

/**
 * @deprecated Use TabbedItem instead
 * @deprecated Attention! This type is for internal purposes only. If you used it previously, please submit a ticket to our {@link https://supportcenter.devexpress.com/ticket/create Support Center}. We will check if there is an alternative solution.
 */
export interface dxFormTabbedItem {
    /**
     * Specifies the number of columns spanned by the item.
     */
    colSpan?: number | undefined;
    /**
     * Specifies a CSS class to be applied to the form item.
     */
    cssClass?: string | undefined;
    /**
     * Specifies the item&apos;s type. Set it to &apos;tabbed&apos; to create a tabbed item.
     */
    itemType?: FormItemType;
    /**
     * Specifies a name that identifies the form item.
     */
    name?: string | undefined;
    /**
     * Holds a configuration object for the TabPanel UI component used to display the current form item.
     */
    tabPanelOptions?: dxTabPanelOptions | undefined;
    /**
     * An array of tab configuration objects.
     */
    tabs?: Array<{
      /**
       * Specifies whether or not labels of items displayed within the current tab are aligned.
       */
      alignItemLabels?: boolean;
      /**
       * Specifies a badge text for the tab.
       */
      badge?: string | undefined;
      /**
       * The count of columns in the tab layout.
       */
      colCount?: number;
      /**
       * Specifies the relation between the screen size qualifier and the number of columns in the tabbed layout.
       */
      colCountByScreen?: any | undefined;
      /**
       * Specifies whether the tab responds to user interaction.
       */
      disabled?: boolean;
      /**
       * Specifies the icon to be displayed on the tab.
       */
      icon?: string | undefined;
      /**
       * Holds an array of form items displayed within the tab.
       */
      items?: Array<Item> | undefined;
      /**
       * The template to be used for rendering the tab.
       */
      tabTemplate?: template | ((tabData: any, tabIndex: number, tabElement: DxElement) => any) | undefined;
      /**
       * The template to be used for rendering the tab content.
       */
      template?: template | ((tabData: any, tabIndex: number, tabElement: DxElement) => any) | undefined;
      /**
       * Specifies the tab title.
       */
      title?: string | undefined;
    }>;
    /**
     * Specifies whether or not the current form item is visible.
     */
    visible?: boolean;
    /**
     * Specifies the sequence number of the item in a form, group or tab.
     */
    visibleIndex?: number | undefined;
}

export type Properties = dxFormOptions;

/**
 * @deprecated use Properties instead
 * @deprecated Attention! This type is for internal purposes only. If you used it previously, please submit a ticket to our {@link https://supportcenter.devexpress.com/ticket/create Support Center}. We will check if there is an alternative solution.
 */
export type Options = dxFormOptions;

// TODO: temporary commented out to fix jquery generation error in R1

//