feat: Add aria-describedby prop

.changeset/friendly-pans-buy.md

@@ -0,0 +1,5 @@
+---
+'react-select': patch
+---
+
+Add aria-describedby prop to Select

packages/react-select/src/Select.tsx

@@ -78,7 +78,9 @@ export interface Props<
   IsMulti extends boolean,
   Group extends GroupBase<Option>
 > {
-  /** HTML ID of an element containing an error message related to the input**/
+  /** HTML ID(s) of the element(s) that describe the input. */
+  'aria-describedby'?: AriaAttributes['aria-describedby'];
+  /** HTML ID of an element containing an error message related to the input */
   'aria-errormessage'?: AriaAttributes['aria-errormessage'];
   /** Indicate if the value entered in the field is invalid **/
   'aria-invalid'?: AriaAttributes['aria-invalid'];
@@ -1233,6 +1235,25 @@ export default class Select<
     this.setState({ ariaSelection: { value, ...actionMeta } });
   };
 
+  getAriaDescribedByValue = () => {
+    const { ariaSelection } = this.state;
+    const ariaDescribedByIds = [];
+
+    if (this.hasValue() && ariaSelection?.action === 'initial-input-focus') {
+      ariaDescribedByIds.push(this.getElementId('live-region'));
+    }
+
+    if (!this.hasValue()) {
+      ariaDescribedByIds.push(this.getElementId('placeholder'));
+    }
+
+    if (this.props['aria-describedby'] != null) {
+      ariaDescribedByIds.push(this.props['aria-describedby']);
+    }
+
+    return ariaDescribedByIds.join(' ');
+  };
+
   hasValue() {
     const { selectValue } = this.state;
     return selectValue.length > 0;
@@ -1708,7 +1729,7 @@ export default class Select<
       required,
     } = this.props;
     const { Input } = this.getComponents();
-    const { inputIsHidden, ariaSelection } = this.state;
+    const { inputIsHidden } = this.state;
     const { commonProps } = this;
 
     const id = inputId || this.getElementId('input');
@@ -1734,13 +1755,7 @@ export default class Select<
       ...(!isSearchable && {
         'aria-readonly': true,
       }),
-      ...(this.hasValue()
-        ? ariaSelection?.action === 'initial-input-focus' && {
-            'aria-describedby': this.getElementId('live-region'),
-          }
-        : {
-            'aria-describedby': this.getElementId('placeholder'),
-          }),
+      'aria-describedby': this.getAriaDescribedByValue(),
     };
 
     if (!isSearchable) {

packages/react-select/src/__tests__/Select.test.tsx

@@ -2252,6 +2252,28 @@ cases(
   }
 );
 
+cases(
+  'accessibility > passes through aria-describedby prop',
+  ({ props = { ...BASIC_PROPS, 'aria-describedby': 'testing' } }) => {
+    let { container } = render(<Select {...props} />);
+    expect(
+      container
+        .querySelector('input.react-select__input')!
+        .getAttribute('aria-describedby')
+    ).toContain('testing');
+  },
+  {
+    'single select > should pass aria-describedby prop down to input': {},
+    'multi select > should pass aria-describedby prop down to input': {
+      props: {
+        ...BASIC_PROPS,
+        'aria-describedby': 'testing',
+        isMulti: true,
+      },
+    },
+  }
+);
+
 cases(
   'accessibility > passes through aria-errormessage prop',
   ({ props = { ...BASIC_PROPS, 'aria-errormessage': 'error-message' } }) => {