refactor(field): rename labelElementID prop to labelID for naming consistency

cixzhang · cixzhang · commit c219d875de42 · 2026-07-03T04:49:34.000Z
diff --git a/.changeset/field-labelid-naming.md b/.changeset/field-labelid-naming.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[refactor] Rename the Field `labelElementID` prop to `labelID`, matching the `(part)ID` naming convention used by the sibling props (`inputID`, `descriptionID`, `messageID`). The disambiguation between "the id applied to the label element" and `inputID` ("the control the label points at") now lives in the prop JSDoc rather than the name. Also renamed on FieldLabel and updated the RadioList/CheckboxList/InputGroup consumers. No behavior change. (#3343)
+@cixzhang
diff --git a/packages/core/src/CheckboxList/CheckboxList.tsx b/packages/core/src/CheckboxList/CheckboxList.tsx
@@ -151,7 +151,7 @@ export function CheckboxList({
   'data-testid': dataTestId,
 }: CheckboxListProps) {
   const inputID = useId();
-  const labelElementID = useId();
+  const labelID = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
 
@@ -211,7 +211,7 @@ export function CheckboxList({
       isLabelHidden={isLabelHidden}
       description={description}
       inputID={inputID}
-      labelElementID={labelElementID}
+      labelID={labelID}
       isGroupLabel
       descriptionID={description ? descriptionID : undefined}
       isDisabled={isDisabled}
@@ -231,7 +231,7 @@ export function CheckboxList({
       <CheckboxListContext value={contextValue}>
         <div
           role="group"
-          aria-labelledby={labelElementID}
+          aria-labelledby={labelID}
           aria-describedby={
             [
               description ? descriptionID : null,
diff --git a/packages/core/src/Field/Field.test.tsx b/packages/core/src/Field/Field.test.tsx
@@ -109,7 +109,7 @@ describe('Field', () => {
       <Field
         label="Plan"
         inputID="plan-group"
-        labelElementID="plan-label"
+        labelID="plan-label"
         isGroupLabel>
         <div role="radiogroup" aria-labelledby="plan-label" />
       </Field>,
@@ -119,7 +119,7 @@ describe('Field', () => {
     expect(labelEl.tagName).toBe('SPAN');
     expect(labelEl.closest('label')).toBeNull();
     expect(labelEl).not.toHaveAttribute('for');
-    // labelElementID is applied to the label element and referenced by the group.
+    // labelID is applied to the label element and referenced by the group.
     expect(labelEl).toHaveAttribute('id', 'plan-label');
     const group = screen.getByRole('radiogroup', {name: 'Plan'});
     expect(group.getAttribute('aria-labelledby')).toBe(labelEl.id);
diff --git a/packages/core/src/Field/Field.tsx b/packages/core/src/Field/Field.tsx
@@ -101,7 +101,7 @@ export interface FieldProps extends Omit<
   /**
    * ID of the input element this label points AT (used as the label's
    * `htmlFor`). This is the id of the *control*, not of the label element —
-   * see `labelElementID` for the latter.
+   * see `labelID` for the latter.
    */
   inputID: string;
   /**
@@ -110,12 +110,12 @@ export interface FieldProps extends Omit<
    * (radiogroup, checkbox group) references this via `aria-labelledby` to take
    * the label as its accessible name. Pair with `isGroupLabel`.
    */
-  labelElementID?: string;
+  labelID?: string;
   /**
    * When the field wraps a group of controls rather than a single input, set
    * this so the label renders as a non-`<label>` element (a `<span>`): a
    * `<label>` semantically names one control and can't be associated with a
-   * group. Pair with `labelElementID` + `aria-labelledby` on the group.
+   * group. Pair with `labelID` + `aria-labelledby` on the group.
    * @default false
    */
   isGroupLabel?: boolean;
@@ -189,7 +189,7 @@ export function Field({
   isLabelHidden = false,
   description,
   inputID,
-  labelElementID,
+  labelID,
   isGroupLabel = false,
   descriptionID,
   isOptional = false,
@@ -225,7 +225,7 @@ export function Field({
     <FieldLabel
       label={label}
       inputID={inputID}
-      labelElementID={labelElementID}
+      labelID={labelID}
       isGroupLabel={isGroupLabel}
       isLabelHidden={isLabelHidden}
       isDisabled={isDisabled}
diff --git a/packages/core/src/Field/FieldLabel.tsx b/packages/core/src/Field/FieldLabel.tsx
@@ -84,7 +84,7 @@ export interface FieldLabelProps extends BaseProps<HTMLLabelElement> {
   /**
    * ID of the input element this label points AT (rendered as `htmlFor` on the
    * label). This is *not* the id of the label element itself — see
-   * `labelElementID` for that.
+   * `labelID` for that.
    */
   inputID: string;
   /**
@@ -93,14 +93,14 @@ export interface FieldLabelProps extends BaseProps<HTMLLabelElement> {
    * reference this via `aria-labelledby` to take the label as its accessible
    * name.
    */
-  labelElementID?: string;
+  labelID?: string;
   /**
    * When true, the field wraps a *group* of controls (e.g. a radiogroup)
    * rather than a single input. In that case the label is rendered as a
    * `<span>` instead of a `<label>` — a `<label>` semantically names one form
    * control and can't be associated with a group, so it must not be a literal
    * label element. The group takes the label as its name via
-   * `labelElementID` + `aria-labelledby`.
+   * `labelID` + `aria-labelledby`.
    * @default false
    */
   isGroupLabel?: boolean;
@@ -161,7 +161,7 @@ export interface FieldLabelProps extends BaseProps<HTMLLabelElement> {
 export function FieldLabel({
   label,
   inputID,
-  labelElementID,
+  labelID,
   isGroupLabel = false,
   isLabelHidden = false,
   isDisabled = false,
@@ -203,7 +203,7 @@ export function FieldLabel({
     <>
       <LabelElement
         ref={ref}
-        id={labelElementID}
+        id={labelID}
         // `htmlFor` only applies to a real `<label>` associating with a single
         // control; a group label (span) has no `htmlFor`.
         htmlFor={isGroupLabel ? undefined : inputID}
diff --git a/packages/core/src/InputGroup/InputGroup.tsx b/packages/core/src/InputGroup/InputGroup.tsx
@@ -156,7 +156,7 @@ export function InputGroup({
 }: InputGroupProps) {
   const size = useSize(sizeProp, 'md');
   const inputId = useId();
-  const labelElementId = useId();
+  const labelID = useId();
   const statusMessageId = useId();
 
   const contextValue = useMemo(() => ({isInGroup: true as const}), []);
@@ -169,7 +169,7 @@ export function InputGroup({
           isLabelHidden={isLabelHidden}
           description={description}
           inputID={inputId}
-          labelElementID={labelElementId}
+          labelID={labelID}
           isGroupLabel
           isOptional={isOptional}
           isRequired={isRequired}
@@ -188,7 +188,7 @@ export function InputGroup({
           <div
             ref={ref}
             role="group"
-            aria-labelledby={labelElementId}
+            aria-labelledby={labelID}
             data-testid={testId}
             {...rest}
             {...mergeProps(
diff --git a/packages/core/src/RadioList/RadioList.tsx b/packages/core/src/RadioList/RadioList.tsx
@@ -183,7 +183,7 @@ export function RadioList({
 }: RadioListProps) {
   const name = useId();
   const inputID = useId();
-  const labelElementID = useId();
+  const labelID = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
 
@@ -284,7 +284,7 @@ export function RadioList({
       isLabelHidden={isLabelHidden}
       description={description}
       inputID={inputID}
-      labelElementID={labelElementID}
+      labelID={labelID}
       isGroupLabel
       descriptionID={description ? descriptionID : undefined}
       isOptional={isOptional}
@@ -308,7 +308,7 @@ export function RadioList({
       <div
         ref={groupRef}
         role="radiogroup"
-        aria-labelledby={labelElementID}
+        aria-labelledby={labelID}
         onFocus={handleFocus}
         aria-describedby={
           [
