Dropdown
import { CustomDropdown, Dropdown } from '@dr.pogodin/react-utils';
The Dropdown component implements a dropdown input themed using React Themes
library. Under the hood it relies on the native <select>
element,
thus the styling support is somewhat limited, but on the other hand it is
natively integrated with browsers.
For use cases requiring advanced theming (or rendering arbitrary objects
as dropdown options) the library provides CustomDropdown component, which
implements the dropdown from scratch based on the simple <div>
elements.
Both dropdown implementation provide similar API, with just slight changes documented below.
Demo Source Code
import { useState } from 'react';
import { CustomDropdown, Dropdown } from '@dr.pogodin/react-utils';
const SAMPLE_OPTIONS = [{
name: 'Option #1',
value: 'option1',
}, {
name: 'Option #2',
value: 'option2',
}, {
value: 'option3',
},
'option #4',
];
const SAMPLE_OPTIONS_2 = [{
name: (
<div style={{ alignItems: 'center', display: 'flex' }}>
<div
style={{
background: 'red',
borderRadius: 10,
height: 10,
marginRight: 5,
width: 10,
}}
/>
Option #1
</div>
),
value: 'option1',
}, {
name: (
<div style={{ alignItems: 'center', display: 'flex' }}>
<div
style={{
background: 'green',
borderRadius: 10,
height: 10,
marginRight: 5,
width: 10,
}}
/>
Option #2
</div>
),
value: 'option2',
}, {
name: (
<div style={{ alignItems: 'center', display: 'flex' }}>
<div
style={{
background: 'blue',
borderRadius: 10,
height: 10,
marginRight: 5,
width: 10,
}}
/>
Option #3
</div>
),
value: 'option3',
}];
export default function DropdownExample() {
const [value, setValue] = useState();
const [value2, setValue2] = useState();
return (
<div>
<Dropdown
label="Native <Dropdown>"
onChange={(e) => setValue(e.target.value)}
options={SAMPLE_OPTIONS}
value={value}
/>
<br />
<CustomDropdown
label="<CustomDropdown>"
onChange={setValue2}
options={SAMPLE_OPTIONS_2}
value={value2}
/>
</div>
);
}
If current value
does not match any provided (and filtered, if filter
is set)
option, Dropdown will add an extra «invalid» option to represent
current value
. This ensures Dropdown correctly displays such value
when it
is closed, rather than displaying the first valid option, not matching the actual
value
. In this scenario, when Dropdown is opened this «invalid»
option is hidden from the list of valid selections in browsers that support it
(e.g. Chrome), or it is shown as disabled (and is non-selectable) in other
browsers (e.g. Safari). The CSS styling for this hidden «invalid»
option can be modified via the hiddenOption
theme key.
Properties
-
filter
- function - Options filter function. When provided, only those elements ofoptions
list will be used by the dropdown, for which this filter function returns true. -
label
— React.ReactNode — Dropdown label. -
onChange
— function — Selection event handler.For native Dropdown its signature is React.ChangeEventHandler<HTMLSelectElement>, i.e. you want to pass in something like
(e) => setValue(e.target.value)
.For CustomDropdown its singature is just (newValue: number | string) => void, i.e. you want to pass in something like
(v) => setValue(v)
, or just asetValue
setter directly. -
options
— Array<DropdownOption | number | string> — An array of dropdown options. It is fine to intermix DropdownOption and string items within the same option list. For string items the option value and name will be the same. -
testId
— string — This value is assigned to thedata-testid
attribute of the dropdown's underlying<select>
element, to facilitate testing with testing-library. It is optimized out from production builds. -
theme
- DropdownTheme - Ad hoc theme. -
value
— number | string — The currently selected value. -
Other props of themed components.
DropdownOption
Represents a single option inside Dropdown component. It is an object with the following properties:
-
name
- For native Dropdown it should be string.
- For CustomDropdown it can be any React.ReactNode.
In both cases if
name
is omitted, thevalue
is used as the name instead. -
value
— number | string — Option value.
DropdownTheme
See React Themes docs to learn how component theming works. The valid theme keys for Dropdown are:
-
arrow
— Dropdown arrow. -
container
— The root component container, which wraps both the optional label (if any), and the actual dropdown assembly. -
dropdown
— The dropdown assembly, which holds the<select>
element, and a custom arrow. -
hiddenOption
— The "hidden option" element, which is rendered when the current dropdown value is undefined. -
invalid
— The corresponding classes are added to the underlying<select>
element (in addition to the classes corresponding to theselect
key below) if the current dropdown's value does not match any of provided options (and, thus, it is invalid). -
label
— The optional dropdown label. -
option
— Each option element. -
select
— The underlying<select>
element.