A disclosure widget includes a button that opens a panel of links or actions.


Simple disclosure
Loading story...
Disclosure with custom list item
Loading story...
Disclosure with groups
Loading story...
Disclosure with complex content
Loading story...
NOTE: Disclosure styles will be updated to match the UI kit.

View in Pajamas UI Kit →


Numbered diagram of a disclosure widget structure
Disclosure widget structure
  1. Button: Triggers the panel to open or close.
  2. Panel: Wraps the content.
  3. Action: Button or link styled as an option.
  4. Scrim: Gradient overlay when items overflow the panel.
  5. Header (optional): Provides more context for the actions.
  6. Custom content (optional): Custom content included in a slot.


When to use

  • Use a disclosure dropdown to toggle a panel of links (<a>) or actions (<button>) that can be performed in a specific context, including the navigation sidebar.
  • In the instance where a combination of links and actions are present in the dropdown, a disclosure is preferred over other dropdown options that are more semantically prescriptive.

When not to use

  • If the options within the panel are selectable instead of directly performing an action, refer to the combobox component.
  • If a user is selecting a single text option from a group of options within a form, consider using a select, radio group, or checkboxes instead.
  • If you need a way for a user to expand or collapse a content section, use an accordion instead.
  • If there is only ever a single option, display that option directly. For example, if the only option is Remove, use a button instead.

Trigger button variants

A button that triggers a dropdown panel comes in a few variants to fit different situations.

  • Dropdown button: A dropdown button has a chevron-down icon to the right of the text label to indicate it will toggle additional content.
  • Split dropdown button: A split dropdown button is a special button group with two segments. The left text button is for the most common option and an attached dropdown button to the right opens a panel with additional options.
  • Icon dropdown: An icon button, like one that uses the vertical or horizontal ellipsis icons, functions similarly to other trigger buttons with the only difference being only an icon label with no text.


  • Trigger: The button width is determined by its available properties.
  • Panel: Has a minimum and maximum width and a maximum height to keep content near the trigger button and to keep panels consistent throughout the UI. The height of the panel is initially set to the height of its content (dynamic height) when less than the maximum, but can optionally be set to always use a fixed height.


  • By default, the panel opens below the trigger button and is aligned to the left of it.
  • The panel can be positioned to the right of the trigger button if it makes more sense in the layout.
  • When there isn't enough space in the viewport, the panel uses edge detection to position it above and/or aligned to the right of the trigger button.
  • When the panel boundaries don't allow it to flip to the other side of the trigger button because there isn't enough space, it shifts along the x-axis.
  • There will always be some padding between the vertical edges of the panel and the vertical edges of the viewport.
  • The tip of the panel points at the trigger and is center-aligned with it by default.
  • If the content within the panel exceeds the maximum height then a scrim (gradient overlay) appears at the bottom of the panel as an overflow affordance. When a user has scrolled to the bottom of the overflowed content the scrim is removed.
  • When a link is selected the user is taken to the destination.
  • When an action is selected that impacts the current view, the panel is closed and the action performed.
  • When an action option is selected that causes a page refresh or other change of context the panel returns to a closed state.
  • All panels can be closed by clicking outside of them, using the Esc key, or by focus moving to an element outside of the component.
  • A limited amount of options that don't scroll can be fixed at the bottom of a dropdown panel.


  • Text should be concise and clearly indicate the link destination or action it performs.
  • Destructive actions should be the last of the available options.



Last updated at: