Dropdown React-only
Open in Storybook Open in Figma
Dropdown is an overlay that attaches to a toggle and drops from it.
Toggle
Every Dropdown needs a toggle. It can be attached to other GDS components or to the DropdownToggle component.
DropdownToggle is handy since it includes a caret animation that reacts to the Dropdown state. It supports the same variants and sizes as Button.
Content overlay
When the Dropdown is opened, the content is rendered in an overlay.
The overlay normally renders a small arrow pointing to the toggle, but this can be prevented. The overlay can also be unpadded when necessary.
Rules For Developers
- There are many props for controlling the toggle triggers:
toggleOnClick,toggleWithSpace,toggleWithEnter,closeWithTab,openOnFocus,openOnKeyDown. They are useful when used with complex toggles, use them only with a good reason. - It is possible to accelerate the animations with the
quickprop - By default Dropdowns close on outside scroll. The motivation here is to align to the browser behaviour of
<select>, although even that isn’t consistent. There are however times when you might want to override it. For example when you have a long menu that the user scrolls through furiously. When they reach the very end and continue scrolling, they might scroll the page and close the Dropdown. You can prevent this situation withcloseOnScrollprop. Use with caution, since when the user scrolls a page with such Dropdowns, they may appear to fly over elements you don’t expect them to thanks to their high z-indices.
Positioning
The overlay decides to drop downwards or upwards automatically, based on the position within the browser window. Naturally, it prefers to drop downwards when possible. You may test the positioning behaviour in this Playroom demo.
The horizontal alignment is configurable. You can choose to align the overlay to the left or right side (or to the centre) of the toggle. This also affects the position of the overlay arrow, when used.
However, satisfying the alignment is not always possible. Imagine having a Dropdown with a short DropdownToggle that drops wide content in the overlay. Now imagine setting the overlay to align to the right side of the toggle and positioning it to the left side of the window. The overlay would have not enough place to drop! In this and other similar cases the overlay will override the alignment to make its content visible.
Another option is to align the overlay to the toggle. This makes it the same width, similar to Select.
Height
The overlay has a default maximum height of 350px, after which it becomes scrollable. Use the maxHeight prop to adjust this. Keep in mind that a custom-sized overlay might stick out of the viewport at smaller screen sizes.
DropdownFooter
The overlay can include a DropdownFooter with an icon and some other information. The title of the footer should link somewhere.
DropdownActionButton
DropdownActionButton is another component to enrich the overlay.
It spans the entire width of the Dropdown and can be configured to automatically close the Dropdown on click.
MenuDropdown BETA
MenuDropdown is a special Dropdown that shows a list of buttons in its overlay. Actions can either be triggered by MenuDropdown.onSelect or with individual onClick handlers defined through items.
Links
By providing an href in the item props, MenuDropdown will switch to using links instead of buttons.
Sections
The items can be also divided into sections.
Loading
If you are pulling the menu items from a backend, you can tell the MenuDropdown to display a loading Spinner in the meantime.
Rules For Developers
- Even when the items are loading please set the
itemsprop, e.g.items={[]}
ColorDropdown BETA
A component for picking a colour.
Rules For Developers
- The palette can be configured by passing a colour array to the
colorsprop. You can import colour sets from GDS.
MonthDropdown BETA
A component for picking a month.
This component should be used when it controls something directly. Examplar use case is changing the time period displayed in a chart.
Please do not use MonthDropdown in Forms, use NewDateInput instead.
YearDropdown BETA
A component for picking a year.
This component should be used when it controls something directly. Examplar use case is changing the time period displayed in a chart.
Please do not use YearDropdown in Forms, use NewDateInput instead.
SplitButton BETA
SplitButton is a special component consisting of a Button and a MenuDropdown.