@instructure/ui-form-field 11.7.9-snapshot-5 → 11.7.10

package/CHANGELOG.md

@@ -3,12 +3,18 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [11.7.9-snapshot-5](https://github.com/instructure/instructure-ui/compare/v11.7.8...v11.7.9-snapshot-5) (2026-10-13)
+## [11.7.10](https://github.com/instructure/instructure-ui/compare/v11.7.8...v11.7.10) (2026-10-14)
 
-**Note:** Version bump only for package @instructure/ui-form-field
+### Bug Fixes
+
+* **many:** Stop wrapping form field controls in their label ([#2740](https://github.com/instructure/instructure-ui/issues/2740)) ([467269e](https://github.com/instructure/instructure-ui/commit/467269ea6d66c88ef9deb8bd14980730bbd645e8))
 
 
+## [11.7.9](https://github.com/instructure/instructure-ui/compare/v11.7.8...v11.7.9) (2026-10-13)
+
+### Bug Fixes
 
+* **many:** Stop wrapping form field controls in their label ([#2740](https://github.com/instructure/instructure-ui/issues/2740)) ([467269e](https://github.com/instructure/instructure-ui/commit/467269ea6d66c88ef9deb8bd14980730bbd645e8))
 
 
 ## [11.7.8](https://github.com/instructure/instructure-ui/compare/v11.7.7...v11.7.8) (2026-10-02)

package/es/FormField/v2/index.js

@@ -58,13 +58,8 @@ class FormField extends Component {
       ...omitProps(this.props, FormField.allowedProps),
       ...pickProps(this.props, formFieldLayoutAllowedProps),
       label: this.props.label,
+      id: this.props.id,
       vAlign: this.props.vAlign,
-      as: "label"
-      // This makes the control in focus when the label is clicked
-      // This is needed to prevent the wrong element to be focused, e.g.
-      // multi selects Tag-s
-      ,
-      htmlFor: this.props.id,
       elementRef: this.handleRef,
       margin: this.props.margin,
       isRequired: this.props.isRequired,

package/es/FormFieldGroup/v2/index.js

@@ -1,4 +1,4 @@
-var _dec, _class;
+var _dec, _dec2, _class;
 /*
  * The MIT License (MIT)
  *
@@ -25,7 +25,7 @@ var _dec, _class;
 
 import { Component, Children, isValidElement } from 'react';
 import { Grid } from '@instructure/ui-grid/latest';
-import { pickProps, omitProps, safeCloneElement } from '@instructure/ui-react-utils';
+import { pickProps, omitProps, safeCloneElement, withDeterministicId } from '@instructure/ui-react-utils';
 import { withStyleNew } from '@instructure/emotion';
 import { allowedProps as formFieldLayoutAllowedProps } from '../../FormFieldLayout/v2/props.js';
 import { FormFieldLayout } from '../../FormFieldLayout/v2/index.js';
@@ -37,7 +37,7 @@ import { jsx as _jsx } from "@emotion/react/jsx-runtime";
 category: components
 ---
 **/
-let FormFieldGroup = (_dec = withStyleNew(generateStyle), _dec(_class = class FormFieldGroup extends Component {
+let FormFieldGroup = (_dec = withDeterministicId(), _dec2 = withStyleNew(generateStyle), _dec(_class = _dec2(_class = class FormFieldGroup extends Component {
   static displayName = 'FormFieldGroup';
   static componentId = 'FormFieldGroup';
   static allowedProps = allowedProps;
@@ -49,6 +49,11 @@ let FormFieldGroup = (_dec = withStyleNew(generateStyle), _dec(_class = class Fo
     vAlign: 'middle',
     isGroup: true
   };
+  constructor(props) {
+    super(props);
+    this._defaultId = props.deterministicId();
+  }
+  _defaultId;
   ref = null;
   handleRef = el => {
     const {
@@ -70,11 +75,13 @@ let FormFieldGroup = (_dec = withStyleNew(generateStyle), _dec(_class = class Fo
       return message.type === 'error' || message.type === 'newError';
     }) >= 0;
   }
-  renderColumns() {
+  renderColumns(params) {
     const {
-      disabled
+      disabled,
+      children
     } = this.props;
-    return Children.map(this.props.children, (child, index) => {
+    const fields = typeof children === 'function' ? children(params) : children;
+    return Children.map(fields, (child, index) => {
       if (!child) return null;
       const el = child;
       const renderedChild = disabled && /*#__PURE__*/isValidElement(el) ? safeCloneElement(el, {
@@ -86,24 +93,24 @@ let FormFieldGroup = (_dec = withStyleNew(generateStyle), _dec(_class = class Fo
       }, index);
     });
   }
-  renderChildren() {
+  renderChildren(params) {
     return _jsx(Grid, {
       colSpacing: this.props.colSpacing,
       rowSpacing: this.props.rowSpacing,
       vAlign: this.props.vAlign,
       startAt: this.props.startAt || (this.props.layout === 'columns' ? 'medium' : null),
       children: _jsx(Grid.Row, {
-        children: this.renderColumns()
+        children: this.renderColumns(params)
       })
     });
   }
-  renderFields() {
+  renderFields(params) {
     const {
       styles
     } = this.props;
     return _jsx("span", {
       css: styles?.formFieldGroup,
-      children: this.renderChildren()
+      children: this.renderChildren(params)
     }, "fields");
   }
   render() {
@@ -128,13 +135,14 @@ let FormFieldGroup = (_dec = withStyleNew(generateStyle), _dec(_class = class Fo
       vAlign: props.vAlign,
       layout: props.layout === 'inline' ? 'inline' : 'stacked',
       label: props.description,
+      id: props.id || this._defaultId,
       "aria-disabled": props.disabled ? 'true' : undefined,
       "aria-invalid": ariaInvalid,
       elementRef: this.handleRef,
       isGroup: isGroup,
-      children: this.renderFields()
+      children: params => this.renderFields(params)
     });
   }
-}) || _class);
+}) || _class) || _class);
 export default FormFieldGroup;
 export { FormFieldGroup };

package/es/FormFieldLayout/v2/index.js

@@ -30,6 +30,12 @@ import { FormFieldMessages } from '../../FormFieldMessages/v2/index.js';
 import generateStyle from './styles.js';
 import { allowedProps } from './props.js';
 import { jsxs as _jsxs, Fragment as _Fragment, jsx as _jsx } from "@emotion/react/jsx-runtime";
+// Elements that handle clicks themselves, do not override it
+const INTERACTIVE_SELECTOR = ['a[href]', 'button', 'input', 'select', 'textarea', 'label', 'summary', 'iframe', 'embed', 'object', 'audio[controls]', 'video[controls]', '[contenteditable]:not([contenteditable="false"])', '[tabindex]'].join(',');
+
+// Clicks already forwarded by a nested FormFieldLayout
+const forwardedClicks = new WeakSet();
+
 /**
 ---
 parent: FormField
@@ -39,10 +45,11 @@ const FormFieldLayout = /*#__PURE__*/forwardRef((props, ref) => {
   const {
     inline = false,
     layout = 'stacked',
-    as = 'label',
+    as = 'div',
     labelAlign = 'end',
     vAlign,
     label,
+    id,
     messages,
     messagesId: messagesIdProp,
     labelId: labelIdProp,
@@ -93,6 +100,7 @@ const FormFieldLayout = /*#__PURE__*/forwardRef((props, ref) => {
     }
   }
   const hasVisibleLabel = label ? hasVisibleChildren(label) : false;
+  const describedBy = hasMessages ? messagesId : undefined;
   const invalid = !!filteredMessages?.find(m => m.type === 'error' || m.type === 'newError');
 
   // Styles
@@ -132,6 +140,28 @@ const FormFieldLayout = /*#__PURE__*/forwardRef((props, ref) => {
       inputContainerRef(node);
     }
   }, [inputContainerRef]);
+
+  // Clicks on the rest of the control area (icons, before/after content) need
+  // to be forwarded to the control.
+  const handleChildrenClick = e => {
+    if (
+    // it's a group, no clear control to forward to
+    ElementType === 'fieldset' || e.defaultPrevented || forwardedClicks.has(e.nativeEvent)) {
+      return;
+    }
+    const container = e.currentTarget;
+    const interactive = e.target.closest(INTERACTIVE_SELECTOR);
+    if (interactive && container.contains(interactive)) {
+      return; // do not steal clicks for e.g. DateInput's calendar icon
+    }
+    const control = id ? container.ownerDocument.getElementById(id) : null;
+    if (!control || !container.contains(control)) {
+      return; // no control
+    }
+    forwardedClicks.add(e.nativeEvent);
+    control.focus();
+    control.click();
+  };
   const renderLabel = () => {
     const labelContent = hasVisibleLabel ? _jsxs(_Fragment, {
       children: [label, isRequired && _jsxs("span", {
@@ -154,9 +184,10 @@ const FormFieldLayout = /*#__PURE__*/forwardRef((props, ref) => {
           })
         });
       }
-      return _jsx("span", {
+      return _jsx("label", {
         css: styles?.formFieldLabel,
         id: labelId,
+        htmlFor: id,
         children: labelContent
       });
     } else if (label) {
@@ -169,9 +200,9 @@ const FormFieldLayout = /*#__PURE__*/forwardRef((props, ref) => {
           children: label
         });
       }
-      // needs to be wrapped because it needs an `id`
-      return _jsx("div", {
+      return _jsx("label", {
         id: labelId,
+        htmlFor: id,
         style: {
           display: 'contents'
         },
@@ -198,7 +229,10 @@ const FormFieldLayout = /*#__PURE__*/forwardRef((props, ref) => {
     children: [renderLabel(), isGroup && renderMessages(), _jsx("span", {
       css: styles?.formFieldChildren,
       ref: handleInputContainerRef,
-      children: children
+      onClick: handleChildrenClick,
+      children: typeof children === 'function' ? children({
+        describedBy
+      }) : children
     }), !isGroup && renderMessages()]
   });
 });

package/es/FormFieldLayout/v2/styles.js

@@ -90,6 +90,7 @@ const generateStyle = (componentTheme, params, sharedTokens) => {
     fontWeight: componentTheme.fontWeight,
     fontSize: componentTheme.fontSize,
     lineHeight: componentTheme.lineHeight,
+    paddingBottom: hasVisibleMessage ? '0' : componentTheme.gapPrimitives,
     ...(isInlineLayout && {
       margin: '0',
       // when inline add a small padding between the label and the control
@@ -143,8 +144,7 @@ const generateStyle = (componentTheme, params, sharedTokens) => {
       ...labelStyles,
       // NOTE: needs separate groups for `:is()` and `:-webkit-any()` because of css selector group validation (see https://www.w3.org/TR/selectors-3/#grouping)
       '&:is(label)': labelStyles,
-      '&:-webkit-any(label)': labelStyles,
-      paddingBottom: hasVisibleMessage ? '0' : componentTheme.gapPrimitives
+      '&:-webkit-any(label)': labelStyles
     },
     formFieldChildren: {
       label: 'formFieldLayout__children',

package/lib/FormField/v2/index.js

@@ -64,13 +64,8 @@ class FormField extends _react.Component {
       ...(0, _uiReactUtils.omitProps)(this.props, FormField.allowedProps),
       ...(0, _uiReactUtils.pickProps)(this.props, _props.allowedProps),
       label: this.props.label,
+      id: this.props.id,
       vAlign: this.props.vAlign,
-      as: "label"
-      // This makes the control in focus when the label is clicked
-      // This is needed to prevent the wrong element to be focused, e.g.
-      // multi selects Tag-s
-      ,
-      htmlFor: this.props.id,
       elementRef: this.handleRef,
       margin: this.props.margin,
       isRequired: this.props.isRequired,

package/lib/FormFieldGroup/v2/index.js

@@ -14,7 +14,7 @@ var _index = require("../../FormFieldLayout/v2/index.js");
 var _styles = _interopRequireDefault(require("./styles.js"));
 var _props2 = require("./props.js");
 var _jsxRuntime = require("@emotion/react/jsx-runtime");
-var _dec, _class;
+var _dec, _dec2, _class;
 /*
  * The MIT License (MIT)
  *
@@ -43,7 +43,7 @@ var _dec, _class;
 category: components
 ---
 **/
-let FormFieldGroup = exports.FormFieldGroup = (_dec = (0, _emotion.withStyleNew)(_styles.default), _dec(_class = class FormFieldGroup extends _react.Component {
+let FormFieldGroup = exports.FormFieldGroup = (_dec = (0, _uiReactUtils.withDeterministicId)(), _dec2 = (0, _emotion.withStyleNew)(_styles.default), _dec(_class = _dec2(_class = class FormFieldGroup extends _react.Component {
   static displayName = 'FormFieldGroup';
   static componentId = 'FormFieldGroup';
   static allowedProps = _props2.allowedProps;
@@ -55,6 +55,11 @@ let FormFieldGroup = exports.FormFieldGroup = (_dec = (0, _emotion.withStyleNew)
     vAlign: 'middle',
     isGroup: true
   };
+  constructor(props) {
+    super(props);
+    this._defaultId = props.deterministicId();
+  }
+  _defaultId;
   ref = null;
   handleRef = el => {
     const {
@@ -76,11 +81,13 @@ let FormFieldGroup = exports.FormFieldGroup = (_dec = (0, _emotion.withStyleNew)
       return message.type === 'error' || message.type === 'newError';
     }) >= 0;
   }
-  renderColumns() {
+  renderColumns(params) {
     const {
-      disabled
+      disabled,
+      children
     } = this.props;
-    return _react.Children.map(this.props.children, (child, index) => {
+    const fields = typeof children === 'function' ? children(params) : children;
+    return _react.Children.map(fields, (child, index) => {
       if (!child) return null;
       const el = child;
       const renderedChild = disabled && /*#__PURE__*/(0, _react.isValidElement)(el) ? (0, _uiReactUtils.safeCloneElement)(el, {
@@ -92,24 +99,24 @@ let FormFieldGroup = exports.FormFieldGroup = (_dec = (0, _emotion.withStyleNew)
       }, index);
     });
   }
-  renderChildren() {
+  renderChildren(params) {
     return (0, _jsxRuntime.jsx)(_latest.Grid, {
       colSpacing: this.props.colSpacing,
       rowSpacing: this.props.rowSpacing,
       vAlign: this.props.vAlign,
       startAt: this.props.startAt || (this.props.layout === 'columns' ? 'medium' : null),
       children: (0, _jsxRuntime.jsx)(_latest.Grid.Row, {
-        children: this.renderColumns()
+        children: this.renderColumns(params)
       })
     });
   }
-  renderFields() {
+  renderFields(params) {
     const {
       styles
     } = this.props;
     return (0, _jsxRuntime.jsx)("span", {
       css: styles?.formFieldGroup,
-      children: this.renderChildren()
+      children: this.renderChildren(params)
     }, "fields");
   }
   render() {
@@ -134,12 +141,13 @@ let FormFieldGroup = exports.FormFieldGroup = (_dec = (0, _emotion.withStyleNew)
       vAlign: props.vAlign,
       layout: props.layout === 'inline' ? 'inline' : 'stacked',
       label: props.description,
+      id: props.id || this._defaultId,
       "aria-disabled": props.disabled ? 'true' : undefined,
       "aria-invalid": ariaInvalid,
       elementRef: this.handleRef,
       isGroup: isGroup,
-      children: this.renderFields()
+      children: params => this.renderFields(params)
     });
   }
-}) || _class);
+}) || _class) || _class);
 var _default = exports.default = FormFieldGroup;

package/lib/FormFieldLayout/v2/index.js

@@ -44,6 +44,12 @@ var _jsxRuntime = require("@emotion/react/jsx-runtime");
  * SOFTWARE.
  */
 
+// Elements that handle clicks themselves, do not override it
+const INTERACTIVE_SELECTOR = ['a[href]', 'button', 'input', 'select', 'textarea', 'label', 'summary', 'iframe', 'embed', 'object', 'audio[controls]', 'video[controls]', '[contenteditable]:not([contenteditable="false"])', '[tabindex]'].join(',');
+
+// Clicks already forwarded by a nested FormFieldLayout
+const forwardedClicks = new WeakSet();
+
 /**
 ---
 parent: FormField
@@ -53,10 +59,11 @@ const FormFieldLayout = exports.FormFieldLayout = /*#__PURE__*/(0, _react.forwar
   const {
     inline = false,
     layout = 'stacked',
-    as = 'label',
+    as = 'div',
     labelAlign = 'end',
     vAlign,
     label,
+    id,
     messages,
     messagesId: messagesIdProp,
     labelId: labelIdProp,
@@ -107,6 +114,7 @@ const FormFieldLayout = exports.FormFieldLayout = /*#__PURE__*/(0, _react.forwar
     }
   }
   const hasVisibleLabel = label ? (0, _uiA11yUtils.hasVisibleChildren)(label) : false;
+  const describedBy = hasMessages ? messagesId : undefined;
   const invalid = !!filteredMessages?.find(m => m.type === 'error' || m.type === 'newError');
 
   // Styles
@@ -146,6 +154,28 @@ const FormFieldLayout = exports.FormFieldLayout = /*#__PURE__*/(0, _react.forwar
       inputContainerRef(node);
     }
   }, [inputContainerRef]);
+
+  // Clicks on the rest of the control area (icons, before/after content) need
+  // to be forwarded to the control.
+  const handleChildrenClick = e => {
+    if (
+    // it's a group, no clear control to forward to
+    ElementType === 'fieldset' || e.defaultPrevented || forwardedClicks.has(e.nativeEvent)) {
+      return;
+    }
+    const container = e.currentTarget;
+    const interactive = e.target.closest(INTERACTIVE_SELECTOR);
+    if (interactive && container.contains(interactive)) {
+      return; // do not steal clicks for e.g. DateInput's calendar icon
+    }
+    const control = id ? container.ownerDocument.getElementById(id) : null;
+    if (!control || !container.contains(control)) {
+      return; // no control
+    }
+    forwardedClicks.add(e.nativeEvent);
+    control.focus();
+    control.click();
+  };
   const renderLabel = () => {
     const labelContent = hasVisibleLabel ? (0, _jsxRuntime.jsxs)(_jsxRuntime.Fragment, {
       children: [label, isRequired && (0, _jsxRuntime.jsxs)("span", {
@@ -168,9 +198,10 @@ const FormFieldLayout = exports.FormFieldLayout = /*#__PURE__*/(0, _react.forwar
           })
         });
       }
-      return (0, _jsxRuntime.jsx)("span", {
+      return (0, _jsxRuntime.jsx)("label", {
         css: styles?.formFieldLabel,
         id: labelId,
+        htmlFor: id,
         children: labelContent
       });
     } else if (label) {
@@ -183,9 +214,9 @@ const FormFieldLayout = exports.FormFieldLayout = /*#__PURE__*/(0, _react.forwar
           children: label
         });
       }
-      // needs to be wrapped because it needs an `id`
-      return (0, _jsxRuntime.jsx)("div", {
+      return (0, _jsxRuntime.jsx)("label", {
         id: labelId,
+        htmlFor: id,
         style: {
           display: 'contents'
         },
@@ -212,7 +243,10 @@ const FormFieldLayout = exports.FormFieldLayout = /*#__PURE__*/(0, _react.forwar
     children: [renderLabel(), isGroup && renderMessages(), (0, _jsxRuntime.jsx)("span", {
       css: styles?.formFieldChildren,
       ref: handleInputContainerRef,
-      children: children
+      onClick: handleChildrenClick,
+      children: typeof children === 'function' ? children({
+        describedBy
+      }) : children
     }), !isGroup && renderMessages()]
   });
 });

package/lib/FormFieldLayout/v2/styles.js

@@ -96,6 +96,7 @@ const generateStyle = (componentTheme, params, sharedTokens) => {
     fontWeight: componentTheme.fontWeight,
     fontSize: componentTheme.fontSize,
     lineHeight: componentTheme.lineHeight,
+    paddingBottom: hasVisibleMessage ? '0' : componentTheme.gapPrimitives,
     ...(isInlineLayout && {
       margin: '0',
       // when inline add a small padding between the label and the control
@@ -149,8 +150,7 @@ const generateStyle = (componentTheme, params, sharedTokens) => {
       ...labelStyles,
       // NOTE: needs separate groups for `:is()` and `:-webkit-any()` because of css selector group validation (see https://www.w3.org/TR/selectors-3/#grouping)
       '&:is(label)': labelStyles,
-      '&:-webkit-any(label)': labelStyles,
-      paddingBottom: hasVisibleMessage ? '0' : componentTheme.gapPrimitives
+      '&:-webkit-any(label)': labelStyles
     },
     formFieldChildren: {
       label: 'formFieldLayout__children',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instructure/ui-form-field",
-  "version": "11.7.9-snapshot-5",
+  "version": "11.7.10",
   "description": "Form layout components.",
   "author": "Instructure, Inc. Engineering and Product Design",
   "module": "./es/index.js",
@@ -15,21 +15,21 @@
   "license": "MIT",
   "dependencies": {
     "@babel/runtime": "^7.29.7",
-    "@instructure/console": "11.7.9-snapshot-5",
-    "@instructure/emotion": "11.7.9-snapshot-5",
-    "@instructure/shared-types": "11.7.9-snapshot-5",
-    "@instructure/ui-a11y-content": "11.7.9-snapshot-5",
-    "@instructure/ui-a11y-utils": "11.7.9-snapshot-5",
-    "@instructure/ui-grid": "11.7.9-snapshot-5",
-    "@instructure/ui-icons": "11.7.9-snapshot-5",
-    "@instructure/ui-react-utils": "11.7.9-snapshot-5",
-    "@instructure/ui-themes": "11.7.9-snapshot-5",
-    "@instructure/ui-utils": "11.7.9-snapshot-5",
-    "@instructure/uid": "11.7.9-snapshot-5"
+    "@instructure/console": "11.7.10",
+    "@instructure/emotion": "11.7.10",
+    "@instructure/shared-types": "11.7.10",
+    "@instructure/ui-a11y-content": "11.7.10",
+    "@instructure/ui-a11y-utils": "11.7.10",
+    "@instructure/ui-grid": "11.7.10",
+    "@instructure/ui-icons": "11.7.10",
+    "@instructure/ui-react-utils": "11.7.10",
+    "@instructure/ui-themes": "11.7.10",
+    "@instructure/ui-utils": "11.7.10",
+    "@instructure/uid": "11.7.10"
   },
   "devDependencies": {
-    "@instructure/ui-axe-check": "11.7.9-snapshot-5",
-    "@instructure/ui-babel-preset": "11.7.9-snapshot-5",
+    "@instructure/ui-axe-check": "11.7.10",
+    "@instructure/ui-babel-preset": "11.7.10",
     "vitest": "^5.0.0"
   },
   "peerDependencies": {

package/src/FormField/v2/README.md

@@ -5,6 +5,32 @@ describes: FormField
 This is a helper component that is used by most of the custom form
 components. In most cases it shouldn't be used directly.
 
+### Accessibility
+
+`FormField` renders a `<label>` that wraps the label text, and links it to
+the form control via its `for` attribute. Make sure that you mind the following:
+
+- The control needs to have the same `id` as the one passed to `FormField` via `labelId`.
+  you can also use `aria-labelledby` on your control to read the label.
+- Messages aren't part of the control's accessible name. To have screen readers
+  announce them, pass a function as `children`. It receives `{ describedBy }`,
+  the id of the rendered messages (or `undefined` when none are shown), which
+  you add to the control's `aria-describedby`.
+
+```js
+---
+type: code
+---
+<FormField id="email" label="Email" messages={messages}>
+  {({ describedBy }) => (
+    <input id="email" type="email" aria-describedby={describedBy} />
+  )}
+</FormField>
+```
+
+Clicking non-interactive content around the control (e.g. icons or padding)
+focuses and clicks the control, like clicking the label does.
+
 ```js
 ---
 type: example
@@ -30,8 +56,8 @@ type: example
     <TextInput id="_foo124"/>
   </FormField>
   <hr/>
-  <FormField id="_foo121" label={<ScreenReaderContent>hidden text</ScreenReaderContent>} width="400px" layout="stacked">
-    <TextInput id="_foo121" />
+  <FormField id="_foo125" label={<ScreenReaderContent>hidden text</ScreenReaderContent>} width="400px" layout="stacked">
+    <TextInput id="_foo125" />
   </FormField>
   <hr/>
 </div>

package/src/FormField/v2/index.tsx

@@ -68,12 +68,8 @@ class FormField extends Component<FormFieldProps> {
         {...omitProps(this.props, FormField.allowedProps)}
         {...pickProps(this.props, formFieldLayoutAllowedProps)}
         label={this.props.label}
+        id={this.props.id}
         vAlign={this.props.vAlign}
-        as="label"
-        // This makes the control in focus when the label is clicked
-        // This is needed to prevent the wrong element to be focused, e.g.
-        // multi selects Tag-s
-        htmlFor={this.props.id}
         elementRef={this.handleRef}
         margin={this.props.margin}
         isRequired={this.props.isRequired}

package/src/FormField/v2/props.ts

@@ -27,6 +27,7 @@ import React from 'react'
 import type { OtherHTMLAttributes } from '@instructure/shared-types'
 import type { FormMessage } from '../../utils/v1/FormPropTypes'
 import type { Spacing } from '@instructure/emotion'
+import type { FormFieldLayoutChildren } from '../../FormFieldLayout/v2/props'
 
 type FormFieldOwnProps = {
   label: React.ReactNode
@@ -47,11 +48,17 @@ type FormFieldOwnProps = {
    */
   messagesId?: string
   /**
-   * id for the label element, so a single form control can reference just the
-   * label text via `aria-labelledby` (keeping messages out of its accessible name)
+   * `id` for the label/legend element. Useful when the control is not a
+   * [labelable](https://developer.mozilla.org/en-US/docs/Web/HTML/Guides/Content_categories#labelable)
+   * element (e.g. a custom widget), and needs to reference the label via
+   * `aria-labelledby`.
    */
   labelId?: string
-  children?: React.ReactNode
+  /**
+   * The form control. Can be a function that receives `{ describedBy }`, so
+   * the control can reference the messages via `aria-describedby`.
+   */
+  children?: FormFieldLayoutChildren
   inline?: boolean
   layout?: 'stacked' | 'inline'
   labelAlign?: 'start' | 'end'