DropdownWrapper – Once UI

DropdownWrapper is a container component that handles the positioning and state management of dropdown menus. It provides a flexible way to create custom dropdown interfaces with various trigger elements and dropdown contents. It supports keyboard navigation when used with Option components.

Basic usage

A simple dropdown with a button trigger and custom content.

DropdownWrapper

const [isOpen, setIsOpen] = useState(false);
const [selected, setSelected] = useState("");

const options = [
  { label: "Option 1", value: "option1" },
  { label: "Option 2", value: "option2" },
  { label: "Option 3", value: "option3" }
];

const handleSelect = (value: string) => {
  setSelected(value);
  setIsOpen(false);
};

return (
  <DropdownWrapper
    open={isOpen}
    onOpenChange={setIsOpen}
    trigger={
      <Button 
        variant="secondary" 
        suffixIcon="chevronDown"
        onClick={() => setIsOpen(!isOpen)}
      >
        {selected ? options.find(opt => opt.value === selected)?.label : "Select an option"}
      </Button>
    }
    dropdown={
      <Column minWidth={10} padding="4" gap="2">
        {options.map((option) => (
          <Option
            key={option.value}
            label={option.label}
            value={option.value}
            selected={option.value === selected}
            onClick={handleSelect}
          />
        ))}
      </Column>
    }
  />
);

Placement

Control the placement of the dropdown relative to its trigger element.

Placement

const [isOpen, setIsOpen] = useState(false);

return (
<Row horizontal="center">
  <DropdownWrapper
    open={isOpen}
    onOpenChange={setIsOpen}
    placement="top"
    trigger={
      <Button onClick={() => setIsOpen(!isOpen)}>
        Open Upward
      </Button>
    }
    dropdown={
      <Column fillWidth padding="4" gap="2">
        <Option
          label="Top option"
          value="top"
          onClick={() => setIsOpen(false)}
        />
        <Option
          label="Middle option"
          value="middle"
          onClick={() => setIsOpen(false)}
        />
        <Option
          label="Bottom option"
          value="bottom"
          onClick={() => setIsOpen(false)}
        />
      </Column>
    }
  />
</Row>
);

Custom

Control the dimensions of the dropdown menu.

Custom

const [isOpen, setIsOpen] = useState(false);
const [selected, setSelected] = useState("");
const [searchQuery, setSearchQuery] = useState("");

const options = [
  { label: "Apple", value: "apple", description: "Fruit" },
  { label: "Banana", value: "banana", description: "Fruit" },
  { label: "Carrot", value: "carrot", description: "Vegetable" },
  { label: "Broccoli", value: "broccoli", description: "Vegetable" },
  { label: "Orange", value: "orange", description: "Fruit" }
];

const handleSelect = (value: string) => {
  setSelected(value);
  setIsOpen(false);
};

const filteredOptions = options.filter(option => 
  option.label.toLowerCase().includes(searchQuery.toLowerCase())
);

return (
  <DropdownWrapper
    open={isOpen}
    onOpenChange={setIsOpen}
    minHeight={200}
    trigger={
      <Button 
        variant="secondary" 
        suffixIcon="chevronDown"
        onClick={() => setIsOpen(!isOpen)}
      >
        {selected ? options.find(opt => opt.value === selected)?.label : "Search items"}
      </Button>
    }
    dropdown={
      <Column fillWidth minWidth={12}>
        <Column padding="4" fillWidth position="sticky" top="0" background="surface" zIndex={1}>
          <Input
            size="s"
            id="search-dropdown"
            placeholder="Search"
            prefix={<Icon name="search" size="xs" />}
            value={searchQuery}
            onChange={(e) => setSearchQuery(e.target.value)}
            onClick={(e) => e.stopPropagation()}
          />
        </Column>
        <Column fillWidth gap="2" padding="4">
          {filteredOptions.length > 0 ? (
            filteredOptions.map((option) => (
              <Option
                key={option.value}
                label={option.label}
                value={option.value}
                description={option.description}
                selected={option.value === selected}
                onClick={handleSelect}
              />
            ))
          ) : (
            <Flex fillWidth center paddingX="16" paddingY="32">
              <Text>No results found</Text>
            </Flex>
          )}
        </Column>
      </Column>
    }
  />
);

Where it opens

A panel opens on the option marked aria-selected="true", scrolled into view inside the panel, the way a native select opens on the value it is already showing. Option sets that attribute from its selected prop, so a list built from Option needs nothing further. With no selection the panel opens on its first enabled option; a selected option that is disabled is skipped.

A panel that leads with something other than its list — a searchable Select and its query field — opens on that instead.

Button triggers

A Button or IconButton passed as the trigger renders a real <button type="button"> with aria-haspopup and aria-expanded, so the dropdown opens from the keyboard as well as the mouse. There is no need to add type="button" or an empty onClick to make it one. A disabled trigger does not open the dropdown.

API reference

	Type	Default
fillWidth Match the trigger's width.	boolean	false
minWidth Lower bound on the dropdown's width, in rem.	number	—
maxWidth Upper bound on the dropdown's width, in rem.	number	—
minHeight Lower bound on the dropdown's height, in rem.	number	—
placement Which side of the trigger it opens on, and how it aligns.	toprightbottomlefttop-starttop-endright-startright-endbottom-startbottom-endleft-startleft-end	bottom-start
triggerrequired The element that opens the dropdown.	ReactNode	—
dropdownrequired What opens. Usually a Column of Options.	ReactNode	—
selectedOption Value of the Option to mark as current.	string	—
style	React.CSSProperties	—
className	string	—
onSelect Called with the value of the Option that was picked.	(value: string) => void	—
closeAfterClick Close on selection. Turn it off for a multi-select.	boolean	true
handleArrowNavigation Move through options with the arrow keys.	boolean	true
open Controlled open state. Leave it out to let the component manage its own.	boolean	—
onOpenChange Called whenever it opens or closes, controlled or not.	(open: boolean) => void	—
nested Marks a dropdown opened from inside another one.	boolean	false
navigationLayout Whether arrow keys walk a row, a column or a grid.	gridrowcolumn	—
columns Grid width, for a grid navigation layout.	numberstring	8
optionsCount How many options there are, when the component cannot count them itself.	number	—
dropdownId Id for the dropdown element, to reference from a label.	string	—
disableTriggerClick Stop the trigger opening it, when something else does.	boolean	false
onFocusCapture	React.FocusEventHandler<HTMLDivElement>	—
onBlurCapture	React.FocusEventHandler<HTMLDivElement>	—