feat: Add htmlName prop

nlemoine · nlemoine · commit 130a2f45264d · 2025-10-14T21:09:56.000+02:00
diff --git a/packages/core/src/components/Form.tsx b/packages/core/src/components/Form.tsx
@@ -42,6 +42,7 @@ import {
   DEFAULT_ID_PREFIX,
   GlobalFormOptions,
   ERRORS_KEY,
+  NameGeneratorFunction,
 } from '@rjsf/utils';
 import _cloneDeep from 'lodash/cloneDeep';
 import _get from 'lodash/get';
@@ -195,6 +196,7 @@ export interface FormProps<T = any, S extends StrictRJSFSchema = RJSFSchema, F e
    * to put the second parameter before the first in its translation.
    */
   translateString?: Registry['translateString'];
+  nameGenerator?: NameGeneratorFunction;
   /** Optional configuration object with flags, if provided, allows users to override default form state behavior
    * Currently only affecting minItems on array fields and handling of setting defaults based on the value of
    * `emptyObjectFields`
@@ -994,10 +996,16 @@ export default class Form<
       experimental_componentUpdateStrategy,
       idSeparator = DEFAULT_ID_SEPARATOR,
       idPrefix = DEFAULT_ID_PREFIX,
+      nameGenerator,
     } = props;
     const rootFieldId = uiSchema['ui:rootFieldId'];
     // Omit any options that are undefined or null
-    return { idPrefix: rootFieldId || idPrefix, idSeparator, experimental_componentUpdateStrategy };
+    return {
+      idPrefix: rootFieldId || idPrefix,
+      idSeparator,
+      ...(experimental_componentUpdateStrategy !== undefined && { experimental_componentUpdateStrategy }),
+      ...(nameGenerator !== undefined && { nameGenerator }),
+    };
   }
 
   /** Returns the registry for the form */
diff --git a/packages/core/src/components/fields/ArrayField.tsx b/packages/core/src/components/fields/ArrayField.tsx
@@ -624,6 +624,7 @@ class ArrayField<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends For
         placeholder={placeholder}
         autofocus={autofocus}
         rawErrors={rawErrors}
+        htmlName={fieldPathId.name}
       />
     );
   }
@@ -675,6 +676,7 @@ class ArrayField<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends For
         placeholder={placeholder}
         autofocus={autofocus}
         rawErrors={rawErrors}
+        htmlName={fieldPathId.name}
       />
     );
   }
@@ -722,6 +724,7 @@ class ArrayField<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends For
         rawErrors={rawErrors}
         label={label}
         hideLabel={!displayLabel}
+        htmlName={fieldPathId.name}
       />
     );
   }
diff --git a/packages/core/src/components/fields/BooleanField.tsx b/packages/core/src/components/fields/BooleanField.tsx
@@ -116,6 +116,7 @@ function BooleanField<T = any, S extends StrictRJSFSchema = RJSFSchema, F extend
       registry={registry}
       autofocus={autofocus}
       rawErrors={rawErrors}
+      htmlName={fieldPathId.name}
     />
   );
 }
diff --git a/packages/core/src/components/fields/LayoutMultiSchemaField.tsx b/packages/core/src/components/fields/LayoutMultiSchemaField.tsx
@@ -220,6 +220,7 @@ export default function LayoutMultiSchemaField<
         onFocus={onFocus}
         value={selectedOption}
         options={widgetOptions}
+        htmlName={fieldPathId.name}
       />
     </FieldTemplate>
   );
diff --git a/packages/core/src/components/fields/StringField.tsx b/packages/core/src/components/fields/StringField.tsx
@@ -74,6 +74,7 @@ function StringField<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends
       registry={registry}
       placeholder={placeholder}
       rawErrors={rawErrors}
+      htmlName={fieldPathId.name}
     />
   );
 }
diff --git a/packages/core/src/components/templates/BaseInputTemplate.tsx b/packages/core/src/components/templates/BaseInputTemplate.tsx
@@ -23,6 +23,7 @@ export default function BaseInputTemplate<
   const {
     id,
     name, // remove this from ...rest
+    htmlName,
     value,
     readonly,
     disabled,
@@ -77,7 +78,7 @@ export default function BaseInputTemplate<
     <>
       <input
         id={id}
-        name={id}
+        name={htmlName || id}
         className='form-control'
         readOnly={readonly}
         disabled={disabled}
diff --git a/packages/core/src/components/widgets/CheckboxWidget.tsx b/packages/core/src/components/widgets/CheckboxWidget.tsx
@@ -31,6 +31,7 @@ function CheckboxWidget<T = any, S extends StrictRJSFSchema = RJSFSchema, F exte
   onFocus,
   onChange,
   registry,
+  htmlName,
 }: WidgetProps<T, S, F>) {
   const DescriptionFieldTemplate = getTemplate<'DescriptionFieldTemplate', T, S, F>(
     'DescriptionFieldTemplate',
@@ -73,7 +74,7 @@ function CheckboxWidget<T = any, S extends StrictRJSFSchema = RJSFSchema, F exte
         <input
           type='checkbox'
           id={id}
-          name={id}
+          name={htmlName || id}
           checked={typeof value === 'undefined' ? false : value}
           required={required}
           disabled={disabled || readonly}
diff --git a/packages/core/src/components/widgets/CheckboxesWidget.tsx b/packages/core/src/components/widgets/CheckboxesWidget.tsx
@@ -27,6 +27,7 @@ function CheckboxesWidget<T = any, S extends StrictRJSFSchema = RJSFSchema, F ex
   onChange,
   onBlur,
   onFocus,
+  htmlName,
 }: WidgetProps<T, S, F>) {
   const checkboxesValues = Array.isArray(value) ? value : [value];
 
@@ -62,7 +63,7 @@ function CheckboxesWidget<T = any, S extends StrictRJSFSchema = RJSFSchema, F ex
               <input
                 type='checkbox'
                 id={optionId(id, index)}
-                name={id}
+                name={htmlName || id}
                 checked={checked}
                 value={String(index)}
                 disabled={disabled || itemDisabled || readonly}
diff --git a/packages/core/src/components/widgets/HiddenWidget.tsx b/packages/core/src/components/widgets/HiddenWidget.tsx
@@ -8,8 +8,9 @@ import { FormContextType, RJSFSchema, StrictRJSFSchema, WidgetProps } from '@rjs
 function HiddenWidget<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any>({
   id,
   value,
+  htmlName,
 }: WidgetProps<T, S, F>) {
-  return <input type='hidden' id={id} name={id} value={typeof value === 'undefined' ? '' : value} />;
+  return <input type='hidden' id={id} name={htmlName || id} value={typeof value === 'undefined' ? '' : value} />;
 }
 
 export default HiddenWidget;
diff --git a/packages/core/src/components/widgets/RadioWidget.tsx b/packages/core/src/components/widgets/RadioWidget.tsx
@@ -26,6 +26,7 @@ function RadioWidget<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends
   onFocus,
   onChange,
   id,
+  htmlName,
 }: WidgetProps<T, S, F>) {
   const { enumOptions, enumDisabled, inline, emptyValue } = options;
 
@@ -57,7 +58,7 @@ function RadioWidget<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends
                 type='radio'
                 id={optionId(id, i)}
                 checked={checked}
-                name={id}
+                name={htmlName || id}
                 required={required}
                 value={String(i)}
                 disabled={disabled || itemDisabled || readonly}
diff --git a/packages/core/src/components/widgets/RatingWidget.tsx b/packages/core/src/components/widgets/RatingWidget.tsx
@@ -29,6 +29,7 @@ export default function RatingWidget<
   onBlur,
   schema,
   options,
+  htmlName,
 }: WidgetProps<T, S, F>) {
   const { stars = 5, shape = 'star' } = options;
 
@@ -117,7 +118,7 @@ export default function RatingWidget<
         <input
           type='hidden'
           id={id}
-          name={id}
+          name={htmlName || id}
           value={value || ''}
           required={required}
           disabled={disabled || readonly}
diff --git a/packages/core/src/components/widgets/SelectWidget.tsx b/packages/core/src/components/widgets/SelectWidget.tsx
@@ -38,6 +38,7 @@ function SelectWidget<T = any, S extends StrictRJSFSchema = RJSFSchema, F extend
   onBlur,
   onFocus,
   placeholder,
+  htmlName,
 }: WidgetProps<T, S, F>) {
   const { enumOptions, enumDisabled, emptyValue: optEmptyVal } = options;
   const emptyValue = multiple ? [] : '';
@@ -72,7 +73,7 @@ function SelectWidget<T = any, S extends StrictRJSFSchema = RJSFSchema, F extend
   return (
     <select
       id={id}
-      name={id}
+      name={id || htmlName}
       multiple={multiple}
       role='combobox'
       className='form-control'
diff --git a/packages/core/src/components/widgets/TextareaWidget.tsx b/packages/core/src/components/widgets/TextareaWidget.tsx
@@ -17,6 +17,7 @@ function TextareaWidget<T = any, S extends StrictRJSFSchema = RJSFSchema, F exte
   onChange,
   onBlur,
   onFocus,
+  htmlName,
 }: WidgetProps<T, S, F>) {
   const handleChange = useCallback(
     ({ target: { value } }: ChangeEvent<HTMLTextAreaElement>) => onChange(value === '' ? options.emptyValue : value),
@@ -36,7 +37,7 @@ function TextareaWidget<T = any, S extends StrictRJSFSchema = RJSFSchema, F exte
   return (
     <textarea
       id={id}
-      name={id}
+      name={htmlName || id}
       className='form-control'
       value={value ? value : ''}
       placeholder={placeholder}
diff --git a/packages/core/test/SchemaField.test.jsx b/packages/core/test/SchemaField.test.jsx
@@ -55,7 +55,6 @@ describe('SchemaField', () => {
         globalFormOptions: {
           idPrefix: DEFAULT_ID_PREFIX,
           idSeparator: DEFAULT_ID_SEPARATOR,
-          experimental_componentUpdateStrategy: undefined,
         },
       });
     });
@@ -94,7 +93,6 @@ describe('SchemaField', () => {
         globalFormOptions: {
           idPrefix: DEFAULT_ID_PREFIX,
           idSeparator: DEFAULT_ID_SEPARATOR,
-          experimental_componentUpdateStrategy: undefined,
         },
       });
     });
diff --git a/packages/utils/src/toFieldPathId.ts b/packages/utils/src/toFieldPathId.ts
@@ -4,12 +4,12 @@ import { FieldPathId, FieldPathList, GlobalFormOptions } from './types';
 /** Constructs the `FieldPathId` for `fieldPath`. If `parentPathId` is provided, the `fieldPath` is appended to the end
  * of the parent path. Then the `ID_KEY` of the resulting `FieldPathId` is constructed from the `idPrefix` and
  * `idSeparator` contained within the `globalFormOptions`. If `fieldPath` is passed as an empty string, it will simply
- * generate the path from the `parentPath` (if provided) and the `idPrefix` and `idSeparator`
+ * generate the path from the `parentPath` (if provided) and the `idPrefix` and `idSeparator`. If a `nameGenerator`
+ * is provided in `globalFormOptions`, it will also generate the HTML `name` attribute.
  *
  * @param fieldPath - The property name or array index of the current field element
  * @param globalFormOptions - The `GlobalFormOptions` used to get the `idPrefix` and `idSeparator`
  * @param [parentPath] - The optional `FieldPathId` or `FieldPathList` of the parent element for this field element
- * @returns - The `FieldPathId` for the given `fieldPath` and the optional `parentPathId`
  */
 export default function toFieldPathId(
   fieldPath: string | number,
@@ -20,5 +20,15 @@ export default function toFieldPathId(
   const childPath = fieldPath === '' ? [] : [fieldPath];
   const path = basePath ? basePath.concat(...childPath) : childPath;
   const id = [globalFormOptions.idPrefix, ...path].join(globalFormOptions.idSeparator);
-  return { path, [ID_KEY]: id };
+
+  // Generate name attribute if nameGenerator is provided
+  let name: string | undefined;
+  if (globalFormOptions.nameGenerator && path.length > 0) {
+    // Determine element type based on the last element in the path
+    const lastPathElement = path[path.length - 1];
+    const elementType = typeof lastPathElement === 'number' ? 'array' : 'object';
+    name = globalFormOptions.nameGenerator(path, elementType);
+  }
+
+  return { path, [ID_KEY]: id, ...(name !== undefined && { name }) };
 }
diff --git a/packages/utils/src/types.ts b/packages/utils/src/types.ts
@@ -35,6 +35,9 @@ export type FormContextType = GenericObjectType;
  */
 export type TestIdShape = Record<string, string>;
 
+/** Function to generate HTML name attributes from path segments */
+export type NameGeneratorFunction = (path: FieldPathList, elementType: 'object' | 'array') => string;
+
 /** Experimental feature that specifies the Array `minItems` default form state behavior
  */
 export type Experimental_ArrayMinItems = {
@@ -175,6 +178,8 @@ export type FieldPathId = {
   $id: string;
   /** The path for a field */
   path: FieldPathList;
+  /** The optional HTML name attribute for a field, generated by nameGenerator if provided */
+  name?: string;
 };
 
 /** Type describing a name used for a field in the `PathSchema` */
@@ -420,6 +425,11 @@ export type GlobalFormOptions = {
   readonly idSeparator: string;
   /** The component update strategy used by the Form and its fields for performance optimization */
   readonly experimental_componentUpdateStrategy?: 'customDeep' | 'shallow' | 'always';
+  /** Optional function to generate custom HTML name attributes for form elements. Receives the field path segments
+   * and element type (object or array), and returns a custom name string. This allows backends like PHP/Rails
+   * (`root[tasks][0][title]`) or Django (`root__tasks-0__title`) to receive form data in their expected format.
+   */
+  readonly nameGenerator?: NameGeneratorFunction;
 };
 
 /** The object containing the registered core, theme and custom fields and widgets as well as the root schema, form
@@ -882,6 +892,8 @@ export interface WidgetProps<T = any, S extends StrictRJSFSchema = RJSFSchema, F
   multiple?: boolean;
   /** An array of strings listing all generated error messages from encountered errors for this widget */
   rawErrors?: string[];
+  /** The optional custom HTML name attribute generated by the nameGenerator function, if provided */
+  htmlName?: string;
 }
 
 /** The definition of a React-based Widget component */

Original file line number	Diff line number	Diff line change
`@@ -116,6 +116,7 @@ function BooleanField<T = any, S extends StrictRJSFSchema = RJSFSchema, F extend`
`116`	`116`	`registry={registry}`
`117`	`117`	`autofocus={autofocus}`
`118`	`118`	`rawErrors={rawErrors}`
	`119`	`+ htmlName={fieldPathId.name}`
`119`	`120`	`/>`
`120`	`121`	`);`
`121`	`122`	`}`
Original file line number	Diff line number	Diff line change
`@@ -74,6 +74,7 @@ function StringField<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends`
`74`	`74`	`registry={registry}`
`75`	`75`	`placeholder={placeholder}`
`76`	`76`	`rawErrors={rawErrors}`
	`77`	`+ htmlName={fieldPathId.name}`
`77`	`78`	`/>`
`78`	`79`	`);`
`79`	`80`	`}`