Parameters
Properties passed to the useFieldProps hook.
| Type | Description | |
|---|---|---|
value | string | (optional) Source data value for the field. Takes precedence over the path value from DataContext. |
defaultValue | string | (optional) Default value for the field. Does not take precedence over values from DataContext. |
path | string | (optional) JSON Pointer for the field data location in the source dataset (when using Form.Handler or DataContext). |
itemPath | string | (optional) Path relative to the current Iterate element. Used when the field is inside an Iterate context. |
emptyValue | string undefined | (optional) The value used when emptying the field (e.g., undefined instead of empty string). |
required | boolean | (optional) When true, validates that the field is not empty. When false, adds "(optional)" suffix to label. |
disabled | boolean | (optional) Disables the field, preventing value changes while still displaying it. |
readOnly | boolean | (optional) Makes the field read-only. Used as a fallback for disabled when disabled is not explicitly set. |
info | React.ReactNode Array<React.ReactNode> function | (optional) Info message shown below the field. Can be a function receiving the current value. |
warning | React.ReactNode Array<React.ReactNode> function | (optional) Warning message shown below the field. Can be a function receiving the current value. |
error | Error FormError Array<Error | FormError> function | (optional) Error message or Error object to display. Can be a function receiving the current value. |
errorMessages | Record<string, React.ReactNode> | (optional) Custom error messages keyed by error type (e.g., Field.errorRequired). |
schema | object ZodSchema | (optional) JSON Schema or Zod schema for validating the field value. |
validateInitially | boolean | (optional) Show validation errors on initial render before user interaction. |
validateUnchanged | boolean | (optional) Show validation errors when field is touched without value changes. |
validateContinuously | boolean | (optional) Show validation errors continuously while typing, not just on blur. |
onChangeValidator | (value, { errorMessages, connectWithPath, validators }) => Error | undefined | (optional) Custom validation function called on every change. Can be async. Returns Error, FormError, or array of validators. |
onBlurValidator | (value, { errorMessages, connectWithPath, validators }) => Error | undefined | (optional) Custom validation function called on blur. Preferred for validations with side-effects. Can be async. |
exportValidators | Record<string, function> | (optional) Object containing validators to export for use in other validators. |
validateRequired | function | (optional) Custom logic for required validation. Receives { value, emptyValue, required, error }. |
transformIn | (external: Value) => Value | (optional) Transforms the external value before displaying in the field. |
transformOut | (internal: Value) => Value | (optional) Transforms the internal value before storing in form data or returning via onChange. |
toInput | (value: Value) => Value | (optional) Transforms value for input display (after transformIn). |
fromInput | (value: Value) => Value | (optional) Transforms value from input (before transformOut). |
toEvent | (value: Value) => Value | (optional) Transforms value before passing to event handlers. |
fromExternal | (value: Value) => Value | (optional) Transforms external data value when reading from DataContext. |
transformValue | (value: Value) => Value | (optional) Transforms the value during processing. |
provideAdditionalArgs | (value: Value, additionalArgs: ProvideAdditionalEventArgs) => ProvideAdditionalEventArgs | (optional) Provides additional arguments to pass through event handlers. |
onChange | (value: Value, additionalArgs?: ReceiveAdditionalEventArgs) => void | (optional) Callback called when the field value changes. |
onFocus | (value: Value, additionalArgs?: ReceiveAdditionalEventArgs) => void | (optional) Callback called when the field receives focus. |
onBlur | (value: Value, additionalArgs?: ReceiveAdditionalEventArgs) => void | (optional) Callback called when the field loses focus. |
onStatusChange | (status: FieldStatus) => void | (optional) Callback called when the field status changes (e.g., error, pending). |
Return Values
Properties and methods returned from the useFieldProps hook.
| Type | Description | |
|---|---|---|
value | string | (required) The current transformed field value, ready for display. |
isChanged | boolean | (required) Whether the field value has been changed by the user. |
hasError | boolean | (optional) Whether the field currently has a validation error. |
htmlAttributes | AriaAttributes & DataAttributes | (required) HTML attributes including aria-invalid, aria-required, aria-describedby, and data-* attributes. |
handleFocus | () => void | (required) Handler to call when the field receives focus. |
handleBlur | () => void | (required) Handler to call when the field loses focus. Triggers blur validation. |
handleChange | (value: Value, additionalArgs?: object) => void | (required) Handler to call when the field value changes. Accepts the new value and optional additional args. |
handleError | () => void | (required) Handler to manually trigger error display. |
updateValue | (value: Value) => void | (required) Programmatically update the field value without triggering change events. |
setHasFocus | (hasFocus: boolean, overrideValue?: Value, additionalArgs?: ProvideAdditionalEventArgs) => void | (required) Manually set the focus state of the field. |
setChanged | (state: boolean) => void | (required) Manually set the changed state of the field. |
setDisplayValue | (value: React.ReactNode, options?: { path?: string; type?: "field" }) => void | (required) Set a custom display value for the field (used in summary views). |
forceUpdate | () => void | (required) Force a re-render of the field component. |
dataContext | ContextState | (required) The DataContext state object, providing access to form-level data and methods. |
fieldState | SubmitState | (required) Current submit state of the field (pending, error, complete, etc.). |
additionalArgs | ReceiveAdditionalEventArgs | (required) Additional arguments passed through event handlers. |