WUI logo

Select

Allows user to select one or mutilple choices.

version

4.2.0

install

yarn add @welcome-ui/select

usage

import { Select } from '@welcome-ui/select'

About #

It is based on the downshift library.

Default #

function () {
const [value, setValue] = React.useState(null)
const handleChange = (newValue) => {
setValue(newValue)
}
return <Select options={constants.ITEMS} name="welcome" value={value} onChange={handleChange} />
}

With Field #

function () {
const [value, setValue] = React.useState(null)
const handleChange = (newValue) => {
setValue(newValue)
}
return (
<Field label="Social networks" required>
<Select options={constants.ITEMS} name="welcome2" value={value} onChange={handleChange} />
</Field>
)
}

Clearable #

function () {
const [value, setValue] = React.useState('github')
const handleChange = (newValue) => {
setValue(newValue)
}
return (
<Field label="Social networks">
<Select isClearable options={constants.ITEMS} name="welcome3" value={value} onChange={handleChange} />
</Field>
)
}

Multiple values #

Just add the isMultiple prop. Note: to be able to choose multiple values you must pass an array for the value.

function () {
const [value, setValue] = React.useState(['github', 'twitter'])
const handleChange = (newValue) => {
setValue(newValue)
}
return (
<Field label="Social networks">
<Select isMultiple options={constants.ITEMS} name="welcome3" value={value} onChange={handleChange} />
</Field>
)
}

Passing a renderMultiple function allows you to format the selected items below the select.

function () {
const [value, setValue] = React.useState(['github', 'twitter'])
const handleChange = (newValue) => {
setValue(newValue)
}
return (
<Field label="Social networks">
<Select
isMultiple
name="welcome4"
options={constants.ITEMS}
value={value}
onChange={handleChange}
renderMultiple={(selected, handleRemove) => {
return selected.map(option => {
const Icon = option.icon
return (
<Tag
key={option.value}
variant="primary"
onRemove={() => handleRemove(option.value)}
mr="sm"
mt="sm"
size="lg"
>
<Icon mr="sm" />
<Text variant="body3" m="0">
{option.label}
</Text>
</Tag>
)
})
}}
/>
</Field>
)
}

Searchable #

To be able to filter (i.e. search) the results, add the isSearchable prop.

function () {
const [value, setValue] = React.useState(null)
const handleChange = (newValue) => {
setValue(newValue)
}
return (
<Field label="Social networks">
<Select isSearchable options={constants.ITEMS} name="welcome5" value={value} onChange={handleChange} />
</Field>
)
}

Add an icon #

Pass icon to decorate your Select

function () {
const [value, setValue] = React.useState(null)
const handleChange = (newValue) => {
setValue(newValue)
}
return (
<Field label="Social networks">
<Select
icon={<LinkIcon label="Social networks" color="light.100" />}
name="welcome6"
options={constants.ITEMS}
value={value}
onChange={handleChange}
/>
</Field>
)
}

Formatting options #

Passing a renderItem function allows you to format the options in the list.

Note: if you use renderItem with isSearchable or isCreatable the selected item will not be formatted

Note: if you want to format the options and the placeholder, create a dummy value as the first of your options with an empty string as the value (see code below).

function () {
const [value, setValue] = React.useState('github')
const handleChange = (newValue) => {
setValue(newValue)
}
return (
<Field label="Social networks">
<Select
name="welcome7"
options={constants.ITEMS}
value={value}
onChange={handleChange}
renderItem={option => {
const Icon = option.icon
return (
<div style={{ display: 'flex', alignItems: 'center' }}>
<Icon mr="xs" /> <span>{option.label}</span>
</div>
)
}}
/>
</Field>
)
}

Creatable #

You can add items by passing the isCreatable prop. The returned item will be of the shape:

{ value: 'name-to-be-kebab-cased', label: 'Name to be kebab-cased' }

function () {
const [value, setValue] = React.useState(null)
const handleChange = (newValue) => {
setValue(newValue)
}
return (
<Field label="Social networks">
<Select isCreatable options={constants.ITEMS} name="welcome8" value={value} onChange={handleChange} />
</Field>
)
}

Creatable with custom create button #

Passing a renderCreateItem function allows you to format the create button in the list. It is a function and receives the input value as argument

function () {
const [value, setValue] = React.useState(null)
const handleChange = (newValue) => {
setValue(newValue)
}
return (
<Field label="Social networks">
<Select
isCreatable
name="welcome9"
options={constants.ITEMS}
onChange={handleChange}
value={value}
renderCreateItem={value => {
return (
<Box alignItems="center" display="flex">
<AddIcon mr="sm" />
<Text m={0}>
Add <b>{value}</b> as a new social network
</Text>
</Box>
)
}}
/>
</Field>
)
}

Using allowUnselectFromList and disableCloseOnSelect #

These two options combined allows you, for example, to build a filter dropdown with checkboxes on each items.

function () {
const [value, setValue] = React.useState(null)
const handleChange = (newValue) => {
setValue(newValue)
}
return (
<Field label="Filters">
<Select
icon={<LinkIcon label="Social networks" color="light.100" />}
isMultiple
isSearchable
options={constants.ITEMS}
name="welcome10"
allowUnselectFromList
disableCloseOnSelect
onChange={handleChange}
value={value}
renderItem={(item, selected) => {
return (
<Box display="flex" justifyContent="space-between">
{item.label}
<Box>
<Checkbox type="checkbox" checked={selected} />
</Box>
</Box>
)
}}
/>
</Field>
)
}

Combining props #

You can pass any combination of the props above. For example below, we have a Select that allows you to search the options, choose multiple options, and create new options.

function () {
const [value, setValue] = React.useState(['github', 'twitter'])
const handleChange = (newValue) => {
setValue(newValue)
}
return (
<Field label="Social networks">
<Select
icon={<LinkIcon label="Social networks" color="light.100" />}
isCreatable
isMultiple
isSearchable
options={constants.ITEMS}
name="welcome11"
value={value}
onChange={handleChange}
/>
</Field>
)
}

With option groups #

To use option groups, you must provide two additional props: groupsEnabled that allow nested options and renderGroupHeader that renders the header of a specific group

function () {
const [value, setValue] = React.useState(['github', 'twitter'])
const handleChange = (newValue) => {
setValue(newValue)
}
return (
<Field label="Social networks">
<Select
options={constants.OPT_GROUP_ITEMS}
name="welcome12"
groupsEnabled
onChange={handleChange}
value={value}
renderGroupHeader={({ label, options }) => (
<Box p="xxs">
<Box display="flex" justifyContent="space-between" alignItems="center">
<Text variant="body3" m="0">
{label}
</Text>
<Tag>{options.length}</Tag>
</Box>
{options.length === 0 && <Text variant="body4">No results found</Text>}
</Box>
)}
/>
</Field>
)
}

Properties #

NameType(s)DefaultRequired
autoComplete
string

We need to add `autoComplete` off to avoid select UI issues when is an input

off
autoFocus
Boolean
disabled
Boolean
icon
string
Element
id
string
isClearable
Boolean
isCreatable
Boolean
isMultiple
Boolean
isSearchable
Boolean
options
Options
name
string
onBlur
() => void
onClick
(event: MouseEvent<HTMLElement, MouseEvent>) => void
onChange
(value: OptionValue | OptionValue[], event?: CreateEvent) => void
onCreate
(option: string, event: CreateEvent) => void
onFocus
() => void
placeholder
string
Choose from…
renderCreateItem
(inputValue: SelectValue) => void
(inputValue: string) => `Create "${inputValue}"`
renderItem
(item: unknown, isItemSelected?: boolean) => string | ReactElement<any, string | JSXElementConstructor<any>>
(item: Option): string => (item ? item.label : EMPTY_STRING)
renderMultiple
(values: Option[], handleRemove: (value: string) => void) => ReactElement<any, string | JSXElementConstructor<any>>
value
string
number
Option
string[]
(string | number | Option)[]
allowUnselectFromList
Boolean
disableCloseOnSelect
Boolean
groupsEnabled
Boolean
renderGroupHeader
(option: OptionGroup) => void
size
"sm"
"md"
"lg"
lg
variant
"error"
"focused"
"info"
"success"
"warning"

Packages #

Dependencies #
Peer dependencies #

Previous

Search