This kit's options
prop requires an array of objects, each of which will be used as the selectable options within the dropdown. Each option object can support any number of key-value pairs, but each must contain label
and value
.
import React from 'react' import { Dropdown } from 'playbook-ui' const DropdownDefault = (props) => { const options = [ { label: "United States", value: "United States", }, { label: "Canada", value: "Canada", }, { label: "Pakistan", value: "Pakistan", } ]; return ( <div> <Dropdown options={options} /> </div> ) } export default DropdownDefault
The dropdown is built using all of the following subcomponents:
Dropdown.Trigger
is the UI component that users interact with to toggle the dropdown.
Dropdown.Container
is the floating container that wraps the list of dropdown options.
Dropdown.Option
renders options that are passed to the container.
Each of these subcomponents can be altered using global props and/or their respective props. See doc examples below for more information on each.
import React from 'react' import { Dropdown } from 'playbook-ui' const DropdownSubcomponentStructure = (props) => { const options = [ { label: "United States", value: "United States", }, { label: "Canada", value: "Canada", }, { label: "Pakistan", value: "Pakistan", } ]; return ( <div> <Dropdown options={options} > <Dropdown.Trigger/> <Dropdown.Container> {options.map((option) => ( <Dropdown.Option key={option.id} option={option} /> ))} </Dropdown.Container> </Dropdown> </div> ) } export default DropdownSubcomponentStructure
The top-level Dropdown component optionally accepts any string through a label
prop to produce a label above your trigger element.
import React from 'react' import { Dropdown } from 'playbook-ui' const DropdownDefault = (props) => { const options = [ { label: "United States", value: "United States", }, { label: "Canada", value: "Canada", }, { label: "Pakistan", value: "Pakistan", } ]; return ( <div> <Dropdown label="Select a Country" options={options} > {options.map((option) => ( <Dropdown.Option key={option.id} option={option} /> ))} </Dropdown> </div> ) } export default DropdownDefault
Dropdown.Option
subcomponent accepts any child components to customize the options' contents and display. By default, options are Body kit text that is set by the label
value from the option
object.
import React from 'react' import { Dropdown, Icon, Body, FlexItem, Flex } from 'playbook-ui' const DropdownWithCustomOptions = (props) => { const options = [ { label: "United States", value: "United States", areaCode: "+1", icon: "🇺🇸", id: "United-states" }, { label: "Canada", value: "Canada", areaCode: "+1", icon: "🇨🇦", id: "canada" }, { label: "Pakistan", value: "Pakistan", areaCode: "+92", icon: "🇵🇰", id: "pakistan" } ]; return ( <div> <Dropdown options={options} > {options.map((option) => ( <Dropdown.Option key={option.id} option={option} > <Flex align="center" justify="between" > <FlexItem> <Flex> <Icon icon={option.icon} paddingRight="xs" /> <Body text={option.label} /> </Flex> </FlexItem> <FlexItem> <Body color="light" text={option.areaCode} /> </FlexItem> </Flex> </Dropdown.Option> ))} </Dropdown> </div> ) } export default DropdownWithCustomOptions
Optionally utilize customDisplay
on the Dropdown.Trigger
subcomponent to customize its content after an option is selected. The component passed to customDisplay will be rendered to the left of the default text-based display. In this example the Avatar kit is being used.
The placeholder
prop can also be used to customize the placeholder text for the default Dropdown.Trigger
.
The onSelect
prop returns the selected option as an object to be utilized by the dev. In this example we are using the onSelect
to set a state with the selected option and using it to customize the customDisplay
.
import React, { useState } from 'react' import { Dropdown, User, Flex, FlexItem, Badge, Avatar } from 'playbook-ui' const DropdownWithCustomDisplay = (props) => { const [selectedOption, setSelectedOption] = useState(); const options = [ { label: "Jasper Furniss", value: "Jasper Furniss", territory: "PHL", title: "Senior UX Engineer", id: "jasper-furniss", status: "Offline" }, { label: "Ramon Ruiz", value: "Ramon Ruiz", territory: "PHL", title: "Senior UX Designer", id: "ramon-ruiz", status: "Away" }, { label: "Jason Cypret", value: "Jason Cypret", territory: "PHL", title: "VP of User Experience", id: "jason-cypret", status: "Online" }, { label: "Courtney Long", value: "Courtney Long", territory: "PHL", title: "UX Design Mentor", id: "courtney-long", status: "Online" } ]; const CustomDisplay = () => { return ( <> { selectedOption && ( <Avatar name={selectedOption.label} size="xs" /> ) } </> ) }; return ( <div> <Dropdown onSelect={(selectedItem) => setSelectedOption(selectedItem)} options={options} > <Dropdown.Trigger customDisplay={<CustomDisplay/>} placeholder="Select a User" /> {options.map((option) => ( <Dropdown.Option key={option.id} option={option} > <Flex align="center" justify="between" > <FlexItem> <User align="left" avatar name={option.label} orientation="horizontal" territory={option.territory} title={option.title} /> </FlexItem> <FlexItem> <Badge dark rounded text={option.status} variant={`${ option.status === "Offline" ? "neutral" : option.status === "Online" ? "success" : "warning" }`} /> </FlexItem> </Flex> </Dropdown.Option> ))} </Dropdown> </div> ) } export default DropdownWithCustomDisplay
Optionally replace the default trigger's select element by passing child components directly to the Dropdown.Trigger
.
import React, { useState } from 'react' import { Dropdown, Icon, Body, FlexItem, Flex, IconCircle } from 'playbook-ui' const DropdownWithCustomTrigger = (props) => { const [selectedOption, setSelectedOption] = useState(); const options = [ { label: "United States", value: "United States", areaCode: "+1", icon: "🇺🇸", id: "United-states" }, { label: "Canada", value: "Canada", areaCode: "+1", icon: "🇨🇦", id: "canada" }, { label: "Pakistan", value: "Pakistan", areaCode: "+92", icon: "🇵🇰", id: "pakistan" } ]; return ( <div> <Dropdown onSelect={(selectedItem) => setSelectedOption(selectedItem)} options={options} > <Dropdown.Trigger> <div key={selectedOption ? selectedOption.icon : "flag"}> <IconCircle cursor="pointer" icon={selectedOption ? selectedOption.icon : "flag"} variant="royal" /> </div> </Dropdown.Trigger> <Dropdown.Container maxWidth="xs"> {options.map((option) => ( <Dropdown.Option key={option.id} option={option} > <Flex align="center" justify="between" > <FlexItem> <Flex> <Icon icon={option.icon} paddingRight="xs" /> <Body text={option.label} /> </Flex> </FlexItem> <FlexItem> <Body color="light" text={option.areaCode} /> </FlexItem> </Flex> </Dropdown.Option> ))} </Dropdown.Container> </Dropdown> </div> ) } export default DropdownWithCustomTrigger
By default, dropdown option paddingX is set to sm
and paddingY is set to xs
, but this padding can be overridden using our global padding props. In this example we are setting the option padding to sm
all around.
import React from 'react' import { Dropdown } from 'playbook-ui' const DropdownWithCustomPadding = (props) => { const options = [ { label: "United States", value: "United States", areaCode: "+1", icon: "🇺🇸", id: "United-states" }, { label: "Canada", value: "Canada", areaCode: "+1", icon: "🇨🇦", id: "canada" }, { label: "Pakistan", value: "Pakistan", areaCode: "+92", icon: "🇵🇰", id: "pakistan" } ]; return ( <div> <Dropdown options={options} > {options.map((option) => ( <Dropdown.Option key={option.id} option={option} padding="sm" /> ))} </Dropdown> </div> ) } export default DropdownWithCustomPadding
import React, { useState } from 'react' import { Dropdown } from 'playbook-ui' const DropdownError = (props) => { const [selectedOption, setSelectedOption] = useState() const error = selectedOption?.value ? null : "Please make a valid selection" const options = [ { label: "United States", value: "United States", }, { label: "Canada", value: "Canada", }, { label: "Pakistan", value: "Pakistan", } ] return ( <> <Dropdown error={error} onSelect={(selectedItem) => setSelectedOption(selectedItem)} options={options} /> </> ) } export default DropdownError
import React from 'react' import { Dropdown } from 'playbook-ui' const DropdownDefaultValue = (props) => { const options = [ { label: "United States", value: "United States", }, { label: "Canada", value: "Canada", }, { label: "Pakistan", value: "Pakistan", } ]; return ( <> <Dropdown defaultValue={options[2]} options={options} /> </> ) } export default DropdownDefaultValue
import React from 'react' import { Dropdown } from 'playbook-ui' const DropdownBlankSelection = (props) => { const options = [ { label: "United States", value: "United States", }, { label: "Canada", value: "Canada", }, { label: "Pakistan", value: "Pakistan", } ]; return ( <> <Dropdown blankSelection="Select one..." options={options} /> </> ) } export default DropdownBlankSelection