@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>; /** * Represents the props of the FieldArray component that is used inside the KendoReact Form component. */ export declare interface FieldArrayProps { /** * The name of the field in the Form state. */ name: string; /** * Can be set to a React component. * [`FieldArrayRenderProps`]({% slug api_form_fieldarrayrenderprops %}). */ component: React.ComponentType<any>; /** * The validation functions for the FieldArray level. * Currently, `validator` supports only synchronous functions. */ validator?: FieldValidatorType | FieldValidatorType[]; /** * The React elements that are passed as children to the rendered component. */ children?: any; /** * @hidden */ [customProp: string]: any; } /** * Represents the props that are passed to the component which is rendered by FieldArray. */ export declare interface FieldArrayRenderProps { /** * Represents the current value of the FieldArray * ([see example]({% slug custom_components_form %}#toc-using-basic-properties)). */ value: any; /** * Represents the error message that is returned by the validator. * The FieldArray is considered valid if the `validationMessage` field is empty. */ validationMessage: string | null; /** * Indicates if the field is touched. * The touched state is set to `true` when the `onBlur` callback is called. */ touched: boolean; /** * Indicates if the field is modified. * The modified state is set to `true` when the `onChange` callback for the current field is called for first time. */ modified: boolean; /** * Indicates if the field is visited. * The visited state is set to `true` when the `onFocus` callback is called. */ visited: boolean; /** * A calculated property based on whether `validationMessage` is present and the `touched` state is set to `true`. */ valid: boolean; /** * Represents the children that are passed to the FieldArray. */ children: any; /** * The name of the field in the Form state. */ name: string; /** * A callback to add a value to the beginning of the array. */ onUnshift: (options: { value: any; }) => number; /** * A callback to add a value to the end of the array. */ onPush: (options: { value: any; }) => void; /** * A callback to insert value at given index of the array. */ onInsert: (options: { value: any; index: number; }) => void; /** * A callback to remove a value from the end of the array. The value is returned. */ onPop: () => any; /** * A callback to remove a value from given index of the array. */ onRemove: (options: { index: number; }) => any; /** * A callback to replace value at given index of the array. */ onReplace: (options: { value: any; index: number; }) => void; /** * A callback to move a value from one index to another. Useful for drag and drop reordering. */ onMove: (options: { prevIndex: number; nextIndex: number; }) => void; /** * @hidden */ [customProp: string]: any; } /** * Represents the props of the Field component that is used inside the KendoReact Form component. */ export declare interface FieldProps { /** * The name of the field in the Form state. * Supports nested fields in the `user.age` and `users[index].name` formats. * * @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>; /** * The validation functions for the Field level. * Currently, `validator` supports only synchronous functions. * Using the array overload with an inline array will cause an infinite loop. Use a `useMemo` hook to memoize the array instead. * * @example * ```jsx * const validator = value => value ? "" : "This field is required."; * <Field name="user.email" component="input" validator={validator} /> * ``` */ validator?: FieldValidatorType | FieldValidatorType[]; /** * The React elements that are passed as children to the rendered component. * * @example * ```jsx * <Field name="user.name" component="input"> * <span>Additional content</span> * </Field> * ``` */ children?: any; /** * Called when the underlying editor triggers its `onChange` event and the Form updates its internal state. * Useful for updating related fields. * > The `Form` listens to this editor event and automatically keeps its internal state up to date. * That is why this event should be used only for executing custom logic. * * @example * ```jsx * const handleChange = event => console.log(event); * <Field name="user.name" component="input" onChange={handleChange} /> * ``` */ onChange?: (event: any) => void; } /** * Represents the props that are passed to the component which is rendered by Field. */ export declare interface FieldRenderProps extends FieldRenderPropsBase { } /** * The validator function for the Field component. The function arguments are: * * * value - The current value of the field. * * valueGetter - Function which can be used to get other fields value. * Usable when validator depends on more than one field. Supports field paths. * * fieldProps - Props of the Field component. Currently contains only the `name` prop. * Usable when one validator is used across multiple fields. * * Returns `string` to signify error or `undefined` to signify validation success. */ 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 of the FieldWrapper DOM element. */ className?: string; /** * Specifies the direction of the content. */ dir?: string; /** * @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 * className="k-button" * disabled={!formRenderProps.allowSubmit} * onClick={formRenderProps.onSubmit} * > * Submit * </button> * </div> * )} * /> * ); * }; * * ReactDOM.render(<App />, document.querySelector('my-app')); * ``` */ 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; /** * @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 { props: FormElementProps; 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 of the form DOM element. */ className?: string; /** * If set to `true` enable the horizontal layout of the form editors. */ horizontal?: boolean; /** * @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; } /** * Represent the `ref` of the Form component. */ export declare interface FormHandle extends Pick<FormClassComponent, keyof FormClassComponent> { } /** * Represents the props of the KendoReact Form component. */ export declare interface FormProps { /** * The initial field values of the Form. * * When you initialize the Form fields, set initial values to them. Otherwise, some * components might throw errors related to 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; }; /** * The validation function for the Form level. * Should return a key-value pair where the key is the field path and the value is the error message. * Nested fields are supported, e.g.: 'users[0].name'. * You can use the same field path to access the value from the * values object using the `getter` function from the `kendo-react-common` package. * Currently, `validator` supports only synchronous functions. * * @example * ```jsx * const validator = values => ({ user: { name: values.user.name ? "" : "Name is required." } }); * <Form validator={validator} render={props => <form> form content </form>} /> * ``` */ validator?: FormValidatorType; /** * The submission handler for the Form. * Called when at least one field has been modified, the user pressed the **Submit** button, and the form validation was successful. * * @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; /** * Called every time the user presses the **Submit** button. * Useful in advanced scenarios when you need to handle every submit event, even when the form is invalid or in an unmodified state. * * @example * ```jsx * const handleSubmitClick = event => console.log(event); * <Form onSubmitClick={handleSubmitClick} render={props => <form> form content </form>} /> * ``` */ onSubmitClick?: (event: FormSubmitClickEvent) => void; /** * The Form content that will be rendered. * * @example * ```jsx * const renderForm = props => <form> form content </form>; * <Form render={renderForm} /> * ``` */ render: (props: FormRenderProps) => any; /** * Set this to `true` to allow the form to submit without modified fields. * * @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; } /** * Represents the props that are passed to the `render` option component of the Form. */ export declare interface FormRenderProps { /** * A callback for submitting the Form. * Can be passed to the `onClick` property of the **Submit** button. * * @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; /** * A callback for resetting the Form. * * @example * ```jsx * <button onClick={props.onFormReset}>Reset</button> * ``` */ onFormReset: () => void; /** * The key-value pair containing the current errors by field path, combined from both field and form level validators. * * @example * ```jsx * console.log(props.errors); * ``` */ errors: KeyValue<string>; /** * Indicates if the Form is valid. * If any field is invalid, `valid` is set to `false`. * * @example * ```jsx * console.log(props.valid); * ``` */ valid: boolean; /** * Indicates if the Form is touched. * If any field is touched, `touched` is set to `true`. * The touched state of a field is set to `true` when the `onBlur` * callback of the Field component is called or when the user tries to submit the form. * * @example * ```jsx * console.log(props.touched); * ``` */ touched: boolean; /** * Indicates if the Form is visited. * If any field is visited, `visited` is set to `true`. * The visited state of a field is set to `true` when the `onFocus` * callback of the Field component is called or when the user tries to submit the form. * * @example * ```jsx * console.log(props.visited); * ``` */ visited: boolean; /** * Indicates if the Form is modified. * If any field is modified, `modified` is set to `true`. * The modified state of a field is set to `true` when the `onChange` * callback of the Field component is called for the first time. * * @example * ```jsx * console.log(props.modified); * ``` */ modified: boolean; /** * Indicates if the Form is successfully submitted. * Useful for detecting if the user is leaving the form before saving changes. * * @example * ```jsx * console.log(props.submitted); * ``` */ submitted: boolean; /** * Indicates if the Form is ready to be submitted. * * If `allowSubmit` is set to `true` and the Form is valid, the user will be able to submit the form. * * If `allowSubmit` is set to `true` and the Form is not valid, the user will be able to set the `touched` and `visited` state of all fields to `true`. * * Useful for toggling the disabled state of the **Submit** button. * * @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; } /** * The FormSubmitClick event. */ export declare interface FormSubmitClickEvent { /** * Contains the current values of the form. */ values: { [name: string]: any; }; /** * The native event. */ event?: React.SyntheticEvent<any>; /** * Represents the validity state of the form. */ isValid: boolean; /** * Represents the modified state of the form. */ isModified: boolean; } /** * The validator function for the Form component. * * * values - The current values of the form. * * valueGetter - Function which can be used to get field value. Supports field paths. * * Returns key-value pair with errors if such are present. The key is the field path, where the value is the error message. */ export declare type FormValidatorType = (values: any, valueGetter: (name: string) => any) => KeyValue<string> | undefined; /** * */ export declare interface KeyValue<ValueType> { [name: string]: ValueType; } export { }