{
+ it('keeps all values when no fields are disabled', () => {
+ const values = {
+ name: 'Ada',
+ count: 0,
+ active: false,
+ empty: '',
+ nullable: null,
+ };
+
+ expect(omitDisabledValues(values, [])).toStrictEqual(values);
+ });
+
+ it('removes disabled properties while preserving enabled falsy values', () => {
+ const values = Object.freeze({
+ excluded: 'stored',
+ count: 0,
+ active: false,
+ empty: '',
+ nullable: null,
+ });
+
+ expect(omitDisabledValues(values, ['excluded'])).toStrictEqual({
+ count: 0,
+ active: false,
+ empty: '',
+ nullable: null,
+ });
+ expect(values.excluded).toBe('stored');
+ });
+
+ it('removes nested values without mutating frozen form state', () => {
+ const profile = Object.freeze({ email: 'ada@example.com', name: 'Ada' });
+ const values = Object.freeze({ profile, enabled: 'keep' });
+
+ expect(omitDisabledValues(values, ['profile.email'])).toStrictEqual({
+ profile: { name: 'Ada' },
+ enabled: 'keep',
+ });
+ expect(values.profile).toStrictEqual({
+ email: 'ada@example.com',
+ name: 'Ada',
+ });
+ });
+
+ it.each(['rows.1.name', 'rows[1].name'])(
+ 'only removes the targeted array-row property for %s',
+ (name) => {
+ const rows = Object.freeze([
+ Object.freeze({ name: 'first', code: 'a' }),
+ Object.freeze({ name: 'second', code: 'b' }),
+ Object.freeze({ name: 'third', code: 'c' }),
+ ]);
+ const values = Object.freeze({ rows });
+
+ expect(omitDisabledValues(values, [name])).toStrictEqual({
+ rows: [
+ { name: 'first', code: 'a' },
+ { code: 'b' },
+ { name: 'third', code: 'c' },
+ ],
+ });
+ expect(values.rows[1]).toStrictEqual({ name: 'second', code: 'b' });
+ },
+ );
+
+ it.each(['tags.1', 'tags[1]', 'tags.1.__FLAT__', 'tags[1].__FLAT__'])(
+ 'removes an array value without shifting later indices for %s',
+ (name) => {
+ const values = Object.freeze({
+ tags: Object.freeze(['first', 'excluded', 'third']),
+ });
+
+ const result = omitDisabledValues(values, [name]);
+
+ expect(result).toHaveProperty('tags.length', 3);
+ expect(result).toHaveProperty('tags.0', 'first');
+ expect(result).not.toHaveProperty('tags.1');
+ expect(result).toHaveProperty('tags.2', 'third');
+ expect(values.tags).toStrictEqual(['first', 'excluded', 'third']);
+ },
+ );
+
+ it.each([
+ ['tags.0.__FLAT__', 'tags.1.__FLAT__'],
+ ['tags.1.__FLAT__', 'tags.0.__FLAT__'],
+ ])('preserves every omitted array slot for %s then %s', (first, second) => {
+ const values = Object.freeze({
+ tags: Object.freeze(['first', 'second', 'third']),
+ });
+
+ const result = omitDisabledValues(values, [first, second]);
+
+ expect(result).toHaveProperty('tags.length', 3);
+ expect(result).not.toHaveProperty('tags.0');
+ expect(result).not.toHaveProperty('tags.1');
+ expect(result).toHaveProperty('tags.2', 'third');
+ expect(values.tags).toStrictEqual(['first', 'second', 'third']);
+ });
+
+ it('ignores missing paths and paths through primitive or nullish values', () => {
+ const values = {
+ profile: { name: 'Ada' },
+ nullable: null,
+ absent: undefined,
+ zero: 0,
+ active: false,
+ };
+
+ expect(
+ omitDisabledValues(values, [
+ 'missing.child',
+ 'profile.missing',
+ 'profile.name.child',
+ 'nullable.child',
+ 'absent.child',
+ 'zero.child',
+ 'active.child',
+ ]),
+ ).toStrictEqual(values);
+ });
+
+ it('handles duplicate and overlapping parent/child paths in either order', () => {
+ const values = Object.freeze({
+ profile: Object.freeze({ email: 'ada@example.com' }),
+ enabled: 'keep',
+ });
+
+ expect(
+ omitDisabledValues(values, ['profile', 'profile.email', 'profile']),
+ ).toStrictEqual({ enabled: 'keep' });
+ expect(
+ omitDisabledValues(values, ['profile.email', 'profile']),
+ ).toStrictEqual({ enabled: 'keep' });
+ expect(values.profile.email).toBe('ada@example.com');
+ });
+
+ it('ignores inherited properties', () => {
+ const values = { enabled: 'keep' };
+
+ expect(omitDisabledValues(values, ['toString.name'])).toBe(values);
+ });
+});
diff --git a/packages/uniform/src/helpers/disabledFields/disabledFields.ts b/packages/uniform/src/helpers/disabledFields/disabledFields.ts
new file mode 100644
index 000000000..b9c6e38f6
--- /dev/null
+++ b/packages/uniform/src/helpers/disabledFields/disabledFields.ts
@@ -0,0 +1,53 @@
+import type { FieldValues } from 'react-hook-form';
+
+import { flatArrayKey } from '../nullishFields/nullishFields';
+
+/** Removes one path by copying only its ancestors, leaving stored values and array indices intact. */
+const omitPath = (
+ value: unknown,
+ [key, ...rest]: readonly string[],
+): unknown => {
+ if (
+ !value ||
+ typeof value !== 'object' ||
+ key === undefined ||
+ !Object.getOwnPropertyDescriptor(value, key)
+ ) {
+ return value;
+ }
+
+ // Preserve holes left by previously omitted array entries.
+ const copy = (Array.isArray(value) ? value.slice() : { ...value }) as Record<
+ string,
+ unknown
+ >;
+
+ if (rest.length) {
+ copy[key] = omitPath(copy[key], rest);
+ } else {
+ // Delete rather than splice so later array fields keep their indices.
+ delete copy[key];
+ }
+
+ return copy;
+};
+
+/** Omits disabled fields from normalized validation/submission data without changing form state. */
+const omitDisabledValues = (
+ values: FieldValues,
+ names: readonly string[],
+): FieldValues => {
+ return names.reduce((data, name) => {
+ // Match RHF names to normalized data, where flat-array wrappers are gone.
+ const path = name
+ .replace(/\[(\d+)\]/g, '.$1')
+ .split('.')
+ .filter((part) => {
+ return part !== flatArrayKey;
+ });
+
+ return omitPath(data, path) as FieldValues;
+ }, values);
+};
+
+export default omitDisabledValues;
diff --git a/packages/uniform/src/hooks/README.md b/packages/uniform/src/hooks/README.md
new file mode 100644
index 000000000..539203153
--- /dev/null
+++ b/packages/uniform/src/hooks/README.md
@@ -0,0 +1,23 @@
+# Uniform hooks
+
+These hooks connect form components to React Hook Form and Uniform's validation,
+value conversion, and change notifications. Most need a parent Uniform `Form`.
+
+| Hook | Purpose |
+| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| [useUniformField](useUniformField/useUniformField.tsx) | Combines registration, labels, validation feedback, test IDs, and value transforms for field components |
+| [useUniformFieldArray](useUniformFieldArray/useUniformFieldArray.ts) | Adds flat-array support, initialization, reset handling, and animation state to RHF field arrays |
+| [useController](useController/useController.ts) | Wraps RHF's controller with nullish-value conversion and user-change notifications |
+| [useFormContext](useFormContext/useFormContext.ts) | Provides RHF methods with schema-aware field state, value conversion, and reset notifications |
+| [useClientValidation](useClientValidation/useClientValidation.ts) | Registers dynamic client validation alongside the form's base schema |
+| [useInput](useInput/useInput.ts) | Re-exports HeroUI's input hook |
+| [useInputValueDebounce](useInputValueDebounce/useInputValueDebounce.ts) | Updates displayed input immediately, debounces stored changes, and flushes on blur |
+| [useInputValueTransform](useInputValueTransform/useInputValueTransform.ts) | Converts between display values and stored form values |
+| [useWatchFormReset](useWatchFormReset/useWatchFormReset.ts) | Runs a callback for resets made through Uniform's form context |
+| [useWatchUserChange](useWatchUserChange/useWatchUserChange.ts) | Reacts to user edits without firing for programmatic value changes or resets |
+
+For custom fields, start with `useUniformField`. For ordinary form access, use
+`useFormContext`. Form initialization uses React Hook Form's `useForm` internally;
+Uniform does not add a separate hook with that name.
+
+See also [Uniform compared with React Hook Form](../../../../docs/uniform-vs-rhf.md).
diff --git a/packages/uniform/src/hooks/useUniformField/useUniformField.tsx b/packages/uniform/src/hooks/useUniformField/useUniformField.tsx
index 489ea7075..a4cec56ae 100644
--- a/packages/uniform/src/hooks/useUniformField/useUniformField.tsx
+++ b/packages/uniform/src/hooks/useUniformField/useUniformField.tsx
@@ -23,7 +23,7 @@ export interface UseUniformFieldParams<
name: Path & string;
/** Custom aria-label for accessibility. If not provided, falls back to field name when no visible label exists */
ariaLabel?: string;
- /** Disable the field */
+ /** Disables the field and omits its value from validation data and submission */
disabled?: boolean;
/** Normalize nested RHF errors into a flat array for array-like fields */
isArrayValue?: boolean;