QUI React2.6.3

Overlay Panel

A utility component for showing floating content relative to an anchor element.

import {QOverlayPanel} from "@qui/react"

Examples

Showcase

To hide and show the panel, supply an interactive element to the anchor prop. The anchor is used to compute the position of the floating panel. If supplied as an element, event handlers will be applied for triggering the open/close state of the menu on interaction.

import {ReactNode} from "react"


import {QButton, QOverlayPanel} from "@qui/react"


export default function Showcase(): ReactNode {
  return (
    <QOverlayPanel
      anchor={
        <QButton color="primary" variant="fill">
          Default
        </QButton>
      }
    >
      <div className="flex place-items-center p-2">Panel content</div>
    </QOverlayPanel>
  )
}

Anchor as Function

The anchor can also be supplied as a function. When you do this, the panel's event handlers and ref need to be passed to the reference element.

TIP

This is known as the Render Prop Pattern

import {ReactNode} from "react"


import {QAnchorProps, QButton, QOverlayPanel} from "@qui/react"


export default function RenderProp(): ReactNode {
  return (
    <div className="flex flex-col items-center justify-center gap-6">
      <QOverlayPanel
        anchor={(props: QAnchorProps) => (
          // the props must be spread to bind the event handlers.
          <QButton color="primary" variant="fill" {...props}>
            Action
          </QButton>
        )}
      >
        <div className="p-2">Panel Content</div>
      </QOverlayPanel>
    </div>
  )
}

Anchor as Ref

The anchor can be supplied as a reference to a ReactElement. When you do this, the menu's event handlers are not bound, so you'll need to manually control the open state.

import {ReactNode, useRef, useState} from "react"


import {QAvatar, QButton, QOverlayPanel} from "@qui/react"


export default function AnchorRef(): ReactNode {
  const anchorRef = useRef(null)


  const [open, setOpen] = useState(false)


  return (
    <div className="flex items-center justify-center gap-6">
      <QButton
        color="primary"
        onClick={() => {
          setOpen((prevState) => !prevState)
        }}
        variant="fill"
      >
        Action
      </QButton>
      <QAvatar ref={anchorRef} content="AV" variant="text" />
      <QOverlayPanel
        anchor={anchorRef}
        onOpenChange={(visible: boolean, event, reason) => {
          console.debug(reason, visible)
          setOpen(visible)
        }}
        open={open}
      >
        <div className="p-2">Panel Content</div>
      </QOverlayPanel>
    </div>
  )
}

Playground

bottom-start
TSX
<QOverlayPanel
  arrow={false}
  focus={false}
  hover={false}
  offset={0}
  placement="bottom-start"
  restoreFocus={true}         
/>

API

Props

Name & DescriptionOption(s)Default
anchor
*
The interactive element that will be used to compute the position of the floating panel. If supplied as an element, event handlers will be applied for triggering the open/close state of the menu on interaction. Can also be supplied as a function that returns an element, or a reference to a ReactElement.
| Element
| ((
    props: Props,
  ) => Element)
| RefObject<
    HTMLElement | object
  >
children
*
React children prop. The content of the panel.
| ReactNode
| ((props: {
    open: boolean
    setOpen: (
      open: boolean,
      ...events: any[]
    ) => void
  }) => ReactNode)
animationDuration
The CSS transition-duration of the enter and exit animations. Supply as a number to configure both transitions at once, or supply an object to configure the enter and exit transitions independently.
| number
| {
    enter: number
    exit: number
  }
200
arrow
Show an arrow between the component and the anchor element.
boolean
arrowOptions
Configure the element shown when arrow is true.
{
  className?: string
  fill?: string
  height?: number
  style?: CSSProperties
  width?: number
}
as
The component used for the root node. It can be a React component or element.
| ElementType
| ComponentType
'div'
autoUpdate
Ensure that the component remains anchored to its reference element following screen resizes or position changes.
boolean
className
The className property of the Element interface gets and sets the value of the class attribute of the specified element.
string
defaultOpen
The default value when uncontrolled.
boolean
disableInitialFocus
If true, the overlay panel will not steal focus when it opens.
boolean
elevation
Box shadow severity of the panel, based on the five elevation styles provided by QDS. A higher number means a more severe box shadow. Supply 0 to disable the box shadow.
| 0
| 1
| 2
| 3
| 4
| 5
| '0'
| '1'
| '2'
| '3'
| '4'
| '5'
flip
Whether to flip the component's placement to keep it in view.
boolean
true
focus
If true, the component will show when the anchor element is focused. This property is ignored if open is supplied.
boolean
false
hover
If true, the component will show when the anchor element is hovered. This property is ignored if open is supplied.
boolean
false
keepMounted
If true, content of the overlay panel is always mounted, even when the panel is not visible.
boolean
false
offset
The distance between the component and its anchor element.
| number
| {
    alignmentAxis?: number
    crossAxis?: number
    mainAxis?: number
  }
0
onOpenChange
Callback fired when panel visibility changes.
  • openThe updated state.
  • eventThe event that triggered the change.
  • reasonThe cause of the change.
(
  open: boolean,
  event?: Event,
  reason?:
    | 'ancestor-scroll'
    | 'click'
    | 'escape-key'
    | 'focus'
    | 'hover'
    | 'list-navigation'
    | 'outside-press'
    | 'reference-press'
    | 'safe-polygon',
) => void
open
The controlled state for the component's visibility.
boolean
placement
Describes the placement of the component before FloatingUI has applied all the modifiers that may have flipped or altered the component. The final placement may differ from this input property.
| 'top-start'
| 'top'
| 'top-end'
| 'bottom-start'
| 'bottom'
| 'bottom-end'
| 'left-start'
| 'left'
| 'left-end'
| 'right-start'
| 'right'
| 'right-end'
'top'
position
CSS position attribute of the component. Can be "absolute" or "fixed".
| 'absolute'
| 'fixed'
'absolute'
restoreFocus
If true, focus will be restored to the component's anchor element on close.
boolean
!hover
style
The style global attribute contains CSS styling declarations to be applied to the element.
CSSProperties
zIndex
The z-index CSS property sets the z-order of a positioned element and its descendants or flex items. Overlapping elements with a larger z-index cover those with a smaller one.
| string
| number
1000
Type
| Element
| ((
    props: Props,
  ) => Element)
| RefObject<
    HTMLElement | object
  >
Description
The interactive element that will be used to compute the position of the floating panel. If supplied as an element, event handlers will be applied for triggering the open/close state of the menu on interaction. Can also be supplied as a function that returns an element, or a reference to a ReactElement.
Type
| ReactNode
| ((props: {
    open: boolean
    setOpen: (
      open: boolean,
      ...events: any[]
    ) => void
  }) => ReactNode)
Description
React children prop. The content of the panel.
Type
| number
| {
    enter: number
    exit: number
  }
Default
200
Description
The CSS transition-duration of the enter and exit animations. Supply as a number to configure both transitions at once, or supply an object to configure the enter and exit transitions independently.
Type
boolean
Description
Show an arrow between the component and the anchor element.
Type
{
  className?: string
  fill?: string
  height?: number
  style?: CSSProperties
  width?: number
}
Description
Configure the element shown when arrow is true.
Type
| ElementType
| ComponentType
Default
'div'
Description
The component used for the root node. It can be a React component or element.
Type
boolean
Description
Ensure that the component remains anchored to its reference element following screen resizes or position changes.
Type
string
Description
The className property of the Element interface gets and sets the value of the class attribute of the specified element.
Type
boolean
Description
The default value when uncontrolled.
Type
boolean
Description
If true, the overlay panel will not steal focus when it opens.
Type
| 0
| 1
| 2
| 3
| 4
| 5
| '0'
| '1'
| '2'
| '3'
| '4'
| '5'
Description
Box shadow severity of the panel, based on the five elevation styles provided by QDS. A higher number means a more severe box shadow. Supply 0 to disable the box shadow.
Type
boolean
Default
true
Description
Whether to flip the component's placement to keep it in view.
Type
boolean
Default
false
Description
If true, the component will show when the anchor element is focused. This property is ignored if open is supplied.
Type
boolean
Default
false
Description
If true, the component will show when the anchor element is hovered. This property is ignored if open is supplied.
Type
boolean
Default
false
Description
If true, content of the overlay panel is always mounted, even when the panel is not visible.
Type
| number
| {
    alignmentAxis?: number
    crossAxis?: number
    mainAxis?: number
  }
Default
0
Description
The distance between the component and its anchor element.
Type
(
  open: boolean,
  event?: Event,
  reason?:
    | 'ancestor-scroll'
    | 'click'
    | 'escape-key'
    | 'focus'
    | 'hover'
    | 'list-navigation'
    | 'outside-press'
    | 'reference-press'
    | 'safe-polygon',
) => void
Description
Callback fired when panel visibility changes.
  • openThe updated state.
  • eventThe event that triggered the change.
  • reasonThe cause of the change.
Type
boolean
Description
The controlled state for the component's visibility.
Type
| 'top-start'
| 'top'
| 'top-end'
| 'bottom-start'
| 'bottom'
| 'bottom-end'
| 'left-start'
| 'left'
| 'left-end'
| 'right-start'
| 'right'
| 'right-end'
Default
'top'
Description
Describes the placement of the component before FloatingUI has applied all the modifiers that may have flipped or altered the component. The final placement may differ from this input property.
Type
| 'absolute'
| 'fixed'
Default
'absolute'
Description
CSS position attribute of the component. Can be "absolute" or "fixed".
Type
boolean
Default
!hover
Description
If true, focus will be restored to the component's anchor element on close.
Type
CSSProperties
Description
The style global attribute contains CSS styling declarations to be applied to the element.
Type
| string
| number
Default
1000
Description
The z-index CSS property sets the z-order of a positioned element and its descendants or flex items. Overlapping elements with a larger z-index cover those with a smaller one.
Previous
Notifications
Next
Pagination
Examples
Showcase
Anchor as Function
Anchor as Ref
Playground
API
Props
Copyright © 2025 QUALCOMM incorporated. All rights reserved. This site is built using QUI Docs. Head over to the template repository to start building.