Examples
Dropdown builds off of the Menu component suite to wrap commonly used properties and functions for a dropdown menu. See the Menu documentation for a full list of properties that may be passed through Dropdown to further customize the dropdown menu, or the custom menu examples for additional examples of fully functional menus.
Basic dropdowns
Basic dropdowns present users with a menu of items upon clicking a dropdown toggle.
A <Dropdown> uses a menu toggle, which is passed to the toggle property, as well as a <DropdownList> with multiple <DropdownItem> components. To allow a dropdown to change the open state of the menu, pass the isOpen property into the onOpenChange callback.
The following example shows a few different states of dropdown items. As shown in this example, dropdown items may:
- Use the
isDisabledproperty to disable an item. - Use the
onClickproperty to trigger a callback for an action.
This example also uses a <Divider> which passes in key=”separator” to split the menu into 2 sections with a horizontal line.
With kebab toggle
To style a dropdown menu's toggle with a kebab icon, pass a "plain" <MenuToggle> to the toggle property. When there isn't enough space for a labeled button, a kebab icon can be used to toggle the dropdown menu open or closed.
With groups of items
To group sets of related dropdown items together, use a <DropdownGroup>. When more than 1 <DropdownGroup> is created in a menu, use the label and labelHeadingLevel properties to assign a name and heading level to each group.
With item descriptions
To provide users with more context about a <DropdownItem>, pass a short message to description property. As shown in the example below, an item's description will appear below its label.
Props
Dropdown
| Name | Type | Default | Description |
|---|---|---|---|
| togglerequired | DropdownToggleProps | ((toggleRef: React.RefObject<any>) => React.ReactNode) | Dropdown toggle. The toggle should either be a renderer function which forwards the given toggle ref, or a direct ReactNode that should be passed along with the toggleRef property. | |
| children | React.ReactNode | Anything which can be rendered in a dropdown. | |
| className | string | Classes applied to root element of dropdown. | |
| isOpen | boolean | Flag to indicate if menu is opened. | |
| isPlain | boolean | Indicates if the menu should be without the outer box-shadow. | |
| isScrollable | boolean | Indicates if the menu should be scrollable. | |
| maxMenuHeight | string | Maximum height of dropdown menu | |
| menuHeight | string | Height of the dropdown menu | |
| onOpenChange | (isOpen: boolean) => void | Callback to allow the dropdown component to change the open state of the menu. Triggered by clicking outside of the menu, or by pressing any keys specificed in onOpenChangeKeys. | |
| onOpenChangeKeys | string[] | Keys that trigger onOpenChange, defaults to tab and escape. It is highly recommended to include Escape in the array, while Tab may be omitted if the menu contains non-menu items that are focusable. | |
| onSelect | (event?: React.MouseEvent<Element, MouseEvent>, value?: string | number) => void | Function callback called when user selects item. | |
| ouiaId | number | string | Value to overwrite the randomly generated data-ouia-component-id. | |
| ouiaSafe | boolean | Set the value of data-ouia-safe. Only set to true when the component is in a static state, i.e. no animations are occurring. At all other times, this value must be false. | |
| popperProps | DropdownPopperProps | Additional properties to pass to the Popper | |
| shouldFocusFirstItemOnOpen Beta | boolean | Flag indicating the first menu item should be focused after opening the dropdown. | |
| shouldFocusToggleOnSelect | boolean | Flag indicating the toggle should be focused after a selection. If this use case is too restrictive, the optional toggleRef property with a node toggle may be used to control focus. | |
| zIndex | number | z-index of the dropdown menu |
DropdownGroup
| Name | Type | Default | Description |
|---|---|---|---|
| childrenrequired | React.ReactNode | Anything which can be rendered in a dropdown group. | |
| className | string | Classes applied to root element of dropdown group | |
| label | string | Label of the dropdown group | |
| labelHeadingLevel | No type info | 'h1' |
DropdownItem
| Name | Type | Default | Description |
|---|---|---|---|
| children | React.ReactNode | Anything which can be rendered in a dropdown item | |
| className | string | Classes applied to root element of dropdown item | |
| description | React.ReactNode | Description of the dropdown item | |
| isAriaDisabled | boolean | Render item as aria-disabled option | |
| isDisabled | boolean | Render item as disabled option | |
| onClick | (event?: any) => void | Callback for item click | |
| ouiaId | number | string | Value to overwrite the randomly generated data-ouia-component-id. | |
| ouiaSafe | boolean | Set the value of data-ouia-safe. Only set to true when the component is in a static state, i.e. no animations are occurring. At all other times, this value must be false. | |
| tooltipProps | TooltipProps | Props for adding a tooltip to a menu item | |
| value | any | Identifies the component in the dropdown onSelect callback |
DropdownList
| Name | Type | Default | Description |
|---|---|---|---|
| childrenrequired | React.ReactNode | Anything which can be rendered in a dropdown list | |
| className | string | Classes applied to root element of dropdown list |
MenuToggle
| Name | Type | Default | Description |
|---|---|---|---|
| badge | BadgeProps | React.ReactNode | Optional badge rendered inside the toggle, after the children content | |
| children | React.ReactNode | Content rendered inside the toggle | |
| className | string | Additional classes added to the toggle | |
| icon | React.ReactNode | Optional icon or image rendered inside the toggle, before the children content. It is recommended to wrap most basic icons in our icon component. | |
| isDisabled | boolean | Flag indicating the toggle is disabled | |
| isExpanded | boolean | Flag indicating the toggle has expanded styling | |
| isFullHeight | boolean | Flag indicating the toggle is full height | |
| isFullWidth | boolean | Flag indicating the toggle takes up the full width of its parent | |
| ouiaId | number | string | Value to overwrite the randomly generated data-ouia-component-id. It will always target the toggle button. | |
| ouiaSafe | boolean | Set the value of data-ouia-safe. Only set to true when the component is in a static state, i.e. no animations are occurring. At all other times, this value must be false. | |
| size | 'default' | 'sm' | Adds styling which affects the size of the menu toggle | |
| splitButtonOptions | SplitButtonOptions | Object used to configure a split button menu toggle | |
| status | 'success' | 'warning' | 'danger' | Status styles of the menu toggle | |
| statusIcon | React.ReactNode | Overrides the status icon | |
| variant | 'default' | 'plain' | 'primary' | 'plainText' | 'secondary' | 'typeahead' | Variant styles of the menu toggle |
DropdownToggleProps
| Name | Type | Default | Description |
|---|---|---|---|
| toggleNoderequired | React.ReactNode | Dropdown toggle node. | |
| toggleRef | React.RefObject<HTMLButtonElement> | Reference to the toggle. |
DropdownPopperProps
| Name | Type | Default | Description |
|---|---|---|---|
| appendTo | HTMLElement | (() => HTMLElement) | 'inline' | The container to append the popper to. Defaults to document.body. | |
| direction | 'up' | 'down' | Vertical direction of the popper. If enableFlip is set to true, this will set the initial direction before the popper flips. | |
| enableFlip | boolean | Enable to flip the popper when it reaches the boundary | |
| maxWidth | string | 'trigger' | Maximum width of the popper. If the value is "trigger", it will set the max width to the dropdown toggle's width | |
| minWidth | string | 'trigger' | Minimum width of the popper. If the value is "trigger", it will set the min width to the dropdown toggle's width | |
| position | 'right' | 'left' | 'center' | 'start' | 'end' | Horizontal position of the popper | |
| preventOverflow | boolean | Flag to prevent the popper from overflowing its container and becoming partially obscured. | |
| width | string | 'trigger' | Custom width of the popper. If the value is "trigger", it will set the width to the dropdown toggle's width |
TooltipProps
| Name | Type | Default | Description |
|---|---|---|---|
| contentrequired | React.ReactNode | Tooltip content | |
| animationDuration | number | CSS fade transition animation duration | |
| appendTo | HTMLElement | ((ref?: HTMLElement) => HTMLElement) | The element to append the tooltip to, defaults to body | |
| aria | 'describedby' | 'labelledby' | 'none' | aria-labelledby or aria-describedby for tooltip. The trigger will be cloned to add the aria attribute, and the corresponding id in the form of 'pf-tooltip-#' is added to the content container. If you don't want that or prefer to add the aria attribute yourself on the trigger, set aria to 'none'. | |
| children | ReactElement<any> | The trigger reference element to which the Tooltip is relatively placed to. If you cannot wrap the element with the Tooltip, you can use the triggerRef prop instead. Usage: <Tooltip><Button>Reference</Button></Tooltip> | |
| className | string | Tooltip additional class | |
| distance | number | Distance of the tooltip to its target, defaults to 15 | |
| enableFlip | boolean | If true, tries to keep the tooltip in view by flipping it if necessary | |
| entryDelay | number | Delay in ms before the tooltip appears | |
| exitDelay | number | Delay in ms before the tooltip disappears, Avoid passing in a value of "0", as users should be given ample time to move their mouse from the trigger to the tooltip content without the content being hidden. | |
| flipBehavior | | 'flip' | ( | 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end' )[] | The desired position to flip the tooltip to if the initial position is not possible. By setting this prop to 'flip' it attempts to flip the tooltip to the opposite side if there is no space. You can also pass an array of positions that determines the flip order. It should contain the initial position followed by alternative positions if that position is unavailable. Example: Initial position is 'top'. Button with tooltip is in the top right corner. 'flipBehavior' is set to ['top', 'right', 'left']. Since there is no space to the top, it checks if right is available. There's also no space to the right, so it finally shows the tooltip on the left. | |
| id | string | id of the tooltip | |
| isContentLeftAligned | boolean | Flag to indicate that the text content is left aligned | |
| isVisible | boolean | value for visibility when trigger is 'manual' | |
| maxWidth | string | Maximum width of the tooltip (default 18.75rem) | |
| minWidth | string | 'trigger' | Minimum width of the tooltip. If set to "trigger", the minimum width will be set to the reference element width. | |
| onTooltipHidden | () => void | Callback when tooltip's hide transition has finished executing | |
| position | | TooltipPosition | 'auto' | 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end' | Tooltip position. Note: With 'enableFlip' set to true, it will change the position if there is not enough space for the starting position. The behavior of where it flips to can be controlled through the flipBehavior prop. The 'auto' position chooses the side with the most space. The 'auto' position requires the 'enableFlip' prop to be true. | |
| trigger | string | Tooltip trigger: click, mouseenter, focus, manual Set to manual to trigger tooltip programmatically (through the isVisible prop) | |
| triggerRef | HTMLElement | (() => HTMLElement) | React.RefObject<any> | The trigger reference element to which the Tooltip is relatively placed to. If you can wrap the element with the Tooltip, you can use the children prop instead, or both props together. When passed along with the trigger prop, the div element that wraps the trigger will be removed. Usage: <Tooltip triggerRef={() => document.getElementById('reference-element')} /> | |
| Unknown | 'off' | 'polite' | Determines whether the tooltip is an aria-live region. If the triggerRef prop is passed in the default behavior is 'polite' in order to ensure the tooltip contents is announced to assistive technologies. Otherwise the default behavior is 'off'. | |
| zIndex | number | z-index of the tooltip |
CSS variables
| Expand or collapse column | Selector | Variable | Value |
|---|
