Go to Content
Design System
Playroom Storybook
#ClimateEmergency

Dropdown React-only

Open in Storybook Open in Figma

Dropdown is an overlay that attaches to a toggle and drops from it.

Loading demo…

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.

Loading demo…

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.

Loading demo…
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 quick prop
  • 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 with closeOnScroll prop. 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.

Loading demo…

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.

Loading demo…

The overlay can include a DropdownFooter with an icon and some other information. The title of the footer should link somewhere.

Loading demo…

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.

Loading demo…

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.

Loading demo…

By providing an href in the item props, MenuDropdown will switch to using links instead of buttons.

Loading demo…

Sections

The items can be also divided into sections.

Loading demo…

Loading

If you are pulling the menu items from a backend, you can tell the MenuDropdown to display a loading Spinner in the meantime.

Loading demo…
Rules For Developers
  • Even when the items are loading please set the items prop, e.g. items={[]}

ColorDropdown BETA

A component for picking a colour.

Loading demo…
Rules For Developers
  • The palette can be configured by passing a colour array to the colors prop. 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.

Loading demo…

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.

Loading demo…

SplitButton BETA

SplitButton is a special component consisting of a Button and a MenuDropdown.

Loading demo…