Popover
Use the EuiPopover component to hide controls or options behind a clickable element. A popover is temporary so keep tasks simple and narrowly focused.
- Popover triggers must be anchored to elements that accept keyboard focus.
- Popovers can contain interactive elements. They must be controlled by a click handler.
- Popovers must not be activated by hover or focus events.
While the visibility of the popover is maintained by the consuming application, popovers will automatically close when clicking outside of the popover bounds. Therefore all work done in a popover should automatically be saved.
Avoid popover inception (popover triggering another popover), and instead use a EuiContextMenu to swap the popover panel content.
Anchor position
The alignment and arrow on your popover can be set with the anchorPosition
prop. These positions will update based upon screen real estate.
Some tips:
- The first word in the
anchorPosition
denotes where the popover will appear relative to the button. - The second word in the
anchorPosition
denotes where the gravity / pin position will appear relative to the popover.
Popover titles and footers
Popovers often need titling. Use the EuiPopoverTitle component nested somewhere inside the popover contents.
You can also add a similarly styled EuiPopoverFooter for smaller captions or call to action buttons.
Popover padding sizes
Use the panelPaddingSize
prop to adjust the padding of the panel content. When using popover titles and footers, this setting will propogate to them. Or you can supply a custom paddingSize
to either the EuiPopoverTitle of EuiPopoverFooter.
Panel class name
Use the panelClassName
prop to pass a custom class to the panel containing the popover contents.
Popover with block level display
Popover anchors default to display: inline-block;
so they do not force a display on inline triggers. If you do need to change this, just add display="block"
Popover on a fixed element
Popover content even works on position: fixed;
elements. Add the repositionOnScroll
boolean prop to ensure the popover realigns to the fixed button on scroll.
Constraining a popover inside a container
EuiPopover can accept a React or DOM element as a container
prop and restrict the popover from overflowing that container.
Popover attached to input element
EuiInputPopover is a specialized popover component intended to be used with form elements. Stylistically, the popover panel is "attached" to the input. As a result, the popover will always try to set its width to match the width of the input, although this can be configured via panelMinWidth
.
Functionally, consumers have control over what events open and close the popover, and it can allow for natural tab order. Although some assumptions are made about keyboard behavior, consumers should provide specific key event handlers depending on the use case. For instance, a type=text
input could use the down key to trigger popover opening, but this interaction would not be appropriate for type=number
inputs as they natively bind to the down key.
Setting an initial focus
If you want a specific child element of the popover to immediately gain focus when the popover is open, use the initialFocus
prop to pass either a selector or DOM node.
It can be jarring for keyboard and screen reader users to immediately land on an element with no other context. To alleviate this, ensure that your initial focus target makes sense alone or is the primary goal of the popover.
Custom outside click behavior
If you do not wish the popover to auto-close on outside clicks, you can use focusTrapProps
to customize this behavior. The below example triggers a confirmation modal which can leave the popover open if the user presses 'No'.
Removing the focus trap
If the popover should not trap focus within itself, then you can remove it with ownFocus={false}
.
Removing ownFocus
makes it difficult for keyboard-only and screen reader users to navigate to and from your popover.
Popover using an HTMLElement as the anchor
EuiWrappingPopover is an extra popover component that allows any existing DOM element to be passed as the button
prop.
Props
EuiPopover
Prop | Description and type | Default value |
---|---|---|
Prop button# | Description and type Triggering element for which to align the popover to NonNullable<ReactNode> | Default value Required |
Prop closePopover# | Description and type Callback to handle hiding of the popover NoArgCallback<void> | Default value Required |
Prop anchorPosition# | Description and type Alignment of the popover and arrow relative to the button "upCenter" | "upLeft" | "upRight" | "downCenter" | "downLeft" | "downRight" | "leftCenter" | "leftUp" | "leftDown" | "rightCenter" | "rightUp" | "rightDown" | Default value downCenter |
Prop attachToAnchor# | Description and type Style and position alteration for arrow-less attachment. boolean | Default value |
Prop container# | Description and type Restrict the popover's position within this element HTMLElement | Default value |
Prop display# | Description and type CSS display type for both the popover and anchor Display | Default value inline-block |
Prop focusTrapProps# | Description and type Object of props passed to EuiFocusTrap Partial<EuiFocusTrapProps> | Default value |
Prop hasArrow# | Description and type Show arrow indicating to originating button boolean | Default value true |
Prop initialFocus# | Description and type Specifies what element should initially have focus; Can be a DOM If not passed, initial focus defaults to the popover panel. ElementTarget | Default value |
Prop insert# | Description and type Passed directly to EuiPortal for DOM positioning. Both properties are { sibling: HTMLElement; position: "before" | "after"; } | Default value |
Prop isOpen# | Description and type Visibility state of the popover boolean | Default value false |
Prop ownFocus# | Description and type Traps tab focus within the popover contents boolean | Default value true |
Prop panelClassName# | Description and type Custom class added to the EuiPanel containing the popover contents string | Default value |
Prop panelPaddingSize# | Description and type EuiPanel padding on all sides "xs" | "s" | "m" | "l" | "xl" | "none" | Default value m |
Prop panelStyle# | Description and type Standard DOM CSSProperties | Default value |
Prop panelProps# | Description and type Object of props passed to EuiPanel. See #EuiPopoverPanelProps Omit<_EuiPanelDivlike, "color" | "style" | "hasBorder" | "hasShadow"> | Default value |
Prop panelRef# | Description and type Type: RefCallback<HTMLElement> | Default value |
Prop popoverScreenReaderText# | Description and type Optional screen reader instructions to announce upon popover open, ReactNode | Default value |
Prop popoverRef# | Description and type Type: Ref<HTMLDivElement> | Default value |
Prop repositionOnScroll# | Description and type When boolean | Default value |
Prop repositionToCrossAxis# | Description and type By default, popovers will attempt to position themselves along the initial If you do not not want this repositioning to occur (and it is acceptable for boolean | Default value true |
Prop hasDragDrop# | Description and type Must be set to true if using boolean | Default value |
Prop zIndex# | Description and type By default, popover content inherits the z-index of the anchor number | Default value |
Prop offset# | Description and type Distance away from the anchor that the popover will render number | Default value |
Prop buffer# | Description and type Minimum distance between the popover and the bounding container; number | [number, number, number, number] | Default value 16 |
Prop arrowChildren# | Description and type Element to pass as the child element of the arrow; ReactNode | Default value |
Prop aria-label# | Description and type Provide a name to the popover panel string | Default value |
Prop aria-labelledby# | Description and type Alternative option to string | Default value |
Prop onPositionChange# | Description and type Function callback for when the popover positon changes (position: EuiPopoverPosition) => void | Default value |
Prop className# | Description and type Type: string | Default value |
Prop data-test-subj# | Description and type Type: string | Default value |
Prop css# | Description and type Type: Interpolation<Theme> | Default value |
EuiPopoverTitle
Prop | Description and type | Default value |
---|---|---|
Prop className# | Description and type Type: string | Default value |
Prop aria-label# | Description and type Defines a string value that labels the current element. string | Default value |
Prop data-test-subj# | Description and type Type: string | Default value |
Prop css# | Description and type Type: Interpolation<Theme> | Default value |
Prop paddingSize# | Description and type Customize the all around padding of the popover title. "xs" | "s" | "m" | "l" | "xl" | "none" | Default value |
EuiPopoverFooter
Prop | Description and type | Default value |
---|---|---|
Prop className# | Description and type Type: string | Default value |
Prop aria-label# | Description and type Defines a string value that labels the current element. string | Default value |
Prop data-test-subj# | Description and type Type: string | Default value |
Prop css# | Description and type Type: Interpolation<Theme> | Default value |
Prop paddingSize# | Description and type Customize the all around padding of the popover footer. "xs" | "s" | "m" | "l" | "xl" | "none" | Default value |
EuiInputPopover
Prop | Description and type | Default value |
---|---|---|
Prop input# | Description and type Type: NonNullable<ReactNode> | Default value Required |
Prop closePopover# | Description and type Callback to handle hiding of the popover NoArgCallback<void> | Default value Required |
Prop className# | Description and type Type: string | Default value |
Prop aria-label# | Description and type Defines a string value that labels the current element. string | Default value |
Prop data-test-subj# | Description and type Type: string | Default value |
Prop css# | Description and type Type: Interpolation<Theme> | Default value |
Prop anchorPosition# | Description and type Alignment of the popover relative to the input "downCenter" | "downLeft" | "downRight" | Default value downLeft |
Prop disableFocusTrap# | Description and type Type: boolean | Default value false |
Prop closeOnScroll# | Description and type Allows automatically closing the input popover on page scroll boolean | Default value false |
Prop fullWidth# | Description and type Type: boolean | Default value false |
Prop inputRef# | Description and type Type: Ref<HTMLDivElement> | Default value |
Prop onPanelResize# | Description and type Type: (width: number) => void | Default value |
Prop panelMinWidth# | Description and type By default, EuiInputPopovers inherit the same width as the passed input element. number | Default value 0 |
Prop zIndex# | Description and type By default, popover content inherits the z-index of the anchor number | Default value |
Prop container# | Description and type Restrict the popover's position within this element HTMLElement | Default value |
Prop display# | Description and type CSS display type for both the popover and anchor Display | Default value block |
Prop offset# | Description and type Distance away from the anchor that the popover will render number | Default value |
Prop panelRef# | Description and type Type: RefCallback<HTMLElement> | Default value |
Prop ownFocus# | Description and type Traps tab focus within the popover contents boolean | Default value false |
Prop focusTrapProps# | Description and type Object of props passed to EuiFocusTrap Partial<EuiFocusTrapProps> | Default value |
Prop isOpen# | Description and type Visibility state of the popover boolean | Default value |
Prop attachToAnchor# | Description and type Style and position alteration for arrow-less attachment. boolean | Default value true |
Prop hasArrow# | Description and type Show arrow indicating to originating button boolean | Default value |
Prop initialFocus# | Description and type Specifies what element should initially have focus; Can be a DOM If not passed, initial focus defaults to the popover panel. ElementTarget | Default value |
Prop insert# | Description and type Passed directly to EuiPortal for DOM positioning. Both properties are { sibling: HTMLElement; position: "before" | "after"; } | Default value |
Prop panelClassName# | Description and type Custom class added to the EuiPanel containing the popover contents string | Default value |
Prop panelPaddingSize# | Description and type EuiPanel padding on all sides "xs" | "s" | "m" | "l" | "xl" | "none" | Default value s |
Prop panelStyle# | Description and type Standard DOM CSSProperties | Default value |
Prop panelProps# | Description and type Object of props passed to EuiPanel. See #EuiPopoverPanelProps Omit<_EuiPanelDivlike, "color" | "style" | "hasBorder" | "hasShadow"> | Default value |
Prop popoverScreenReaderText# | Description and type Optional screen reader instructions to announce upon popover open, ReactNode | Default value |
Prop popoverRef# | Description and type Type: Ref<HTMLDivElement> | Default value |
Prop repositionOnScroll# | Description and type When boolean | Default value |
Prop repositionToCrossAxis# | Description and type By default, popovers will attempt to position themselves along the initial If you do not not want this repositioning to occur (and it is acceptable for boolean | Default value false |
Prop hasDragDrop# | Description and type Must be set to true if using boolean | Default value |
Prop buffer# | Description and type Minimum distance between the popover and the bounding container; number | [number, number, number, number] | Default value 16 |
Prop arrowChildren# | Description and type Element to pass as the child element of the arrow; ReactNode | Default value |
Prop onPositionChange# | Description and type Function callback for when the popover positon changes (position: EuiPopoverPosition) => void | Default value |
EuiWrappingPopover
Prop | Description and type | Default value |
---|---|---|
Prop button# | Description and type Type: HTMLElement | Default value Required |
Prop closePopover# | Description and type Callback to handle hiding of the popover NoArgCallback<void> | Default value Required |
Prop zIndex# | Description and type By default, popover content inherits the z-index of the anchor number | Default value |
Prop className# | Description and type Type: string | Default value |
Prop css# | Description and type Type: Interpolation<Theme> | Default value |
Prop aria-label# | Description and type Provide a name to the popover panel string | Default value |
Prop data-test-subj# | Description and type Type: string | Default value |
Prop aria-labelledby# | Description and type Alternative option to string | Default value |
Prop container# | Description and type Restrict the popover's position within this element HTMLElement | Default value |
Prop display# | Description and type CSS display type for both the popover and anchor Display | Default value |
Prop offset# | Description and type Distance away from the anchor that the popover will render number | Default value |
Prop panelRef# | Description and type Type: RefCallback<HTMLElement> | Default value |
Prop ownFocus# | Description and type Traps tab focus within the popover contents boolean | Default value |
Prop focusTrapProps# | Description and type Object of props passed to EuiFocusTrap Partial<EuiFocusTrapProps> | Default value |
Prop isOpen# | Description and type Visibility state of the popover boolean | Default value |
Prop anchorPosition# | Description and type Alignment of the popover and arrow relative to the button "upCenter" | "upLeft" | "upRight" | "downCenter" | "downLeft" | "downRight" | "leftCenter" | "leftUp" | "leftDown" | "rightCenter" | "rightUp" | "rightDown" | Default value |
Prop attachToAnchor# | Description and type Style and position alteration for arrow-less attachment. boolean | Default value |
Prop hasArrow# | Description and type Show arrow indicating to originating button boolean | Default value |
Prop initialFocus# | Description and type Specifies what element should initially have focus; Can be a DOM If not passed, initial focus defaults to the popover panel. ElementTarget | Default value |
Prop insert# | Description and type Passed directly to EuiPortal for DOM positioning. Both properties are { sibling: HTMLElement; position: "before" | "after"; } | Default value |
Prop panelClassName# | Description and type Custom class added to the EuiPanel containing the popover contents string | Default value |
Prop panelPaddingSize# | Description and type EuiPanel padding on all sides "xs" | "s" | "m" | "l" | "xl" | "none" | Default value |
Prop panelStyle# | Description and type Standard DOM CSSProperties | Default value |
Prop panelProps# | Description and type Object of props passed to EuiPanel. See #EuiPopoverPanelProps Omit<_EuiPanelDivlike, "color" | "style" | "hasBorder" | "hasShadow"> | Default value |
Prop popoverScreenReaderText# | Description and type Optional screen reader instructions to announce upon popover open, ReactNode | Default value |
Prop popoverRef# | Description and type Type: Ref<HTMLDivElement> | Default value |
Prop repositionOnScroll# | Description and type When boolean | Default value |
Prop repositionToCrossAxis# | Description and type By default, popovers will attempt to position themselves along the initial If you do not not want this repositioning to occur (and it is acceptable for boolean | Default value true |
Prop hasDragDrop# | Description and type Must be set to true if using boolean | Default value |
Prop buffer# | Description and type Minimum distance between the popover and the bounding container; number | [number, number, number, number] | Default value 16 |
Prop arrowChildren# | Description and type Element to pass as the child element of the arrow; ReactNode | Default value |
Prop onPositionChange# | Description and type Function callback for when the popover positon changes (position: EuiPopoverPosition) => void | Default value |