[joy-ui][Select] Support selection of multiple options

docs/data/joy/components/select/SelectMultiple.js

@@ -0,0 +1,31 @@
+import * as React from 'react';
+import Select from '@mui/joy/Select';
+import Option from '@mui/joy/Option';
+
+export default function SelectMultiple() {
+  const handleChange = (event, newValue) => {
+    console.log(`You have choosen "${newValue}"`);
+  };
+  return (
+    <Select
+      defaultValue={['dog']}
+      multiple
+      onChange={handleChange}
+      sx={{
+        minWidth: '13rem',
+      }}
+      slotProps={{
+        listbox: {
+          sx: {
+            width: '100%',
+          },
+        },
+      }}
+    >
+      <Option value="dog">Dog</Option>
+      <Option value="cat">Cat</Option>
+      <Option value="fish">Fish</Option>
+      <Option value="bird">Bird</Option>
+    </Select>
+  );
+}

docs/data/joy/components/select/SelectMultiple.tsx

@@ -0,0 +1,34 @@
+import * as React from 'react';
+import Select from '@mui/joy/Select';
+import Option from '@mui/joy/Option';
+
+export default function SelectMultiple() {
+  const handleChange = (
+    event: React.SyntheticEvent | null,
+    newValue: Array<string> | null,
+  ) => {
+    console.log(`You have choosen "${newValue}"`);
+  };
+  return (
+    <Select
+      defaultValue={['dog']}
+      multiple
+      onChange={handleChange}
+      sx={{
+        minWidth: '13rem',
+      }}
+      slotProps={{
+        listbox: {
+          sx: {
+            width: '100%',
+          },
+        },
+      }}
+    >
+      <Option value="dog">Dog</Option>
+      <Option value="cat">Cat</Option>
+      <Option value="fish">Fish</Option>
+      <Option value="bird">Bird</Option>
+    </Select>
+  );
+}

docs/data/joy/components/select/SelectMultipleAppearance.js

@@ -0,0 +1,37 @@
+import * as React from 'react';
+import Select from '@mui/joy/Select';
+import Option from '@mui/joy/Option';
+import { Box, Chip } from '@mui/joy';
+
+export default function SelectMultipleAppearance() {
+  return (
+    <Select
+      multiple
+      defaultValue={['dog', 'cat']}
+      renderValue={(selected) => (
+        <Box sx={{ display: 'flex', gap: '0.25rem' }}>
+          {selected.map((selectedOption) => (
+            <Chip variant="outlined" color="success">
+              {selectedOption.label}
+            </Chip>
+          ))}
+        </Box>
+      )}
+      sx={{
+        minWidth: '15rem',
+      }}
+      slotProps={{
+        listbox: {
+          sx: {
+            width: '100%',
+          },
+        },
+      }}
+    >
+      <Option value="dog">Dog</Option>
+      <Option value="cat">Cat</Option>
+      <Option value="fish">Fish</Option>
+      <Option value="bird">Bird</Option>
+    </Select>
+  );
+}

docs/data/joy/components/select/SelectMultipleAppearance.tsx

@@ -0,0 +1,37 @@
+import * as React from 'react';
+import Select from '@mui/joy/Select';
+import Option from '@mui/joy/Option';
+import { Box, Chip } from '@mui/joy';
+
+export default function SelectMultipleAppearance() {
+  return (
+    <Select
+      multiple
+      defaultValue={['dog', 'cat']}
+      renderValue={(selected) => (
+        <Box sx={{ display: 'flex', gap: '0.25rem' }}>
+          {selected.map((selectedOption) => (
+            <Chip variant="outlined" color="success">
+              {selectedOption.label}
+            </Chip>
+          ))}
+        </Box>
+      )}
+      sx={{
+        minWidth: '15rem',
+      }}
+      slotProps={{
+        listbox: {
+          sx: {
+            width: '100%',
+          },
+        },
+      }}
+    >
+      <Option value="dog">Dog</Option>
+      <Option value="cat">Cat</Option>
+      <Option value="fish">Fish</Option>
+      <Option value="bird">Bird</Option>
+    </Select>
+  );
+}

docs/data/joy/components/select/select.md

@@ -123,6 +123,25 @@ const App = () => (
 );
 ```
 
+### Multiple selections
+
+Set the `multiple` prop to let your users select multiple options from the list.
+In contrast with single-selection mode, the options popup doesn't close after an item is selected, which enables users to continue choosing more options.
+
+Note that in multiple selection mode, the `value` prop (and `defaultValue`) is an array.
+
+{{"demo": "SelectMultiple.js"}}
+
+#### Selected value appearance
+
+Use the `renderValue` prop to customize the display of the selected options.
+
+{{"demo": "SelectMultipleAppearance.js"}}
+
+#### Form submission
+
+Show what the value looks like after submitted a form.
+
 ### Listbox
 
 #### Maximum height

docs/pages/joy-ui/api/select.json

@@ -23,6 +23,7 @@
     "indicator": { "type": { "name": "node" } },
     "listboxId": { "type": { "name": "string" } },
     "listboxOpen": { "type": { "name": "bool" } },
+    "multiple": { "type": { "name": "bool" } },
     "name": { "type": { "name": "string" } },
     "onChange": { "type": { "name": "func" } },
     "onClose": { "type": { "name": "func" } },
@@ -113,6 +114,7 @@
       "disabled",
       "expanded",
       "focusVisible",
+      "multiple",
       "popper",
       "sizeLg",
       "sizeMd",

docs/translations/api-docs-joy/select/select.json

@@ -31,6 +31,9 @@
       "description": "<code>id</code> attribute of the listbox element. Also used to derive the <code>id</code> attributes of options."
     },
     "listboxOpen": { "description": "Controls the open state of the select&#39;s listbox." },
+    "multiple": {
+      "description": "If <code>true</code>, selecting multiple values is allowed. This affects the type of the <code>value</code>, <code>defaultValue</code>, and <code>onChange</code> props."
+    },
     "name": {
       "description": "Name of the element. For example used by the server to identify the fields in form submits. If the name is provided, the component will render a hidden input element that can be submitted to a server."
     },
@@ -85,6 +88,9 @@
       "description": "Class name applied to {{nodeName}}.",
       "nodeName": "the listbox slot"
     },
+    "multiple": {
+      "description": "Class name applied to the root slot if <code>multiple=true</code>"
+    },
     "colorPrimary": {
       "description": "Class name applied to {{nodeName}} if {{conditions}}.",
       "nodeName": "the root slot",

packages/mui-joy/src/Select/Select.spec.tsx

@@ -105,40 +105,103 @@ interface Value {
 <Select
   slotProps={{
     root: (ownerState) => {
-      expectType<SelectOwnerState<any>, typeof ownerState>(ownerState);
+      expectType<SelectOwnerState<any, false>, typeof ownerState>(ownerState);
       return {
         'data-testid': 'test',
       };
     },
     button: (ownerState) => {
-      expectType<SelectOwnerState<any>, typeof ownerState>(ownerState);
+      expectType<SelectOwnerState<any, false>, typeof ownerState>(ownerState);
       return {
         'data-testid': 'test',
       };
     },
     startDecorator: (ownerState) => {
-      expectType<SelectOwnerState<any>, typeof ownerState>(ownerState);
+      expectType<SelectOwnerState<any, false>, typeof ownerState>(ownerState);
       return {
         'data-testid': 'test',
       };
     },
     endDecorator: (ownerState) => {
-      expectType<SelectOwnerState<any>, typeof ownerState>(ownerState);
+      expectType<SelectOwnerState<any, false>, typeof ownerState>(ownerState);
       return {
         'data-testid': 'test',
       };
     },
     indicator: (ownerState) => {
-      expectType<SelectOwnerState<any>, typeof ownerState>(ownerState);
+      expectType<SelectOwnerState<any, false>, typeof ownerState>(ownerState);
       return {
         'data-testid': 'test',
       };
     },
     listbox: (ownerState) => {
-      expectType<SelectOwnerState<any>, typeof ownerState>(ownerState);
+      expectType<SelectOwnerState<any, false>, typeof ownerState>(ownerState);
       return {
         'data-testid': 'test',
       };
     },
   }}
 />;
+
+const handleChange = (
+  e: React.MouseEvent | React.KeyboardEvent | React.FocusEvent | null,
+  val: number | null,
+) => {};
+
+const handleMultiChange = (
+  e: React.MouseEvent | React.KeyboardEvent | React.FocusEvent | null,
+  val: number[] | null,
+) => {};
+
+<Select value={10} onChange={handleChange} />;
+<Select<number, true> value={[10]} onChange={handleMultiChange} />;
+<Select<number, 'a', true> value={[10]} component="a" />;
+<Select multiple value={[10]} component="button" />;
+<Select multiple defaultValue={[10]} />;
+<Select multiple value={[10]} />;
+
+<Select
+  value={10}
+  // @ts-expect-error
+  onChange={handleMultiChange}
+/>;
+
+<Select<number, true>
+  value={[10]}
+  // @ts-expect-error
+  onChange={handleChange}
+/>;
+
+<Select
+  defaultValue={10}
+  // @ts-expect-error
+  onChange={handleMultiChange}
+/>;
+
+<Select<number, true>
+  defaultValue={[10]}
+  // @ts-expect-error
+  onChange={handleChange}
+/>;
+<Select value={10} onChange={handleChange} />;
+
+<Select<number, true> onChange={handleMultiChange} value={[10]} />;
+
+<Select defaultValue={10} onChange={handleChange} />;
+
+<Select<number, true> defaultValue={[10]} onChange={handleMultiChange} />;
+
+// @ts-expect-error
+<Select<number, false> value={[10]} />;
+// @ts-expect-error
+<Select<number, false> defaultValue={[10]} />;
+// @ts-expect-error
+<Select multiple defaultValue={10} />;
+// @ts-expect-error
+<Select multiple value={10} />;
+// @ts-expect-error
+<Select multiple value={10} component="button" />;
+// @ts-expect-error
+<Select value={[10]} component="button" />;
+// @ts-expect-error
+<Select value={[10]} />;

packages/mui-joy/src/Select/Select.test.tsx

@@ -646,4 +646,32 @@ describe('Joy <Select />', () => {
     });
     expect(getByRole('combobox', { hidden: true })).to.have.attribute('aria-expanded', 'false');
   });
+
+  describe('prop: multiple', () => {
+    it('renders the selected values (multiple) using the renderValue prop', () => {
+      const { getByRole } = render(
+        <Select
+          multiple
+          defaultValue={[1, 2]}
+          renderValue={(values) => values.map((v) => `${v.label} (${v.value})`).join(', ')}
+        >
+          <Option value={1}>One</Option>
+          <Option value={2}>Two</Option>
+        </Select>,
+      );
+
+      expect(getByRole('combobox')).to.have.text('One (1), Two (2)');
+    });
+
+    it('renders the selected values (multiple) as comma-separated list of labels if renderValue is not provided', () => {
+      const { getByRole } = render(
+        <Select multiple defaultValue={[1, 2]}>
+          <Option value={1}>One</Option>
+          <Option value={2}>Two</Option>
+        </Select>,
+      );
+
+      expect(getByRole('combobox')).to.have.text('One, Two');
+    });
+  });
 });