@progress/kendo-react-form

/** * @license *------------------------------------------------------------------------------------------- * Copyright © 2025 Progress Software Corporation. All rights reserved. * Licensed under commercial license. See LICENSE.md in the package root for more information *------------------------------------------------------------------------------------------- */ import { default as default_2 } from 'prop-types'; import { FieldRenderPropsBase } from '@progress/kendo-react-common'; import { FormClassStructure } from '@progress/kendo-react-common'; import { ForwardRefExoticComponent } from 'react'; import { JSX } from 'react/jsx-runtime'; import * as React_2 from 'react'; import { RefAttributes } from 'react'; /** * Represents the Field component that is used inside the KendoReact Form component. * It uses `name` property to access field value and meta information from Form state. */ export declare const Field: { (props: FieldProps & { [customProp: string]: any; }): React_2.ReactElement<any, string | React_2.JSXElementConstructor<any>> | null; displayName: string; }; /** * Represents the FieldArray component that is used inside the KendoReact Form component. * It provides methods via render props for common array manipulations. */ export declare const FieldArray: React_2.FunctionComponent<FieldArrayProps>; /** * Contains the props for the FieldArray component that you use inside forms. */ export declare interface FieldArrayProps { /** * Sets the field name in the form state. */ name: string; /** * Can be set to a React component. * [`FieldArrayRenderProps`]({% slug api_form_fieldarrayrenderprops %}). */ component: React.ComponentType<any>; /** * Validates the field array and returns error messages. * Only synchronous functions are supported. */ validator?: FieldValidatorType | FieldValidatorType[]; /** * Provides child elements that are passed to the rendered component. */ children?: any; /** * @hidden */ [customProp: string]: any; } /** * Contains props that are passed to components rendered inside FieldArray components. */ export declare interface FieldArrayRenderProps { /** * Represents the current value of the FieldArray * ([see example]({% slug custom_components_form %}#toc-using-basic-properties)). */ value: any; /** * Contains the error message from validation. * The field is valid when this is empty. */ validationMessage: string | null; /** * Shows whether the user has interacted with the field. * Becomes true when the field loses focus. */ touched: boolean; /** * Shows whether the field value has changed from its initial value. * Becomes true when the field value changes for the first time. */ modified: boolean; /** * Shows whether the user has focused on the field. * Becomes true when the field receives focus. */ visited: boolean; /** * Shows whether the field passes validation and has been touched. */ valid: boolean; /** * Contains child elements that are passed to the FieldArray. */ children: any; /** * Contains the field name in the form state. */ name: string; /** * Adds a value to the beginning of the array. */ onUnshift: (options: { value: any; }) => number; /** * Adds a value to the end of the array. */ onPush: (options: { value: any; }) => void; /** * Inserts a value at a specific position in the array. */ onInsert: (options: { value: any; index: number; }) => void; /** * Removes and returns the last value from the array. */ onPop: () => any; /** * Removes a value at a specific position in the array. */ onRemove: (options: { index: number; }) => any; /** * Replaces a value at a specific position in the array. */ onReplace: (options: { value: any; index: number; }) => void; /** * Moves a value from one position to another in the array. */ onMove: (options: { prevIndex: number; nextIndex: number; }) => void; /** * @hidden */ [customProp: string]: any; } /** * Contains the props for the Field component that you use inside forms. */ export declare interface FieldProps { /** * Sets the field name in the form state. * You can use nested fields like `user.age` and `users[0].name`. * * @example * ```jsx * <Field name="user.age" component="input" /> * ``` */ name: string; /** * Can be set to a React component or to the name of an HTML element, * for example, `input`, `select`, and `textarea`. * The props that are passed to the component are the * [`FieldRenderProps`]({% slug api_form_fieldrenderprops %}). * * @example * ```jsx * <Field name="user.name" component="input" /> * ``` */ component: string | React.ComponentType<any>; /** * Validates the field value and returns error messages. * * Only synchronous functions are supported. * Use `useMemo` to avoid infinite loops when using an array of validators. * * @example * ```jsx * const validator = value => value ? "" : "This field is required."; * <Field name="user.email" component="input" validator={validator} /> * ``` */ validator?: FieldValidatorType | FieldValidatorType[]; /** * Provides child elements that are passed to the rendered component. * * @example * ```jsx * <Field name="user.name" component="input"> * <span>Additional content</span> * </Field> * ``` */ children?: any; /** * Sets how many columns the field spans in the form layout. */ colSpan?: number | ResponsiveFormBreakPoint[]; /** * Handles changes to the field value. * * Use this to update related fields. The Form automatically updates its state when this fires. * * @example * ```jsx * const handleChange = event => console.log(event); * <Field name="user.name" component="input" onChange={handleChange} /> * ``` */ onChange?: (event: any) => void; } /** * Contains props that are passed to components rendered inside Field components. */ export declare interface FieldRenderProps extends FieldRenderPropsBase { } /** * Validates a single field and returns an error message or success. * * * value - Contains the current field value * * valueGetter - Gets values from other fields using field paths like 'user.name' * * fieldProps - Contains the field's props, including the field name * * Returns a string for validation errors or undefined for successful validation. */ export declare type FieldValidatorType = (value: any, valueGetter: (name: string) => any, fieldProps: { name: string; }) => string | undefined; /** * Represents the KendoReact FieldWrapper component. * It's designed to wrap the field editor, Label, Hint and Error components. * The FieldWrapper supports only single editor inside it. */ export declare const FieldWrapper: React_2.FunctionComponent<FieldWrapperProps>; /** * Represents the props of the KendoReact FieldWrapper component. */ export declare interface FieldWrapperProps { /** * @hidden */ children: any; /** * The styles that are applied to the FieldWrapper. */ style?: React_2.CSSProperties; /** * Sets a class for the FieldWrapper DOM element. */ className?: string; /** * Specifies the direction of the content. */ dir?: string; /** * Defines the colspan for the form field element related to the parent Form component columns. Can be a number or an array of responsive breakpoints. */ colSpan?: number | ResponsiveFormBreakPoint[]; /** * @hidden */ unstyled?: FormClassStructure; } /** @hidden */ export declare const Form: ForwardRefExoticComponent<FormProps & RefAttributes<any>>; /** * Represents the [KendoReact Form component]({% slug overview_form %}). * * @example * ```jsx * export const FormInput = (fieldRenderProps) => { * const onValueChange = React.useCallback( * (event) => fieldRenderProps.onChange(event.target.value), * [fieldRenderProps.onChange] * ); * return ( * <input * className={'k-input'} * value={fieldRenderProps.value} * onChange={onValueChange} * /> * ); * }; * * export const App = () => { * const handleSubmit = (dataItem) => alert(JSON.stringify(dataItem)); * return ( * <Form * initialValues={{title: ''}} * onSubmit={handleSubmit} * render={(formRenderProps) => ( * <div> * <Field name={'title'} component={FormInput} /> * <Button * disabled={!formRenderProps.allowSubmit} * onClick={formRenderProps.onSubmit} * > * Submit * </Button> * </div> * )} * /> * ); * }; * ``` */ export declare class FormClassComponent extends React_2.Component<FormProps, {}> { /** * @hidden */ static displayName: string; /** * @hidden */ static propTypes: { initialValues: default_2.Requireable<any>; onSubmit: default_2.Requireable<(...args: any[]) => any>; onSubmitClick: default_2.Requireable<(...args: any[]) => any>; render: default_2.Validator<(...args: any[]) => any>; id: default_2.Requireable<string>; }; private _key?; private _touched; private _visited; private _modified; private _validatorsByField; private _values; private _fields; private _unmounted; private _submitted; private readonly showLicenseWatermark; private readonly licenseMessage?; /** * @hidden */ private _accumulatorTimeout; /** * @hidden */ get touched(): KeyValue<boolean>; /** * @hidden */ set touched(value: KeyValue<boolean>); /** * @hidden */ get visited(): KeyValue<boolean>; /** * @hidden */ set visited(value: KeyValue<boolean>); /** * @hidden */ get modified(): KeyValue<boolean>; /** * @hidden */ set modified(value: KeyValue<boolean>); /** * @hidden */ get validatorsByField(): KeyValue<(FieldValidatorType | FieldValidatorType[] | undefined)[]>; /** * @hidden */ set validatorsByField(value: KeyValue<(FieldValidatorType | FieldValidatorType[] | undefined)[]>); /** * @hidden */ get values(): KeyValue<any>; /** * @hidden */ set values(value: KeyValue<any>); /** * @hidden */ get fields(): string[]; /** * @hidden */ get formErrors(): KeyValue<string> | undefined; /** * @hidden */ get errors(): KeyValue<string>; /** * @hidden */ constructor(props: FormProps); /** * @hidden */ componentWillUnmount(): void; /** * @hidden */ isValid: () => boolean; /** * @hidden */ accumulatedForceUpdate: () => void; /** * @hidden */ resetForm: () => void; /** * Method for resetting the form state outside the form component. * * > Use `onReset` only if you cannot achieve the desired behavior through the Field component or by FormRenderProps. */ onReset: () => void; /** * @hidden */ addField: (field: string) => void; /** * @hidden */ onSubmit: (event: React_2.SyntheticEvent<any>) => void; /** * Method for emiting changes to a specific field outside the form component. * * > Use `onChange` only if you cannot achieve the desired behavior through the Field component by FormRenderProps. */ onChange: (name: string, options: { value: any; }) => void; /** * @hidden */ onFocus: (name: string, skipForceUpdate?: boolean) => void; /** * @hidden */ onBlur: (name: string, skipForceUpdate?: boolean) => void; /** * @hidden */ onFieldRegister: (name: string, validator: FieldValidatorType | FieldValidatorType[] | undefined) => () => void; /** * @hidden */ isFormValid: (errors: KeyValue<any>) => boolean; /** * @hidden */ isFormModified: (modified: KeyValue<boolean>, fields: string[]) => boolean; /** * @hidden */ isFormHasNotTouched: (touched: KeyValue<boolean>, fields: string[]) => boolean; /** * @hidden */ isFormTouched: (touched: KeyValue<boolean>, fields: string[]) => boolean; /** * @hidden */ isFormVisited: (visited: KeyValue<boolean>, fields: string[]) => boolean; /** * @hidden */ valueGetter: (fieldName: string) => any; /** * @hidden */ valueSetter: (fieldName: string, value: any) => any; /** * @hidden */ onArrayAction: (name: string) => void; /** * @hidden */ onInsert: (name: string, options: { value: any; index: number; }) => void; /** * @hidden */ onUnshift: (name: string, options: { value: any; }) => void; /** * @hidden */ onPush: (name: string, options: { value: any; }) => void; /** * @hidden */ onPop: (name: string) => any; /** * @hidden */ onRemove: (name: string, options: { index: number; }) => any; /** * @hidden */ onReplace: (name: string, options: { value: any; index: number; }) => void; /** * @hidden */ onMove: (name: string, options: { prevIndex: number; nextIndex: number; }) => void; /** * @hidden */ render(): JSX.Element; } /** * Represents the KendoReact FormElement component. * It's small wrapper around HTML form element which automatically attach the * Form component's `onSubmit` render prop and Kendo CSS classes. * Other props are passed to the DOM node. */ export declare const FormElement: React_2.FunctionComponent<FormElementProps>; /** * Represent the `ref` of the FormElement component. */ export declare interface FormElementHandle { /** * Represents the props of the FormElement component. */ props: FormElementProps; /** * Represents the element of the FormElement component. */ element: HTMLFormElement | null; } /** * Represents the props of the KendoReact FormElement component. */ export declare interface FormElementProps { /** * @hidden */ children?: any; /** * The styles that are applied to the form DOM element. */ style?: React_2.CSSProperties; /** * Sets a class for the form DOM element. */ className?: string; /** * If set to `true` enable the horizontal layout of the form editors. */ horizontal?: boolean; /** * Sets the id of the form DOM element. Takes priority over the Form's id. */ id?: string; /** * Defines the number of columns in the form. Can be a number or an array of responsive breakpoints. */ cols?: number | ResponsiveFormBreakPoint[]; /** * Defines the gutters for the form. You can specify gutters for rows and columns. Number is equivalent to px. */ gutters?: string | number | Gutters | ResponsiveFormBreakPoint[]; /** * @hidden */ [customProp: string]: any; /** * Configures the `size` of the Form. * * The available options are: * - small * - medium * - large * - null—Does not set a size `className`. * * @default `medium` */ size?: null | 'small' | 'medium' | 'large'; /** * @hidden */ unstyled?: FormClassStructure; } /** * Represents the KendoReact FormFieldSet component. */ export declare const FormFieldSet: React_2.FunctionComponent<FormFieldSetProps>; /** * Represent the `ref` of the FormFieldSet component. */ export declare interface FormFieldSetHandle { /** * Represents the props of the FormFieldSet component. */ props: FormFieldSetProps; /** * Represents the element of the FormFieldSet component. */ element: HTMLFieldSetElement | null; } /** * Represents the props of the KendoReact FormFieldSet component. */ export declare interface FormFieldSetProps { /** * Defines the number of columns of the fieldset. Can be a number or an array of responsive breakpoints. */ cols?: number | ResponsiveFormBreakPoint[]; /** * Defines the colspan for the fieldset related to the parent Form component columns. Can be a number or an array of responsive breakpoints. */ colSpan?: number | ResponsiveFormBreakPoint[]; /** * Defines the gutters for the fieldset. You can specify gutters for rows and columns. Number is equivalent to px. */ gutters?: string | number | Gutters | ResponsiveFormBreakPoint[]; /** * Defines the legend for the fieldset. */ legend?: string; /** * @hidden */ children?: any; /** * The styles that are applied to the form DOM element. */ style?: React_2.CSSProperties; /** * Sets a class for the form DOM element. */ className?: string; } /** * Represent the `ref` of the Form component. */ export declare interface FormHandle extends Pick<FormClassComponent, keyof FormClassComponent> { } /** * Contains the props for the KendoReact Form component. */ export declare interface FormProps { /** * Sets the starting values for form fields. * * Set initial values to prevent errors when switching from uncontrolled to controlled mode. * * @example * ```jsx * const initialValues = { user: { name: '', age: 0 } }; * <Form initialValues={initialValues} render={props => <form>form content</form>} /> * ``` */ initialValues?: { [name: string]: any; }; /** * Validation errors that override field and form validators. * * Provides validation errors directly as an object, unlike the validator prop which expects a callback. * When both validator and errors exist for a field, the errors prop takes precedence. * * @example * ```jsx * const [errors, setErrors] = useState({}); * const handleSubmit = async (data) => { * const response = await submitToServer(data); * if (response.errors) { * setErrors(response.errors); * } * }; * <Form errors={errors} onSubmit={handleSubmit} render={props => <FormElement>form content</FormElement>} /> * ``` */ errors?: { [name: string]: string; }; /** * Fires each time any field value changes. * * The third parameter `valueGetter` allows accessing other field values, useful for cross-field validation or clearing related errors. * * @example * ```jsx * const handleChange = (fieldName, value, valueGetter) => { * // For nested fields like 'user.name', access related fields like 'user.email' * if (fieldName === 'user.name') { * const email = valueGetter('user.email'); * console.log('Name changed:', value, 'Email is:', email); * } * // Clear error for the changed field * if (formErrors[fieldName]) { * setFormErrors(prev => ({ ...prev, [fieldName]: '' })); * } * }; * <Form errors={formErrors} onChange={handleChange} render={props => <FormElement>form content</FormElement>} /> * ``` */ onChange?: (fieldName: string, value: any, valueGetter: (name: string) => any) => void; /** * Validates the entire form and returns error messages. * * Return a key-value pair where the key is the field path and the value is the error message. * You can validate nested fields like 'users[0].name'. * Only synchronous functions are supported. * * @example * ```jsx * const validator = values => ({ user: { name: values.user.name ? "" : "Name is required." } }); * <Form validator={validator} render={props => <form> form content </form>} /> * ``` */ validator?: FormValidatorType; /** * Handles form submission when validation passes and fields are modified. * * Fires when at least one field is modified, the user clicks Submit, and validation passes. * * @example * ```jsx * const handleSubmit = (values, event) => console.log(values); * <Form onSubmit={handleSubmit} render={props => <form> form content </form>} /> * ``` */ onSubmit?: (values: { [name: string]: any; }, event?: React.SyntheticEvent<any>) => void; /** * Handles every submit button click, even when the form is invalid or unchanged. * * Use this for advanced scenarios where you need to handle all submit events. * * @example * ```jsx * const handleSubmitClick = event => console.log(event); * <Form onSubmitClick={handleSubmitClick} render={props => <form> form content </form>} /> * ``` */ onSubmitClick?: (event: FormSubmitClickEvent) => void; /** * Renders the form content using the provided render function. * * @example * ```jsx * const renderForm = props => <form> form content </form>; * <Form render={renderForm} /> * ``` */ render: (props: FormRenderProps) => any; /** * Allows the form to submit even when no fields have been modified. * * @example * ```jsx * <Form ignoreModified={true} render={props => <form>form content </form>} /> * ``` */ ignoreModified?: boolean; /** * @hidden * This prop comes from the `withId` HOC and is used internally by the Form. * It replaces the previously used guid() function and generates an `id` of the Form. */ id?: string; } /** * Contains props that are passed to the form's render function. */ export declare interface FormRenderProps { /** * Submits the form when called. * Use this with the onClick property of Submit buttons. * * @example * ```jsx * const handleSubmit = event => console.log("Form submitted"); * <Button onClick={props.onSubmit}>Submit</Button> * ``` */ onSubmit: (event: React.SyntheticEvent<any>) => void; /** * A callback for emitting changes to a specific field without using the Field component * ([see example]({% slug common_scenarios_form %}#toc-changing-the-field-value)). * * > Use `onChange` only if you cannot achieve the desired behavior through the Field component. * * @example * ```jsx * props.onChange("user.name", { value: "John Doe" }); * ``` */ onChange: (name: string, options: { value: any; }) => void; /** * Resets the form to its initial state. * * @example * ```jsx * <Button onClick={props.onFormReset}>Reset</Button> * ``` */ onFormReset: () => void; /** * Contains current validation errors organized by field path. * * @example * ```jsx * console.log(props.errors); * ``` */ errors: KeyValue<string>; /** * Shows whether the form passes all validation rules. * Becomes false if any field fails validation. * * @example * ```jsx * console.log(props.valid); * ``` */ valid: boolean; /** * Shows whether the user has interacted with any field. * Becomes true when any field loses focus or the user tries to submit. * * @example * ```jsx * console.log(props.touched); * ``` */ touched: boolean; /** * Shows whether the user has focused on any field. * Becomes true when any field receives focus or the user tries to submit. * * @example * ```jsx * console.log(props.visited); * ``` */ visited: boolean; /** * Shows whether any field value has changed from its initial value. * Becomes true when any field value changes for the first time. * * @example * ```jsx * console.log(props.modified); * ``` */ modified: boolean; /** * Shows whether the form has been successfully submitted. * Use this to detect if the user is leaving before saving changes. * * @example * ```jsx * console.log(props.submitted); * ``` */ submitted: boolean; /** * Shows whether the form can be submitted. * When true and form is valid, you can submit. When true and form is invalid, you can show all validation errors. * * Use this to control the disabled state of Submit buttons. * * @example * ```jsx * console.log(props.allowSubmit); * ``` */ allowSubmit: boolean; /** * A callback for getting the value of a field without using the Field component * ([see example]({% slug common_scenarios_form %}#toc-reading-the-field-state)). * Useful for creating and modifying the UI based on the field values. * * @example * ```jsx * const value = props.valueGetter("user.name"); * console.log(value); * ``` */ valueGetter: (name: string) => any; } /** * Represents the KendoReact FormSeparator component. */ export declare const FormSeparator: React_2.FunctionComponent<FormSeparatorProps>; /** * Represent the `ref` of the FormSeparator component. */ export declare interface FormSeparatorHandle { /** * Represents the props of the FormSeparator component. */ props: FormSeparatorProps; /** * Represents the element of the FormSeparator component. */ element: HTMLSpanElement | null; } /** * Represents the props of the KendoReact FormSeparator component. */ export declare interface FormSeparatorProps { /** * Defines the colspan for the separator element related to the parent Form component columns. Can be a number or an array of responsive breakpoints. */ colSpan?: number | ResponsiveFormBreakPoint[]; /** * @hidden */ children?: any; /** * The styles that are applied to the form DOM element. */ style?: React_2.CSSProperties; /** * Sets a class for the form DOM element. */ className?: string; } /** * Contains data for the form submit click event. */ export declare interface FormSubmitClickEvent { /** * Provides the current values from all form fields. */ values: { [name: string]: any; }; /** * Contains the original browser event that triggered the submit. */ event?: React.SyntheticEvent<any>; /** * Shows whether the form passes all validation rules. */ isValid: boolean; /** * Shows whether any form fields have been changed from their initial values. */ isModified: boolean; } /** * Validates an entire form and returns error messages. * * * values - Contains the current values from all form fields * * valueGetter - Gets field values using field paths like 'user.name' * * Returns a key-value pair where the key is the field path and the value is the error message. */ export declare type FormValidatorType = (values: any, valueGetter: (name: string) => any) => KeyValue<string> | undefined; /** * Represents the [gutters](https://developer.mozilla.org/en-US/docs/Web/CSS/gap) configuration for a form layout. * It allows defining the spacing between the columns and rows of the form. * Each property can be a number or an array of responsive breakpoints. */ export declare interface Gutters { /** * Defines the gutters for the columns in the form. * Can be a number or an array of responsive breakpoints. */ cols?: string | number | ResponsiveFormBreakPoint[]; /** * Defines the gutters for the rows in the form. * Can be a number or an array of responsive breakpoints. */ rows?: string | number | ResponsiveFormBreakPoint[]; } /** * Represents a key-value pair collection where keys are strings. */ export declare interface KeyValue<ValueType> { [name: string]: ValueType; } /** * Defines responsive breakpoints for form layouts. * Each breakpoint sets minimum and maximum widths and values for columns or spacing at different screen sizes. */ export declare interface ResponsiveFormBreakPoint { /** * Sets the minimum screen width in pixels for this breakpoint. */ minWidth?: number; /** * Sets the maximum screen width in pixels for this breakpoint. */ maxWidth?: number; /** * Sets the number of columns or spacing for form controls at this screen size. */ value: number | string; } export { }