Add required prop (#4882)

* Add `required` prop

* Add changeset

* Add braces around `if`

* Extend test cases

* Add `aria-required`

* Remove `requiredMessage` prop

* Remove `requiredMessage` from default props

.changeset/violet-readers-listen.md

@@ -0,0 +1,5 @@
+---
+'react-select': minor
+---
+
+Add `required` prop

packages/react-select/src/Select.tsx

@@ -14,7 +14,7 @@ import { MenuPlacer } from './components/Menu';
 import LiveRegion from './components/LiveRegion';
 
 import { createFilter, FilterOptionOption } from './filters';
-import { DummyInput, ScrollManager } from './internal/index';
+import { DummyInput, ScrollManager, RequiredInput } from './internal/index';
 import { AriaLiveMessages, AriaSelection } from './accessibility/index';
 
 import {
@@ -262,6 +262,8 @@ export interface Props<
   value: PropsValue<Option>;
   /** Sets the form attribute on the input */
   form?: string;
+  /** Marks the value-holding input as required for form validation */
+  required?: boolean;
 }
 
 export const defaultProps = {
@@ -1421,6 +1423,15 @@ export default class Select<
     return shouldHideSelectedOptions(this.props);
   };
 
+  // If the hidden input gets focus through form submit,
+  // redirect focus to focusable input.
+  onValueInputFocus: FocusEventHandler = (e) => {
+    e.preventDefault();
+    e.stopPropagation();
+
+    this.focus();
+  };
+
   // ==============================
   // Keyboard Handlers
   // ==============================
@@ -1574,6 +1585,7 @@ export default class Select<
       tabIndex,
       form,
       menuIsOpen,
+      required,
     } = this.props;
     const { Input } = this.getComponents();
     const { inputIsHidden, ariaSelection } = this.state;
@@ -1590,6 +1602,7 @@ export default class Select<
       'aria-invalid': this.props['aria-invalid'],
       'aria-label': this.props['aria-label'],
       'aria-labelledby': this.props['aria-labelledby'],
+      'aria-required': required,
       role: 'combobox',
       ...(menuIsOpen && {
         'aria-controls': this.getElementId('listbox'),
@@ -1986,11 +1999,15 @@ export default class Select<
     );
   }
   renderFormField() {
-    const { delimiter, isDisabled, isMulti, name } = this.props;
+    const { delimiter, isDisabled, isMulti, name, required } = this.props;
     const { selectValue } = this.state;
 
     if (!name || isDisabled) return;
 
+    if (required && !this.hasValue()) {
+      return <RequiredInput name={name} onFocus={this.onValueInputFocus} />;
+    }
+
     if (isMulti) {
       if (delimiter) {
         const value = selectValue
@@ -2009,7 +2026,7 @@ export default class Select<
               />
             ))
           ) : (
-            <input name={name} type="hidden" />
+            <input name={name} type="hidden" value="" />
           );
 
         return <div>{input}</div>;

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

@@ -3119,3 +3119,43 @@ test('renders with custom theme', () => {
     window.getComputedStyle(firstOption!).getPropertyValue('background-color')
   ).toEqual(primary);
 });
+
+cases(
+  '`required` prop',
+  ({ props = BASIC_PROPS }) => {
+    const components = (value: Option | null | undefined = null) => (
+      <form id="formTest">
+        <Select {...props} required value={value} />
+      </form>
+    );
+
+    const { container, rerender } = render(components());
+
+    expect(
+      container.querySelector<HTMLFormElement>('#formTest')?.checkValidity()
+    ).toEqual(false);
+    rerender(components(props.options[0]));
+    expect(
+      container.querySelector<HTMLFormElement>('#formTest')?.checkValidity()
+    ).toEqual(true);
+  },
+  {
+    'single select > should validate with value': {
+      props: {
+        ...BASIC_PROPS,
+      },
+    },
+    'single select (isSearchable is false) > should validate with value': {
+      props: {
+        ...BASIC_PROPS,
+        isSearchable: false,
+      },
+    },
+    'multi select > should validate with value': {
+      props: {
+        ...BASIC_PROPS,
+        isMulti: true,
+      },
+    },
+  }
+);

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

@@ -475,3 +475,23 @@ cases<KeyboardInteractionOpts>(
       },
   }
 );
+
+test('`required` prop > should validate', () => {
+  const { container } = render(
+    <form id="formTest">
+      <Select {...BASIC_PROPS} menuIsOpen required />
+    </form>
+  );
+
+  expect(
+    container.querySelector<HTMLFormElement>('#formTest')?.checkValidity()
+  ).toEqual(false);
+
+  let selectOption = container.querySelectorAll('div.react-select__option')[3];
+
+  userEvent.click(selectOption);
+
+  expect(
+    container.querySelector<HTMLFormElement>('#formTest')?.checkValidity()
+  ).toEqual(true);
+});

packages/react-select/src/internal/RequiredInput.tsx

@@ -0,0 +1,30 @@
+/** @jsx jsx */
+import { FocusEventHandler, FunctionComponent } from 'react';
+import { jsx } from '@emotion/react';
+
+const RequiredInput: FunctionComponent<{
+  readonly name: string;
+  readonly onFocus: FocusEventHandler<HTMLInputElement>;
+}> = ({ name, onFocus }) => (
+  <input
+    required
+    name={name}
+    tabIndex={-1}
+    onFocus={onFocus}
+    css={{
+      label: 'requiredInput',
+      opacity: 0,
+      pointerEvents: 'none',
+      position: 'absolute',
+      bottom: 0,
+      left: 0,
+      right: 0,
+      width: '100%',
+    }}
+    // Prevent `Switching from uncontrolled to controlled` error
+    value=""
+    onChange={() => {}}
+  />
+);
+
+export default RequiredInput;

packages/react-select/src/internal/index.ts

@@ -1,3 +1,4 @@
 export { default as A11yText } from './A11yText';
 export { default as DummyInput } from './DummyInput';
 export { default as ScrollManager } from './ScrollManager';
+export { default as RequiredInput } from './RequiredInput';