@rachelallyson/hero-hook-form 2.11.0 → 2.13.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.13.0] - 2026-01-29
+
+### Added
+
+- **ConfigProvider: autocomplete defaults** – `HeroHookFormDefaultsConfig` and `useHeroHookFormDefaults()` now support `defaults.autocomplete`. AutocompleteField spreads these defaults so global Autocomplete styling (color, size, variant, radius, labelPlacement) applies like Input, Textarea, and Select.
+- **FieldArrayField: readOnly** – New `readOnly?: boolean` on `FieldArrayConfig`. When true, hides the add button, remove buttons, and reorder buttons so the field array is display-only.
+- **StringArrayField: readOnly** – New `readOnly?: boolean` on `StringArrayFieldConfig`. When true, hides the input, add button, and remove buttons so the list is display-only.
+- **AutocompleteFieldHandlers: store custom value from selection** – `createAutocompleteFieldHandlers` now allows `onSelectionChange` to return a value (string or number); that value is stored in the form field instead of the selected key (e.g. "store key, show label" by returning the display string).
+
+### Changed
+
+- **AutocompleteField** – `AutocompleteItem` `textValue` now uses `item.label ?? String(item.value)` so options with labels display correctly.
+- **StringArrayField** – Uses `useHeroHookFormDefaults()` for Input and Button; switched to HeroUI-style props (`onValueChange`, `onPress`, `isDisabled`). Enter key handling uses `onKeyDown` instead of deprecated `onKeyPress`.
+
+## [2.12.0] - 2026-01-28
+
+### Added
+
+- **Custom option layout for autocomplete (renderItem)** – `FormFieldHelpers.autocomplete()` and the builder chain accept an optional 6th param `options?: { renderItem?: (item) => ReactNode }` so each option can show custom content (e.g. name + email + phone). Config supports `renderItem`; `FormField`, `ServerActionForm`, and `AdvancedFormBuilder` pass it through; `AutocompleteField` wraps custom children in `AutocompleteItem` so HeroUI receives valid listbox items. Use with static options or with `getOptions` for dynamic items + custom layout.
+- **StringFieldConfig.renderItem** – Optional `renderItem?: (item: { label: string; value: string | number }) => ReactNode` for autocomplete fields.
+- **Component tests** – Autocomplete: `renderItem` config and render (static and getOptions + renderItem).
+
+### Fixed
+
+- **AutocompleteField custom children** – Custom `children` (renderItem) are now wrapped in `AutocompleteItem` before passing to HeroUI Autocomplete so the listbox receives valid items and the form renders correctly.
+
 ## [2.11.0] - 2026-01-28
 
 ### Added

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import React$1, { ComponentProps } from 'react';
+import React$1, { ComponentProps, ReactNode } from 'react';
 import { Button } from '@heroui/react';
 import * as react_hook_form from 'react-hook-form';
 import { FieldValues, Path, RegisterOptions, ArrayPath, Control, UseFormReturn, FieldErrors, UseFormProps, SubmitHandler, DefaultValues, UseFormSetError, FieldPath, FieldArrayWithId } from 'react-hook-form';
@@ -90,6 +90,11 @@ interface StringFieldConfig<TFieldValues extends FieldValues> extends BaseFormFi
         label: string;
         value: string | number;
     }[];
+    /** Custom render for each autocomplete option (e.g. name + email + phone). When provided, used instead of default label-only. */
+    renderItem?: (item: {
+        label: string;
+        value: string | number;
+    }) => ReactNode;
 }
 interface BooleanFieldConfig<TFieldValues extends FieldValues> extends BaseFormFieldConfig<TFieldValues> {
     type: "checkbox" | "switch";
@@ -165,6 +170,8 @@ interface StringArrayFieldConfig<TFieldValues extends FieldValues> extends BaseF
         addButtonText?: string;
         /** Whether to show add button or use enter key */
         showAddButton?: boolean;
+        /** When true, only display items: no input, no add button, no remove buttons */
+        readOnly?: boolean;
     };
 }
 interface CustomFieldConfig<TFieldValues extends FieldValues> extends Omit<BaseFormFieldConfig<TFieldValues>, "name"> {
@@ -217,6 +224,8 @@ interface FieldArrayConfig<TFieldValues extends FieldValues> extends Omit<BaseFo
     };
     /** Function to create default item when adding new array item */
     defaultItem?: () => any;
+    /** When true, hide add button, remove buttons, and reorder buttons (display-only) */
+    readOnly?: boolean;
     /** Whether this field array should always be registered (for conditional rendering) */
     alwaysRegistered?: boolean;
     /** Custom render function for array items */
@@ -1761,7 +1770,7 @@ declare function useFormHelper<T extends FieldValues>({ defaultValues, methods,
  * @category Hooks
  */
 declare function useHeroForm<TFieldValues extends FieldValues>(): {
-    defaults: Required<Pick<HeroHookFormDefaultsConfig, "input" | "select" | "textarea" | "switch" | "radioGroup" | "checkbox" | "slider" | "dateInput" | "submitButton">>;
+    defaults: Required<Pick<HeroHookFormDefaultsConfig, "input" | "select" | "textarea" | "switch" | "radioGroup" | "checkbox" | "slider" | "autocomplete" | "dateInput" | "submitButton">>;
     watch: react_hook_form.UseFormWatch<TFieldValues>;
     getValues: react_hook_form.UseFormGetValues<TFieldValues>;
     getFieldState: react_hook_form.UseFormGetFieldState<TFieldValues>;
@@ -1800,6 +1809,8 @@ type TextareaDefaults = Partial<Omit<TextareaProps, "value" | "onValueChange" |
 type CheckboxDefaults = Partial<Omit<React$1.ComponentProps<typeof Checkbox>, "isSelected" | "onValueChange" | "isInvalid" | "errorMessage" | "isDisabled">>;
 type RadioGroupDefaults = Partial<Omit<React$1.ComponentProps<typeof RadioGroup>, "value" | "onValueChange" | "label">>;
 type SelectDefaults = Partial<Omit<SelectProps, "selectedKeys" | "onSelectionChange" | "label" | "isInvalid" | "errorMessage" | "isDisabled">>;
+type AutocompleteProps = React$1.ComponentProps<typeof Autocomplete>;
+type AutocompleteDefaults = Partial<Omit<AutocompleteProps, "selectedKey" | "inputValue" | "label" | "isInvalid" | "errorMessage" | "isDisabled" | "items" | "defaultItems" | "children">>;
 type DateInputProps = React$1.ComponentProps<typeof DateInput>;
 type DateInputDefaults = Partial<Omit<DateInputProps, "value" | "onChange" | "label" | "isInvalid" | "errorMessage" | "isDisabled">>;
 type SliderDefaults = Partial<Omit<React$1.ComponentProps<typeof Slider>, "value" | "onValueChange" | "label" | "isInvalid" | "errorMessage" | "isDisabled">>;
@@ -1807,6 +1818,7 @@ type SwitchDefaults = Partial<Omit<React$1.ComponentProps<typeof Switch>, "isSel
 type ButtonDefaults = Partial<Omit<React$1.ComponentProps<typeof Button$1>, "type" | "isLoading">>;
 interface HeroHookFormDefaultsConfig {
     common?: CommonFieldDefaults;
+    autocomplete?: AutocompleteDefaults;
     input?: InputDefaults;
     textarea?: TextareaDefaults;
     checkbox?: CheckboxDefaults;
@@ -1822,7 +1834,7 @@ interface HeroHookFormProviderProps {
     defaults?: HeroHookFormDefaultsConfig;
 }
 declare function HeroHookFormProvider(props: HeroHookFormProviderProps): React$1.JSX.Element;
-declare function useHeroHookFormDefaults(): Required<Pick<HeroHookFormDefaultsConfig, "input" | "textarea" | "checkbox" | "radioGroup" | "select" | "dateInput" | "slider" | "switch" | "submitButton">>;
+declare function useHeroHookFormDefaults(): Required<Pick<HeroHookFormDefaultsConfig, "input" | "textarea" | "checkbox" | "radioGroup" | "select" | "autocomplete" | "dateInput" | "slider" | "switch" | "submitButton">>;
 
 interface FormProps<TFieldValues extends FieldValues> {
     methods: UseFormReturn<TFieldValues>;
@@ -2433,6 +2445,7 @@ declare class BasicFormBuilder<T extends FieldValues> {
     }[]): this;
     /**
      * Add an autocomplete field (static options array or dynamic getOptions getter).
+     * Optional options.renderItem for custom option layout (e.g. name + email + phone).
      */
     autocomplete(name: Path<T>, label: string, items: {
         label: string;
@@ -2440,7 +2453,12 @@ declare class BasicFormBuilder<T extends FieldValues> {
     }[] | (() => {
         label: string;
         value: string | number;
-    }[]), placeholder?: string): this;
+    }[]), placeholder?: string, options?: {
+        renderItem?: (item: {
+            label: string;
+            value: string | number;
+        }) => React$1.ReactNode;
+    }): this;
     /**
      * Add a checkbox field
      */
@@ -2557,6 +2575,11 @@ declare const FormFieldHelpers: {
      * FormFieldHelpers.autocomplete("personId", "Person", () => people.map(p => ({ label: p.name, value: p.id })), "Search people", {
      *   onInputChange: (q) => fetchPeople(q).then(setPeople),
      * })
+     *
+     * // Custom option layout (e.g. name + email + phone per option)
+     * FormFieldHelpers.autocomplete("personId", "Person", getOptions, "Search", undefined, {
+     *   renderItem: (item) => <div><strong>{item.label}</strong><br /><small>{getSubtitle(item.value)}</small></div>,
+     * })
      * ```
      */
     autocomplete: <T extends FieldValues>(name: Path<T>, label: string, items: {
@@ -2565,7 +2588,13 @@ declare const FormFieldHelpers: {
     }[] | (() => {
         label: string;
         value: string | number;
-    }[]), placeholder?: string, autocompleteProps?: AutocompletePassthroughProps) => ZodFormFieldConfig<T>;
+    }[]), placeholder?: string, autocompleteProps?: AutocompletePassthroughProps, options?: {
+        /** Custom render for each option (e.g. name + email + phone). When provided, used instead of default label-only. */
+        renderItem?: (item: {
+            label: string;
+            value: string | number;
+        }) => React$1.ReactNode;
+    }) => ZodFormFieldConfig<T>;
     /**
      * Create a checkbox field
      *
@@ -3012,6 +3041,10 @@ type FieldCreationParams<T extends FieldValues> = {
         value: string | number;
     }[];
     props?: Record<string, unknown>;
+    renderItem?: (item: {
+        label: string;
+        value: string | number;
+    }) => React$1.ReactNode;
 } | {
     type: "checkbox";
     name: Path<T>;
@@ -4346,4 +4379,4 @@ declare const validationUtils: {
     }>;
 };
 
-export { AdvancedFieldBuilder, type ArraySyncOptions, type ArraySyncResult, AutocompleteField, type AutocompleteFieldProps, type AutocompleteOption, type AutocompletePassthroughProps, type BaseFormFieldConfig, BasicFormBuilder, type BooleanFieldConfig, type ButtonDefaults, type CheckboxDefaults, CheckboxField, type CheckboxFieldProps, CheckboxGroupField, type CheckboxGroupFieldConfig, type CheckboxGroupFieldProps, type CheckboxGroupPassthroughProps, type CheckboxPassthroughProps, type CommonFieldDefaults, CommonFields, ConditionalField, type ConditionalFieldConfig, type ConditionalFieldProps, type ConditionalValidation, ConfigurableForm, ContentField, type ContentFieldConfig, type CreateFieldArrayCustomConfigOptions, type CustomFieldConfig, DateField, type DateFieldConfig, type DateFieldProps, type DateInputDefaults, type DateInputPassthroughProps, type DynamicSectionConfig, DynamicSectionField, type DynamicSectionFieldProps, type EnhancedFormState, FieldArrayBuilder, type FieldArrayConfig, FieldArrayField, type FieldArrayFieldProps, FieldArrayItemBuilder, type FieldBaseProps, type FieldCreationParams, type FieldGroup, FileField, type FileFieldConfig, type FileFieldProps, type FileInputPassthroughProps, FontPickerField, type FontPickerFieldConfig, type FontPickerFieldProps, type FormConfig, FormField, type FormFieldConfig, FormFieldHelpers, type FormFieldType, type FormProps, FormProvider, FormStatus, type FormStatusProps, type FormStep, type FormSubmissionState, type FormTestUtils, FormToast, type FormToastProps, type FormValidationError, type HeroHookFormDefaultsConfig, HeroHookFormProvider, type HeroHookFormProviderProps, type InputDefaults, InputField, type InputFieldProps, type InputPassthroughProps, type RadioFieldConfig, type RadioGroupDefaults, RadioGroupField, type RadioGroupFieldProps, type RadioGroupPassthroughProps, type SelectDefaults, SelectField, type SelectFieldProps, type SelectPassthroughProps, ServerActionForm, type ServerFieldError, type ServerFormError, SimpleForm, type SimpleFormProps, type SliderDefaults, SliderField, type SliderFieldConfig, type SliderFieldProps, type SliderPassthroughProps, type StringArrayFieldConfig, type StringFieldConfig, SubmitButton, type SubmitButtonProps, type SwitchDefaults, SwitchField, type SwitchFieldProps, type SwitchPassthroughProps, type TextareaDefaults, TextareaField, type TextareaFieldProps, type TextareaPassthroughProps, TypeInferredBuilder, type UseDebouncedValidationOptions, type UseEnhancedFormStateOptions, type UseInferredFormOptions, type ValidationUtils, type WithControl, type WizardFormConfig, ZodForm, type ZodFormConfig, type ZodFormFieldConfig, applyServerErrors, asyncValidation, commonValidations, createAdvancedBuilder, createBasicFormBuilder, createDateSchema, createEmailSchema, createField, createFieldArrayBuilder, createFieldArrayCustomConfig, createFieldArrayItemBuilder, createFileSchema, createFormTestUtils, createFutureDateSchema, createMaxLengthSchema, createMinLengthSchema, createMockFormData, createMockFormErrors, createNestedPathBuilder, createNumberRangeSchema, createOptimizedFieldHandler, createPasswordSchema, createPastDateSchema, createPhoneSchema, createRequiredCheckboxSchema, createRequiredSchema, createTypeInferredBuilder, createUrlSchema, createZodFormConfig, crossFieldValidation, debounce, deepEqual, defineInferredForm, errorMessages, field, getFieldError, getFormErrors, hasFieldError, hasFormErrors, memorySafeFieldArray, pathToString, serverValidation, shallowEqual, simulateFieldInput, simulateFormSubmission, suggestGarbageCollection, syncArrays, throttle, useDebouncedFieldValidation, useDebouncedValidation, useEnhancedFormState, useFieldArrayMemoryCleanup, useFormHelper, useHeroForm, useHeroHookFormDefaults, useInferredForm, useLazyFieldArrayRegistration, useLazyFieldRegistration, useMemoizedCallback, useMemoizedFieldProps, usePerformanceMonitor, useTypeInferredForm, useZodForm, validationPatterns, validationUtils, waitForFormState };
+export { AdvancedFieldBuilder, type ArraySyncOptions, type ArraySyncResult, type AutocompleteDefaults, AutocompleteField, type AutocompleteFieldProps, type AutocompleteOption, type AutocompletePassthroughProps, type BaseFormFieldConfig, BasicFormBuilder, type BooleanFieldConfig, type ButtonDefaults, type CheckboxDefaults, CheckboxField, type CheckboxFieldProps, CheckboxGroupField, type CheckboxGroupFieldConfig, type CheckboxGroupFieldProps, type CheckboxGroupPassthroughProps, type CheckboxPassthroughProps, type CommonFieldDefaults, CommonFields, ConditionalField, type ConditionalFieldConfig, type ConditionalFieldProps, type ConditionalValidation, ConfigurableForm, ContentField, type ContentFieldConfig, type CreateFieldArrayCustomConfigOptions, type CustomFieldConfig, DateField, type DateFieldConfig, type DateFieldProps, type DateInputDefaults, type DateInputPassthroughProps, type DynamicSectionConfig, DynamicSectionField, type DynamicSectionFieldProps, type EnhancedFormState, FieldArrayBuilder, type FieldArrayConfig, FieldArrayField, type FieldArrayFieldProps, FieldArrayItemBuilder, type FieldBaseProps, type FieldCreationParams, type FieldGroup, FileField, type FileFieldConfig, type FileFieldProps, type FileInputPassthroughProps, FontPickerField, type FontPickerFieldConfig, type FontPickerFieldProps, type FormConfig, FormField, type FormFieldConfig, FormFieldHelpers, type FormFieldType, type FormProps, FormProvider, FormStatus, type FormStatusProps, type FormStep, type FormSubmissionState, type FormTestUtils, FormToast, type FormToastProps, type FormValidationError, type HeroHookFormDefaultsConfig, HeroHookFormProvider, type HeroHookFormProviderProps, type InputDefaults, InputField, type InputFieldProps, type InputPassthroughProps, type RadioFieldConfig, type RadioGroupDefaults, RadioGroupField, type RadioGroupFieldProps, type RadioGroupPassthroughProps, type SelectDefaults, SelectField, type SelectFieldProps, type SelectPassthroughProps, ServerActionForm, type ServerFieldError, type ServerFormError, SimpleForm, type SimpleFormProps, type SliderDefaults, SliderField, type SliderFieldConfig, type SliderFieldProps, type SliderPassthroughProps, type StringArrayFieldConfig, type StringFieldConfig, SubmitButton, type SubmitButtonProps, type SwitchDefaults, SwitchField, type SwitchFieldProps, type SwitchPassthroughProps, type TextareaDefaults, TextareaField, type TextareaFieldProps, type TextareaPassthroughProps, TypeInferredBuilder, type UseDebouncedValidationOptions, type UseEnhancedFormStateOptions, type UseInferredFormOptions, type ValidationUtils, type WithControl, type WizardFormConfig, ZodForm, type ZodFormConfig, type ZodFormFieldConfig, applyServerErrors, asyncValidation, commonValidations, createAdvancedBuilder, createBasicFormBuilder, createDateSchema, createEmailSchema, createField, createFieldArrayBuilder, createFieldArrayCustomConfig, createFieldArrayItemBuilder, createFileSchema, createFormTestUtils, createFutureDateSchema, createMaxLengthSchema, createMinLengthSchema, createMockFormData, createMockFormErrors, createNestedPathBuilder, createNumberRangeSchema, createOptimizedFieldHandler, createPasswordSchema, createPastDateSchema, createPhoneSchema, createRequiredCheckboxSchema, createRequiredSchema, createTypeInferredBuilder, createUrlSchema, createZodFormConfig, crossFieldValidation, debounce, deepEqual, defineInferredForm, errorMessages, field, getFieldError, getFormErrors, hasFieldError, hasFormErrors, memorySafeFieldArray, pathToString, serverValidation, shallowEqual, simulateFieldInput, simulateFormSubmission, suggestGarbageCollection, syncArrays, throttle, useDebouncedFieldValidation, useDebouncedValidation, useEnhancedFormState, useFieldArrayMemoryCleanup, useFormHelper, useHeroForm, useHeroHookFormDefaults, useInferredForm, useLazyFieldArrayRegistration, useLazyFieldRegistration, useMemoizedCallback, useMemoizedFieldProps, usePerformanceMonitor, useTypeInferredForm, useZodForm, validationPatterns, validationUtils, waitForFormState };

package/dist/index.js

@@ -88,9 +88,170 @@ import React19 from "react";
 import { get, useWatch as useWatch3 } from "react-hook-form";
 
 // src/fields/AutocompleteField.tsx
-import React from "react";
+import React2 from "react";
 import { Controller } from "react-hook-form";
 
+// src/providers/ConfigProvider.tsx
+import React, { createContext, useContext, useMemo } from "react";
+var DefaultsContext = createContext(null);
+function HeroHookFormProvider(props) {
+  const value = useMemo(() => props.defaults ?? {}, [props.defaults]);
+  return /* @__PURE__ */ React.createElement(DefaultsContext.Provider, { value }, props.children);
+}
+function extractInputCommon(common) {
+  const result = {};
+  if (common.color !== void 0) {
+    const color = common.color;
+    result.color = color;
+  }
+  if (common.size !== void 0) {
+    const size = common.size;
+    result.size = size;
+  }
+  if (common.variant !== void 0) {
+    const variant = common.variant;
+    result.variant = variant;
+  }
+  if (common.radius !== void 0) {
+    const radius = common.radius;
+    result.radius = radius;
+  }
+  if (common.labelPlacement !== void 0) {
+    const labelPlacement = common.labelPlacement;
+    result.labelPlacement = labelPlacement;
+  }
+  return result;
+}
+function extractTextareaCommon(common) {
+  const result = {};
+  if (common.color !== void 0) {
+    const color = common.color;
+    result.color = color;
+  }
+  if (common.size !== void 0) {
+    const size = common.size;
+    result.size = size;
+  }
+  if (common.variant !== void 0) {
+    const variant = common.variant;
+    result.variant = variant;
+  }
+  if (common.radius !== void 0) {
+    const radius = common.radius;
+    result.radius = radius;
+  }
+  if (common.labelPlacement !== void 0) {
+    const labelPlacement = common.labelPlacement;
+    result.labelPlacement = labelPlacement;
+  }
+  return result;
+}
+function extractSelectCommon(common) {
+  const result = {};
+  if (common.color !== void 0) {
+    const color = common.color;
+    result.color = color;
+  }
+  if (common.size !== void 0) {
+    const size = common.size;
+    result.size = size;
+  }
+  if (common.variant !== void 0) {
+    const variant = common.variant;
+    result.variant = variant;
+  }
+  if (common.radius !== void 0) {
+    const radius = common.radius;
+    result.radius = radius;
+  }
+  if (common.labelPlacement !== void 0) {
+    const labelPlacement = common.labelPlacement;
+    result.labelPlacement = labelPlacement;
+  }
+  return result;
+}
+function extractAutocompleteCommon(common) {
+  const result = {};
+  if (common.color !== void 0) {
+    const color = common.color;
+    result.color = color;
+  }
+  if (common.size !== void 0) {
+    const size = common.size;
+    result.size = size;
+  }
+  if (common.variant !== void 0) {
+    const variant = common.variant;
+    result.variant = variant;
+  }
+  if (common.radius !== void 0) {
+    const radius = common.radius;
+    result.radius = radius;
+  }
+  if (common.labelPlacement !== void 0) {
+    const labelPlacement = common.labelPlacement;
+    result.labelPlacement = labelPlacement;
+  }
+  return result;
+}
+function extractDateInputCommon(common) {
+  const result = {};
+  if (common.color !== void 0) {
+    const color = common.color;
+    result.color = color;
+  }
+  if (common.size !== void 0) {
+    const size = common.size;
+    result.size = size;
+  }
+  if (common.variant !== void 0) {
+    const variant = common.variant;
+    result.variant = variant;
+  }
+  if (common.radius !== void 0) {
+    const radius = common.radius;
+    result.radius = radius;
+  }
+  if (common.labelPlacement !== void 0) {
+    const labelPlacement = common.labelPlacement;
+    result.labelPlacement = labelPlacement;
+  }
+  return result;
+}
+function useHeroHookFormDefaults() {
+  const cfg = useContext(DefaultsContext) ?? {};
+  const common = cfg.common ?? {};
+  const commonInput = extractInputCommon(common);
+  const commonTextarea = extractTextareaCommon(common);
+  const commonSelect = extractSelectCommon(common);
+  const commonAutocomplete = extractAutocompleteCommon(common);
+  const commonDateInput = extractDateInputCommon(common);
+  const dateInputBase = {
+    radius: "md",
+    size: "md",
+    variant: "bordered"
+  };
+  return {
+    autocomplete: {
+      ...commonAutocomplete,
+      ...cfg.autocomplete ?? {}
+    },
+    checkbox: cfg.checkbox ?? {},
+    dateInput: {
+      ...dateInputBase,
+      ...commonDateInput,
+      ...cfg.dateInput ?? {}
+    },
+    input: { ...commonInput, ...cfg.input ?? {} },
+    radioGroup: cfg.radioGroup ?? {},
+    select: { ...commonSelect, ...cfg.select ?? {} },
+    slider: cfg.slider ?? {},
+    submitButton: cfg.submitButton ?? {},
+    switch: cfg.switch ?? {},
+    textarea: { ...commonTextarea, ...cfg.textarea ?? {} }
+  };
+}
+
 // src/utils/fieldHandlers.ts
 function createBlurHandler(userHandler, formHandler) {
   return (e) => {
@@ -235,10 +396,12 @@ function createAutocompleteFieldHandlers(props, field2, fieldLevel, options) {
   const allowsCustomValue = options?.allowsCustomValue ?? false;
   const handleSelectionChange = (key) => {
     const next = key ?? "";
-    if (props?.onSelectionChange) {
-      props.onSelectionChange(key);
+    const valueToStore = typeof props?.onSelectionChange === "function" ? props.onSelectionChange(key) : void 0;
+    if (valueToStore !== void 0) {
+      field2.onChange(valueToStore);
+    } else {
+      field2.onChange(next);
     }
-    field2.onChange(next);
   };
   const handleInputChange = (value) => {
     const strValue = value != null ? String(value) : "";
@@ -305,7 +468,8 @@ function AutocompleteField(props) {
     placeholder,
     rules
   } = props;
-  return /* @__PURE__ */ React.createElement(
+  const defaults = useHeroHookFormDefaults();
+  return /* @__PURE__ */ React2.createElement(
     Controller,
     {
       control,
@@ -322,9 +486,10 @@ function AutocompleteField(props) {
           { isDisabled, label },
           { allowsCustomValue }
         );
-        return /* @__PURE__ */ React.createElement("div", { className }, /* @__PURE__ */ React.createElement(
+        return /* @__PURE__ */ React2.createElement("div", { className }, /* @__PURE__ */ React2.createElement(
           Autocomplete,
           {
+            ...defaults.autocomplete,
             ...rest,
             ...defaultItems && {
               defaultItems
@@ -338,11 +503,20 @@ function AutocompleteField(props) {
             inputValue: shouldShowInputValue ? field2.value ?? "" : void 0,
             items
           },
-          children ? children : (item) => /* @__PURE__ */ React.createElement(
+          children ? (item) => /* @__PURE__ */ React2.createElement(
+            AutocompleteItem,
+            {
+              key: String(item.value),
+              textValue: item.label ?? String(item.value),
+              description: item.description,
+              isDisabled: item.disabled
+            },
+            children(item)
+          ) : (item) => /* @__PURE__ */ React2.createElement(
             AutocompleteItem,
             {
               key: String(item.value),
-              textValue: String(item.value),
+              textValue: item.label ?? String(item.value),
               description: item.description,
               isDisabled: item.disabled
             },
@@ -358,140 +532,6 @@ function AutocompleteField(props) {
 // src/fields/CheckboxField.tsx
 import React3 from "react";
 import { Controller as Controller2 } from "react-hook-form";
-
-// src/providers/ConfigProvider.tsx
-import React2, { createContext, useContext, useMemo } from "react";
-var DefaultsContext = createContext(null);
-function HeroHookFormProvider(props) {
-  const value = useMemo(() => props.defaults ?? {}, [props.defaults]);
-  return /* @__PURE__ */ React2.createElement(DefaultsContext.Provider, { value }, props.children);
-}
-function extractInputCommon(common) {
-  const result = {};
-  if (common.color !== void 0) {
-    const color = common.color;
-    result.color = color;
-  }
-  if (common.size !== void 0) {
-    const size = common.size;
-    result.size = size;
-  }
-  if (common.variant !== void 0) {
-    const variant = common.variant;
-    result.variant = variant;
-  }
-  if (common.radius !== void 0) {
-    const radius = common.radius;
-    result.radius = radius;
-  }
-  if (common.labelPlacement !== void 0) {
-    const labelPlacement = common.labelPlacement;
-    result.labelPlacement = labelPlacement;
-  }
-  return result;
-}
-function extractTextareaCommon(common) {
-  const result = {};
-  if (common.color !== void 0) {
-    const color = common.color;
-    result.color = color;
-  }
-  if (common.size !== void 0) {
-    const size = common.size;
-    result.size = size;
-  }
-  if (common.variant !== void 0) {
-    const variant = common.variant;
-    result.variant = variant;
-  }
-  if (common.radius !== void 0) {
-    const radius = common.radius;
-    result.radius = radius;
-  }
-  if (common.labelPlacement !== void 0) {
-    const labelPlacement = common.labelPlacement;
-    result.labelPlacement = labelPlacement;
-  }
-  return result;
-}
-function extractSelectCommon(common) {
-  const result = {};
-  if (common.color !== void 0) {
-    const color = common.color;
-    result.color = color;
-  }
-  if (common.size !== void 0) {
-    const size = common.size;
-    result.size = size;
-  }
-  if (common.variant !== void 0) {
-    const variant = common.variant;
-    result.variant = variant;
-  }
-  if (common.radius !== void 0) {
-    const radius = common.radius;
-    result.radius = radius;
-  }
-  if (common.labelPlacement !== void 0) {
-    const labelPlacement = common.labelPlacement;
-    result.labelPlacement = labelPlacement;
-  }
-  return result;
-}
-function extractDateInputCommon(common) {
-  const result = {};
-  if (common.color !== void 0) {
-    const color = common.color;
-    result.color = color;
-  }
-  if (common.size !== void 0) {
-    const size = common.size;
-    result.size = size;
-  }
-  if (common.variant !== void 0) {
-    const variant = common.variant;
-    result.variant = variant;
-  }
-  if (common.radius !== void 0) {
-    const radius = common.radius;
-    result.radius = radius;
-  }
-  if (common.labelPlacement !== void 0) {
-    const labelPlacement = common.labelPlacement;
-    result.labelPlacement = labelPlacement;
-  }
-  return result;
-}
-function useHeroHookFormDefaults() {
-  const cfg = useContext(DefaultsContext) ?? {};
-  const common = cfg.common ?? {};
-  const commonInput = extractInputCommon(common);
-  const commonTextarea = extractTextareaCommon(common);
-  const commonSelect = extractSelectCommon(common);
-  const commonDateInput = extractDateInputCommon(common);
-  const dateInputBase = {
-    radius: "md",
-    size: "md",
-    variant: "bordered"
-  };
-  return {
-    checkbox: cfg.checkbox ?? {},
-    dateInput: {
-      ...dateInputBase,
-      ...commonDateInput,
-      ...cfg.dateInput ?? {}
-    },
-    input: { ...commonInput, ...cfg.input ?? {} },
-    radioGroup: cfg.radioGroup ?? {},
-    select: { ...commonSelect, ...cfg.select ?? {} },
-    slider: cfg.slider ?? {},
-    submitButton: cfg.submitButton ?? {},
-    switch: cfg.switch ?? {},
-    textarea: { ...commonTextarea, ...cfg.textarea ?? {} }
-  };
-}
-
-// src/fields/CheckboxField.tsx
 function CheckboxField(props) {
   const {
     checkboxProps,
@@ -1446,6 +1486,7 @@ function FieldArrayField({
     max = 10,
     min = 0,
     name,
+    readOnly = false,
     removeButtonText = "Remove",
     renderAddButton,
     renderItem,
@@ -1562,7 +1603,7 @@ function FieldArrayField({
           key: field2.id,
           className: "border border-gray-200 rounded-lg p-4 space-y-4"
         },
-        /* @__PURE__ */ React9.createElement("div", { className: "flex justify-between items-center" }, /* @__PURE__ */ React9.createElement("h4", { className: "text-sm font-medium text-gray-700" }, config.label, " #", index + 1), /* @__PURE__ */ React9.createElement("div", { className: "flex gap-2" }, enableReordering && /* @__PURE__ */ React9.createElement(React9.Fragment, null, /* @__PURE__ */ React9.createElement(
+        /* @__PURE__ */ React9.createElement("div", { className: "flex justify-between items-center" }, /* @__PURE__ */ React9.createElement("h4", { className: "text-sm font-medium text-gray-700" }, config.label, " #", index + 1), !readOnly && /* @__PURE__ */ React9.createElement("div", { className: "flex gap-2" }, enableReordering && /* @__PURE__ */ React9.createElement(React9.Fragment, null, /* @__PURE__ */ React9.createElement(
           Button2,
           {
             size: "sm",
@@ -1599,6 +1640,9 @@ function FieldArrayField({
     });
   };
   const renderAddButtonElement = () => {
+    if (readOnly) {
+      return null;
+    }
     if (renderAddButton) {
       return renderAddButton({
         canAdd,
@@ -2067,10 +2111,12 @@ function StringArrayInput(props) {
     maxItems,
     minItems,
     placeholder = "Add item...",
+    readOnly = false,
     showAddButton = true,
     transformItem = (item) => item.trim(),
     validateItem = () => true
   } = stringArrayProps || {};
+  const defaults = useHeroHookFormDefaults();
   const canAddMore = !maxItems || items.length < maxItems;
   const handleAddItem = () => {
     const trimmedValue = inputValue.trim();
@@ -2087,33 +2133,32 @@ function StringArrayInput(props) {
     const newItems = items.filter((_, index) => index !== indexToRemove);
     field2.onChange(newItems);
   };
-  const handleKeyPress = (e) => {
-    if (e.key === "Enter") {
-      e.preventDefault();
-      if (!showAddButton) {
-        handleAddItem();
-      }
-    }
-  };
-  return /* @__PURE__ */ React16.createElement("div", { className: "space-y-2" }, label && /* @__PURE__ */ React16.createElement("label", { className: "block text-sm font-medium text-foreground" }, label, minItems !== void 0 && /* @__PURE__ */ React16.createElement("span", { className: "text-xs text-muted-foreground ml-1" }, "(min ", minItems, ")"), maxItems !== void 0 && /* @__PURE__ */ React16.createElement("span", { className: "text-xs text-muted-foreground ml-1" }, "(max ", maxItems, ")")), description && /* @__PURE__ */ React16.createElement("p", { className: "text-sm text-muted-foreground" }, description), canAddMore && /* @__PURE__ */ React16.createElement("div", { className: "flex gap-2" }, /* @__PURE__ */ React16.createElement(
+  return /* @__PURE__ */ React16.createElement("div", { className: "space-y-2" }, label && /* @__PURE__ */ React16.createElement("label", { className: "block text-sm font-medium text-foreground" }, label, minItems !== void 0 && /* @__PURE__ */ React16.createElement("span", { className: "text-xs text-muted-foreground ml-1" }, "(min ", minItems, ")"), maxItems !== void 0 && /* @__PURE__ */ React16.createElement("span", { className: "text-xs text-muted-foreground ml-1" }, "(max ", maxItems, ")")), description && /* @__PURE__ */ React16.createElement("p", { className: "text-sm text-muted-foreground" }, description), !readOnly && canAddMore && /* @__PURE__ */ React16.createElement("div", { className: "flex gap-2" }, /* @__PURE__ */ React16.createElement(
     Input,
     {
+      ...defaults.input,
       className: "flex-1",
-      disabled,
+      isInvalid: !!errorMessage,
+      errorMessage,
+      isDisabled: disabled,
       placeholder,
       value: inputValue,
-      onChange: (e) => setInputValue(e.target.value),
-      onKeyPress: handleKeyPress,
-      isInvalid: !!errorMessage,
-      errorMessage
+      onValueChange: setInputValue,
+      onKeyDown: (e) => {
+        if (e.key === "Enter") {
+          e.preventDefault();
+          if (!showAddButton) handleAddItem();
+        }
+      }
     }
   ), showAddButton && /* @__PURE__ */ React16.createElement(
     Button,
     {
+      ...defaults.submitButton,
       type: "button",
       variant: "flat",
-      onClick: handleAddItem,
-      disabled: disabled || !inputValue.trim(),
+      onPress: handleAddItem,
+      isDisabled: disabled || !inputValue.trim(),
       size: "sm"
     },
     addButtonText
@@ -2124,14 +2169,15 @@ function StringArrayInput(props) {
       className: "flex items-center gap-2 p-2 bg-content2 rounded-md"
     },
     /* @__PURE__ */ React16.createElement("span", { className: "flex-1 text-sm" }, item),
-    /* @__PURE__ */ React16.createElement(
+    !readOnly && /* @__PURE__ */ React16.createElement(
       Button,
       {
+        ...defaults.submitButton,
         type: "button",
         variant: "light",
         size: "sm",
-        onClick: () => handleRemoveItem(index),
-        disabled,
+        onPress: () => handleRemoveItem(index),
+        isDisabled: disabled,
         className: "min-w-[60px]"
       },
       "Remove"
@@ -2336,6 +2382,7 @@ function FormFieldComponent({
     }
     case "autocomplete": {
       const autocompleteOptions = "getOptions" in fieldConfig && typeof fieldConfig.getOptions === "function" ? fieldConfig.getOptions() : "options" in fieldConfig && fieldConfig.options ? fieldConfig.options : [];
+      const autocompleteRenderItem = "renderItem" in fieldConfig && typeof fieldConfig.renderItem === "function" ? (item) => /* @__PURE__ */ React19.createElement(React19.Fragment, null, fieldConfig.renderItem(item)) : void 0;
       return /* @__PURE__ */ React19.createElement(
         AutocompleteField,
         {
@@ -2347,7 +2394,8 @@ function FormFieldComponent({
             label: opt.label,
             value: String(opt.value)
           })),
-          autocompleteProps: "autocompleteProps" in fieldConfig ? fieldConfig.autocompleteProps : void 0
+          autocompleteProps: "autocompleteProps" in fieldConfig ? fieldConfig.autocompleteProps : void 0,
+          children: autocompleteRenderItem
         }
       );
     }
@@ -3145,7 +3193,7 @@ function ServerActionField({
           onInputChange: setValue,
           items
         },
-        items.map((item) => /* @__PURE__ */ React21.createElement(AutocompleteItem, { key: String(item.value) }, item.label))
+        items.map((item) => /* @__PURE__ */ React21.createElement(AutocompleteItem, { key: String(item.value) }, typeof stringConfig.renderItem === "function" ? stringConfig.renderItem(item) : item.label))
       );
     }
     case "slider": {
@@ -4051,14 +4099,16 @@ var BasicFormBuilder = class {
   }
   /**
    * Add an autocomplete field (static options array or dynamic getOptions getter).
+   * Optional options.renderItem for custom option layout (e.g. name + email + phone).
    */
-  autocomplete(name, label, items, placeholder) {
+  autocomplete(name, label, items, placeholder, options) {
     const isGetter = typeof items === "function";
     this.fields.push({
       autocompleteProps: placeholder ? { placeholder } : void 0,
       label,
       name,
       ...isGetter ? { getOptions: items } : { options: items },
+      ...options?.renderItem && { renderItem: options.renderItem },
       type: "autocomplete"
     });
     return this;
@@ -4151,9 +4201,14 @@ var FormFieldHelpers = {
    * FormFieldHelpers.autocomplete("personId", "Person", () => people.map(p => ({ label: p.name, value: p.id })), "Search people", {
    *   onInputChange: (q) => fetchPeople(q).then(setPeople),
    * })
+   *
+   * // Custom option layout (e.g. name + email + phone per option)
+   * FormFieldHelpers.autocomplete("personId", "Person", getOptions, "Search", undefined, {
+   *   renderItem: (item) => <div><strong>{item.label}</strong><br /><small>{getSubtitle(item.value)}</small></div>,
+   * })
    * ```
    */
-  autocomplete: (name, label, items, placeholder, autocompleteProps) => {
+  autocomplete: (name, label, items, placeholder, autocompleteProps, options) => {
     const isGetter = typeof items === "function";
     return {
       autocompleteProps: {
@@ -4161,6 +4216,7 @@ var FormFieldHelpers = {
         ...autocompleteProps
       },
       ...isGetter ? { getOptions: items } : { options: items },
+      ...options?.renderItem && { renderItem: options.renderItem },
       label,
       name,
       type: "autocomplete"
@@ -4838,6 +4894,7 @@ function createFieldFromParams(params) {
         label: params.label,
         name: params.name,
         ...typeof params.getOptions === "function" ? { getOptions: params.getOptions } : { options: params.options },
+        ...params.renderItem && { renderItem: params.renderItem },
         type: "autocomplete"
       };
     case "content":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rachelallyson/hero-hook-form",
-  "version": "2.11.0",
+  "version": "2.13.0",
   "description": "Typed form helpers that combine React Hook Form and HeroUI components.",
   "author": "Rachel Higley",
   "homepage": "https://rachelallyson.github.io/hero-hook-form/",