MultiSelect
MultiSelect components are used for collecting user provided information from a list of options.
| Install | yarn add @diallink-corp/convergo-react-multiselect |
|---|---|
| Version | 4.1.2 |
| Usage | import {MultiSelect} from '@diallink-corp/convergo-react-multiselect' |
Static Collection
The MultiSelect component can either render static or dynamic collections of data. For simple multiselect components that need to render a list of pre-defined data a static collection should be used. Static collections cannot be changed over time.
<MultiSelect label='What is your favorite fruit?'>
<Item key='apples'>Apples</Item>
<Item key='bananas'>Bananas</Item>
<Item key='grapes'>Grapes</Item>
<Item key='oranges'>Oranges</Item>
</MultiSelect><MultiSelect label='What is your favorite fruit?'>
<Item key='apples'>Apples</Item>
<Item key='bananas'>Bananas</Item>
<Item key='grapes'>Grapes</Item>
<Item key='oranges'>Oranges</Item>
</MultiSelect><MultiSelect label="What is your favorite fruit?">
<Item key="apples">
Apples
</Item>
<Item key="bananas">
Bananas
</Item>
<Item key="grapes">
Grapes
</Item>
<Item key="oranges">
Oranges
</Item>
</MultiSelect>Dynamic Collection
For data that is non-static, such as data fetched from a backend, the MultiSelect component supports dynamic collections. Dynamic collections support adding, updating and removing of the data that is being rendered.
function Example() {
const [fruits, setFruits] = useState([
{id: 1, name: 'Apples'},
{id: 2, name: 'Bananas'},
{id: 3, name: 'Grapes'},
{id: 4, name: 'Oranges'}
]);
return (
<MultiSelect label='What is your favorite fruit?' items={fruits}>
{(item) => <Item key={item.id}>{item.name}</Item>}
</MultiSelect>
);
}function Example() {
const [fruits, setFruits] = useState([
{ id: 1, name: 'Apples' },
{ id: 2, name: 'Bananas' },
{ id: 3, name: 'Grapes' },
{ id: 4, name: 'Oranges' }
]);
return (
<MultiSelect
label="What is your favorite fruit?"
items={fruits}
>
{(item) => <Item key={item.id}>{item.name}</Item>}
</MultiSelect>
);
}
function Example() {
const [
fruits,
setFruits
] = useState([
{
id: 1,
name: 'Apples'
},
{
id: 2,
name: 'Bananas'
},
{
id: 3,
name: 'Grapes'
},
{
id: 4,
name: 'Oranges'
}
]);
return (
<MultiSelect
label="What is your favorite fruit?"
items={fruits}
>
{(item) => (
<Item
key={item.id}
>
{item.name}
</Item>
)}
</MultiSelect>
);
}
Asynchronous Fetching
The Select component supports asynchronous fetching of data via the onLoadMoreItems prop. The select
component uses its built-in infinite scrolling to achieve this. This means that when the user reaches
the bottom of the list, the component will automatically load more data. If you provide an isLoading
prop, the Select component will show a Spinner component, to indicate to the user, that more data is
being fetched.
function Example() {
const list = useAsyncListState({
async loadItems({ cursor, signal }) {
const response = await fetch(
cursor || 'https://pokeapi.co/api/v2/pokemon',
{ signal }
);
const { results, next } = await response.json();
return { items: results, cursor: next };
}
});
return (
<MultiSelect
label="What is your favorite pokemon?"
items={list.items}
isLoading={list.isLoading}
onLoadMoreItems={list.loadMoreItems}
>
{(item) => <Item key={item.name}>{item.name}</Item>}
</MultiSelect>
);
}
function Example() {
const list = useAsyncListState({
async loadItems({ cursor, signal }) {
const response = await fetch(
cursor || 'https://pokeapi.co/api/v2/pokemon',
{ signal }
);
const { results, next } = await response.json();
return { items: results, cursor: next };
}
});
return (
<MultiSelect
label="What is your favorite pokemon?"
items={list.items}
isLoading={list.isLoading}
onLoadMoreItems={list.loadMoreItems}
>
{(item) => <Item key={item.name}>{item.name}</Item>}
</MultiSelect>
);
}
function Example() {
const list =
useAsyncListState({
async loadItems(
{
cursor,
signal
}
) {
const response =
await fetch(
cursor ||
'https://pokeapi.co/api/v2/pokemon',
{ signal }
);
const {
results,
next
} =
await response
.json();
return {
items: results,
cursor: next
};
}
});
return (
<MultiSelect
label="What is your favorite pokemon?"
items={list.items}
isLoading={list
.isLoading}
onLoadMoreItems={list
.loadMoreItems}
>
{(item) => (
<Item
key={item.name}
>
{item.name}
</Item>
)}
</MultiSelect>
);
}
Uncontrolled Value
By default, the Select component handles its selection uncontrolled. In the uncontrolled variant you can
pass in a defaultSelectedKey to select a value by default. The key that is being referenced here is the
value that is passed to the Item component as a key prop, so in this case item.name.
function Example() {
const fruits = [
{ id: 1, name: 'Apples' },
{ id: 2, name: 'Bananas' },
{ id: 3, name: 'Grapes' },
{ id: 4, name: 'Oranges' }
];
return (
<MultiSelect
label="What is your favorite fruit?"
items={fruits}
defaultSelectedKeys={['Grapes']}
>
{(item) => <Item key={item.name}>{item.name}</Item>}
</MultiSelect>
);
}
function Example() {
const fruits = [
{ id: 1, name: 'Apples' },
{ id: 2, name: 'Bananas' },
{ id: 3, name: 'Grapes' },
{ id: 4, name: 'Oranges' }
];
return (
<MultiSelect
label="What is your favorite fruit?"
items={fruits}
defaultSelectedKeys={['Grapes']}
>
{(item) => <Item key={item.name}>{item.name}</Item>}
</MultiSelect>
);
}
function Example() {
const fruits = [
{
id: 1,
name: 'Apples'
},
{
id: 2,
name: 'Bananas'
},
{
id: 3,
name: 'Grapes'
},
{
id: 4,
name: 'Oranges'
}
];
return (
<MultiSelect
label="What is your favorite fruit?"
items={fruits}
defaultSelectedKeys={[
'Grapes'
]}
>
{(item) => (
<Item
key={item.name}
>
{item.name}
</Item>
)}
</MultiSelect>
);
}
Controlled Value
The use the controlled selection variant, you can use the selectedKeys and onSelectionChange props together.
function Example() {
const fruits = [
{id: 1, name: 'Apples'},
{id: 2, name: 'Bananas'},
{id: 3, name: 'Grapes'},
{id: 4, name: 'Oranges'}
];
const [keys, setKeys] = useState(['Bananas']);
return (
<MultiSelect
label='What is your favorite fruit?'
items={fruits}
selectedKeys={keys}
onSelectionChange={setKeys}
>
{(item) => <Item key={item.name}>{item.name}</Item>}
</MultiSelect>
);
}function Example() {
const fruits = [
{id: 1, name: 'Apples'},
{id: 2, name: 'Bananas'},
{id: 3, name: 'Grapes'},
{id: 4, name: 'Oranges'}
];
const [keys, setKeys] = useState(['Bananas']);
return (
<MultiSelect
label='What is your favorite fruit?'
items={fruits}
selectedKeys={keys}
onSelectionChange={setKeys}
>
{(item) => <Item key={item.name}>{item.name}</Item>}
</MultiSelect>
);
}function Example() {
const fruits = [
{
id: 1,
name: 'Apples'
},
{
id: 2,
name: 'Bananas'
},
{
id: 3,
name: 'Grapes'
},
{
id: 4,
name: 'Oranges'
}
];
const [keys, setKeys] =
useState([
'Bananas'
]);
return (
<MultiSelect
label="What is your favorite fruit?"
items={fruits}
selectedKeys={keys}
onSelectionChange={setKeys}
>
{(item) => (
<Item
key={item.name}
>
{item.name}
</Item>
)}
</MultiSelect>
);
}
Static Sections
To group items by sections you can wrap the items in a Section component.
<MultiSelect label='What is your favorite fruit?'>
<Section title='Category A'>
<Item key='apples'>Apples</Item>
<Item key='bananas'>Bananas</Item>
</Section>
<Section title='Category B'>
<Item key='grapes'>Grapes</Item>
<Item key='oranges'>Oranges</Item>
</Section>
</MultiSelect><MultiSelect label='What is your favorite fruit?'>
<Section title='Category A'>
<Item key='apples'>Apples</Item>
<Item key='bananas'>Bananas</Item>
</Section>
<Section title='Category B'>
<Item key='grapes'>Grapes</Item>
<Item key='oranges'>Oranges</Item>
</Section>
</MultiSelect><MultiSelect label="What is your favorite fruit?">
<Section title="Category A">
<Item key="apples">
Apples
</Item>
<Item key="bananas">
Bananas
</Item>
</Section>
<Section title="Category B">
<Item key="grapes">
Grapes
</Item>
<Item key="oranges">
Oranges
</Item>
</Section>
</MultiSelect>Dynamic Sections
To render a group of sections dynamically you can create them from a hierarchical data structure.
function Example() {
const fruits = [
{
title: 'Category A',
items: [
{id: 1, name: 'Apples'},
{id: 2, name: 'Bananas'}
]
},
{
title: 'Category B',
items: [
{id: 3, name: 'Grapes'},
{id: 4, name: 'Oranges'}
]
}
];
return (
<MultiSelect label='What is your favorite fruit?' items={fruits}>
{(section) => (
<Section title={section.title} items={section.items}>
{(item) => <Item key={item.name}>{item.name}</Item>}
</Section>
)}
</MultiSelect>
);
}function Example() {
const fruits = [
{
title: 'Category A',
items: [
{ id: 1, name: 'Apples' },
{ id: 2, name: 'Bananas' }
]
},
{
title: 'Category B',
items: [
{ id: 3, name: 'Grapes' },
{ id: 4, name: 'Oranges' }
]
}
];
return (
<MultiSelect
label="What is your favorite fruit?"
items={fruits}
>
{(section) => (
<Section
title={section.title}
items={section.items}
>
{(item) => (
<Item key={item.name}>{item.name}</Item>
)}
</Section>
)}
</MultiSelect>
);
}
function Example() {
const fruits = [
{
title:
'Category A',
items: [
{
id: 1,
name: 'Apples'
},
{
id: 2,
name: 'Bananas'
}
]
},
{
title:
'Category B',
items: [
{
id: 3,
name: 'Grapes'
},
{
id: 4,
name: 'Oranges'
}
]
}
];
return (
<MultiSelect
label="What is your favorite fruit?"
items={fruits}
>
{(section) => (
<Section
title={section
.title}
items={section
.items}
>
{(item) => (
<Item
key={item
.name}
>
{item.name}
</Item>
)}
</Section>
)}
</MultiSelect>
);
}
Required
To indicate to the user that the Select is required you can use the isRequired prop.
<MultiSelect label='What is your favorite fruit?' isRequired>
<Item key='apples'>Apples</Item>
<Item key='bananas'>Bananas</Item>
<Item key='grapes'>Grapes</Item>
<Item key='oranges'>Oranges</Item>
</MultiSelect><MultiSelect
label="What is your favorite fruit?"
isRequired
>
<Item key="apples">Apples</Item>
<Item key="bananas">Bananas</Item>
<Item key="grapes">Grapes</Item>
<Item key="oranges">Oranges</Item>
</MultiSelect><MultiSelect
label="What is your favorite fruit?"
isRequired
>
<Item key="apples">
Apples
</Item>
<Item key="bananas">
Bananas
</Item>
<Item key="grapes">
Grapes
</Item>
<Item key="oranges">
Oranges
</Item>
</MultiSelect>Validation
The Select component has built-in accessible validation support. To indicate whether the field is valid or not
you can use the errorMessage prop.
function Example() {
const [value, setValue] = useState();
return (
<MultiSelect
label='What is your favorite fruit?'
isRequired
errorMessage={!value && 'This field is required.'}
selectedKeys={value}
onSelectionChange={setValue}
>
<Item key='apples'>Apples</Item>
<Item key='bananas'>Bananas</Item>
<Item key='grapes'>Grapes</Item>
<Item key='oranges'>Oranges</Item>
</MultiSelect>
);
}function Example() {
const [value, setValue] = useState();
return (
<MultiSelect
label='What is your favorite fruit?'
isRequired
errorMessage={!value && 'This field is required.'}
selectedKeys={value}
onSelectionChange={setValue}
>
<Item key='apples'>Apples</Item>
<Item key='bananas'>Bananas</Item>
<Item key='grapes'>Grapes</Item>
<Item key='oranges'>Oranges</Item>
</MultiSelect>
);
}function Example() {
const [
value,
setValue
] = useState();
return (
<MultiSelect
label="What is your favorite fruit?"
isRequired
errorMessage={!value &&
'This field is required.'}
selectedKeys={value}
onSelectionChange={setValue}
>
<Item key="apples">
Apples
</Item>
<Item key="bananas">
Bananas
</Item>
<Item key="grapes">
Grapes
</Item>
<Item key="oranges">
Oranges
</Item>
</MultiSelect>
);
}
Description
To give further instructions or more verbose examples to the user about a Select you can provide a description prop.
Avoid using error like tone of voice of the message. If an errorMessage prop is provided it will replace the description.
<MultiSelect
label="What is your favorite fruit?"
description="Test description"
>
<Item key="apples">Apples</Item>
<Item key="bananas">Bananas</Item>
<Item key="grapes">Grapes</Item>
<Item key="oranges">Oranges</Item>
</MultiSelect><MultiSelect
label="What is your favorite fruit?"
description="Test description"
>
<Item key="apples">Apples</Item>
<Item key="bananas">Bananas</Item>
<Item key="grapes">Grapes</Item>
<Item key="oranges">Oranges</Item>
</MultiSelect><MultiSelect
label="What is your favorite fruit?"
description="Test description"
>
<Item key="apples">
Apples
</Item>
<Item key="bananas">
Bananas
</Item>
<Item key="grapes">
Grapes
</Item>
<Item key="oranges">
Oranges
</Item>
</MultiSelect>Contextual Help
To offer the user contextual help, the MultiSelect supports passing a contextualHelp prop, that accepts a ReactNode.
<MultiSelect
label='What is your favorite fruit?'
contextualHelp={(
<ContextualHelp variant="info">
<Header>
<Heading>Lorem Ipsum</Heading>
</Header>
<Content>
<Text>
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
</Text>
</Content>
</ContextualHelp>
)}
>
<Item key='apples'>Apples</Item>
<Item key='bananas'>Bananas</Item>
<Item key='grapes'>Grapes</Item>
<Item key='oranges'>Oranges</Item>
</MultiSelect><MultiSelect
label="What is your favorite fruit?"
contextualHelp={
<ContextualHelp variant="info">
<Header>
<Heading>Lorem Ipsum</Heading>
</Header>
<Content>
<Text>
Lorem ipsum dolor sit amet, consectetur
adipiscing elit.
</Text>
</Content>
</ContextualHelp>
}
>
<Item key="apples">Apples</Item>
<Item key="bananas">Bananas</Item>
<Item key="grapes">Grapes</Item>
<Item key="oranges">Oranges</Item>
</MultiSelect><MultiSelect
label="What is your favorite fruit?"
contextualHelp={
<ContextualHelp variant="info">
<Header>
<Heading>
Lorem Ipsum
</Heading>
</Header>
<Content>
<Text>
Lorem ipsum
dolor sit
amet,
consectetur
adipiscing
elit.
</Text>
</Content>
</ContextualHelp>
}
>
<Item key="apples">
Apples
</Item>
<Item key="bananas">
Bananas
</Item>
<Item key="grapes">
Grapes
</Item>
<Item key="oranges">
Oranges
</Item>
</MultiSelect>Disabled
The Select component can be disabled via the isDisabled prop.
<MultiSelect label='What is your favorite fruit?' isDisabled>
<Item key='apples'>Apples</Item>
<Item key='bananas'>Bananas</Item>
<Item key='grapes'>Grapes</Item>
<Item key='oranges'>Oranges</Item>
</MultiSelect><MultiSelect
label="What is your favorite fruit?"
isDisabled
>
<Item key="apples">Apples</Item>
<Item key="bananas">Bananas</Item>
<Item key="grapes">Grapes</Item>
<Item key="oranges">Oranges</Item>
</MultiSelect><MultiSelect
label="What is your favorite fruit?"
isDisabled
>
<Item key="apples">
Apples
</Item>
<Item key="bananas">
Bananas
</Item>
<Item key="grapes">
Grapes
</Item>
<Item key="oranges">
Oranges
</Item>
</MultiSelect>Read Only
The Select component can be marked as read only via the isReadOnly prop.
<MultiSelect label='What is your favorite fruit?' isReadOnly>
<Item key='apples'>Apples</Item>
<Item key='bananas'>Bananas</Item>
<Item key='grapes'>Grapes</Item>
<Item key='oranges'>Oranges</Item>
</MultiSelect><MultiSelect
label="What is your favorite fruit?"
isReadOnly
>
<Item key="apples">Apples</Item>
<Item key="bananas">Bananas</Item>
<Item key="grapes">Grapes</Item>
<Item key="oranges">Oranges</Item>
</MultiSelect><MultiSelect
label="What is your favorite fruit?"
isReadOnly
>
<Item key="apples">
Apples
</Item>
<Item key="bananas">
Bananas
</Item>
<Item key="grapes">
Grapes
</Item>
<Item key="oranges">
Oranges
</Item>
</MultiSelect>Menu Direction
By default, the menu of The Select component opens to the bottom. If the window does not offer enough
space to fully open the menu, it automatically opens it to the top. However, you can control this behaviour
yourself via the placement prop.
<MultiSelect label='What is your favorite fruit?' placement='top'>
<Item key='apples'>Apples</Item>
<Item key='bananas'>Bananas</Item>
<Item key='grapes'>Grapes</Item>
<Item key='oranges'>Oranges</Item>
</MultiSelect><MultiSelect
label="What is your favorite fruit?"
placement="top"
>
<Item key="apples">Apples</Item>
<Item key="bananas">Bananas</Item>
<Item key="grapes">Grapes</Item>
<Item key="oranges">Oranges</Item>
</MultiSelect><MultiSelect
label="What is your favorite fruit?"
placement="top"
>
<Item key="apples">
Apples
</Item>
<Item key="bananas">
Bananas
</Item>
<Item key="grapes">
Grapes
</Item>
<Item key="oranges">
Oranges
</Item>
</MultiSelect>Menu Alignment
The menu is by default aligned to the start of the input component. If the content of the menu is longer
than the input that shows the value of The Select component, the menu will outgrow the end of the input.
However, this behaviour can be reversed with the placement prop.
<MultiSelect label='What is your favorite fruit?' placement='top end'>
<Item key='apples'>Apples</Item>
<Item key='bananas'>Bananas</Item>
<Item key='grapes'>Grapes</Item>
<Item key='oranges'>Oranges</Item>
</MultiSelect><MultiSelect
label="What is your favorite fruit?"
placement="top end"
>
<Item key="apples">Apples</Item>
<Item key="bananas">Bananas</Item>
<Item key="grapes">Grapes</Item>
<Item key="oranges">Oranges</Item>
</MultiSelect><MultiSelect
label="What is your favorite fruit?"
placement="top end"
>
<Item key="apples">
Apples
</Item>
<Item key="bananas">
Bananas
</Item>
<Item key="grapes">
Grapes
</Item>
<Item key="oranges">
Oranges
</Item>
</MultiSelect>Labeling
A Select component should be labeled with a visual text through the label prop. If the Select does not
include a textual label, an aria-label or aria-labelledby prop need to be provided to support assistive
technology such as screen readers.
<MultiSelect label='What is your favorite fruit?'>
<Item key='apples'>Apples</Item>
<Item key='bananas'>Bananas</Item>
<Item key='grapes'>Grapes</Item>
<Item key='oranges'>Oranges</Item>
</MultiSelect><MultiSelect label='What is your favorite fruit?'>
<Item key='apples'>Apples</Item>
<Item key='bananas'>Bananas</Item>
<Item key='grapes'>Grapes</Item>
<Item key='oranges'>Oranges</Item>
</MultiSelect><MultiSelect label="What is your favorite fruit?">
<Item key="apples">
Apples
</Item>
<Item key="bananas">
Bananas
</Item>
<Item key="grapes">
Grapes
</Item>
<Item key="oranges">
Oranges
</Item>
</MultiSelect>Label Alignment
For languages that are read left-to-right (LTR), such as English, the label of The Select component is displayed
on the left side of the input. For right-to-left (RTL) languages, such as Arabic, this is flipped. You can control
the position of the label through the labelPlacement prop.
<MultiSelect label="What is your favorite fruit?" labelPlacement="top end">
<Item key="apples">Apples</Item>
<Item key="bananas">Bananas</Item>
<Item key="grapes">Grapes</Item>
<Item key="oranges">Oranges</Item>
</MultiSelect><MultiSelect
label="What is your favorite fruit?"
labelPlacement="top end"
>
<Item key="apples">Apples</Item>
<Item key="bananas">Bananas</Item>
<Item key="grapes">Grapes</Item>
<Item key="oranges">Oranges</Item>
</MultiSelect><MultiSelect
label="What is your favorite fruit?"
labelPlacement="top end"
>
<Item key="apples">
Apples
</Item>
<Item key="bananas">
Bananas
</Item>
<Item key="grapes">
Grapes
</Item>
<Item key="oranges">
Oranges
</Item>
</MultiSelect>Label Position
By default, the label of The Select component is displayed above its input. With the labelPlacement prop
this placement can be adjusted to be on the side of the input.
<MultiSelect label="What is your favorite fruit?" labelPlacement="side end">
<Item key="apples">Apples</Item>
<Item key="bananas">Bananas</Item>
<Item key="grapes">Grapes</Item>
<Item key="oranges">Oranges</Item>
</MultiSelect><MultiSelect
label="What is your favorite fruit?"
labelPlacement="side end"
>
<Item key="apples">Apples</Item>
<Item key="bananas">Bananas</Item>
<Item key="grapes">Grapes</Item>
<Item key="oranges">Oranges</Item>
</MultiSelect><MultiSelect
label="What is your favorite fruit?"
labelPlacement="side end"
>
<Item key="apples">
Apples
</Item>
<Item key="bananas">
Bananas
</Item>
<Item key="grapes">
Grapes
</Item>
<Item key="oranges">
Oranges
</Item>
</MultiSelect>Controlled Menu State
The open state of the menu can be controlled via the isOpen prop.
function Example() {
const [isOpen, setOpen] = useState(false);
const handleOpenChange = () => {
setOpen((prevOpen) => !prevOpen);
};
return (
<MultiSelect
label="What is your favorite fruit?"
isOpen={isOpen}
onOpenChange={handleOpenChange}
>
<Item key="apples">Apples</Item>
<Item key="bananas">Bananas</Item>
<Item key="grapes">Grapes</Item>
<Item key="oranges">Oranges</Item>
</MultiSelect>
);
}
function Example() {
const [isOpen, setOpen] = useState(false);
const handleOpenChange = () => {
setOpen((prevOpen) => !prevOpen);
};
return (
<MultiSelect
label="What is your favorite fruit?"
isOpen={isOpen}
onOpenChange={handleOpenChange}
>
<Item key="apples">Apples</Item>
<Item key="bananas">Bananas</Item>
<Item key="grapes">Grapes</Item>
<Item key="oranges">Oranges</Item>
</MultiSelect>
);
}
function Example() {
const [
isOpen,
setOpen
] = useState(false);
const handleOpenChange =
() => {
setOpen((
prevOpen
) => !prevOpen);
};
return (
<MultiSelect
label="What is your favorite fruit?"
isOpen={isOpen}
onOpenChange={handleOpenChange}
>
<Item key="apples">
Apples
</Item>
<Item key="bananas">
Bananas
</Item>
<Item key="grapes">
Grapes
</Item>
<Item key="oranges">
Oranges
</Item>
</MultiSelect>
);
}
Accessibility
For enhanced mobile device accessibility, the Select component exchanges the default Overlay component to a Tray component. For more details on this component, please consult the Tray component docs.
In order to support internationalization, provide a localized string to the label or aria-label prop.