Popover

Displays rich content in a portal, triggered by a button.

Features

  • Full keyboard navigation
  • Customize positioning of popover
  • Can be controlled or uncontrolled
  • Focus is fully managed
  • Supports an optional arrow component

Anatomy

  • Trigger: The button(s) which open/close the popover.
  • Content: The content area viewed when the trigger is clicked.
  • Arrow: An optional arrow component
  • Close: A button which closes the popover

Usage

To create a popover, use the createPopover builder function. Follow the anatomy or the example above to create your popover.

Default open state

To specify that the popover should be open by default, set the defaultOpen prop to true.

    const { trigger, content, open, arrow, close } = createPopover({
  defaultOpen: true
})
	
    const { trigger, content, open, arrow, close } = createPopover({
  defaultOpen: true
})
	

Controlled usage

To control the popover directly, you can use the onOpenChange prop, which accepts a callback.

The callback will be called with an object containing two properties: prev and next. Prev indicates the previous open state, and next indicates the next open state that would take place in uncontrolled usage. The value returned by the callback will be used as the next open state.

    const popover = createPopover({
  onOpenChange: ({ curr, next }) => {
  // Do something with the open state
  if (/* some condition */) {
    return false
  }
  return next
  }
})
	
    const popover = createPopover({
  onOpenChange: ({ curr, next }) => {
  // Do something with the open state
  if (/* some condition */) {
    return false
  }
  return next
  }
})
	

You can also pass in your own store to control the open state. This is useful when you want to control the open state from outside the popover, or use an outside store that is already being used elsewhere in your application.

If you don't pass an open prop, the builder will create a store for you, and return it.

    const open = writable(false)
 
const popover = createPopover({
  open
})
	
    const open = writable(false)
 
const popover = createPopover({
  open
})
	

Example Components

Nested Popovers

API Reference

createPopover

The builder function used to create the popover component.

Props

Prop Default Type / Description
positioning placement: 'bottom'

A configuration object which determines how the floating element is positioned relative to the trigger.

disableFocusTrap false
boolean

Whether to disable the focus trap.

arrowSize 8
number

The size of the arrow which points to the trigger in pixels.

closeOnEscape true
boolean

Whether or not to close the popover when the escape key is pressed.

closeOnOutsideClick true
boolean

Whether or not to close the popover when the user clicks outside of it.

preventScroll true
boolean

Whether or not to prevent scrolling of the document when the popover is open.

portal body
string | HTMLElement | null

The element or selector to render the popover into. Nested floating elements are automatically rendered into their parent if not specified. Pass in null to disable portalling.

forceVisible false
boolean

Whether or not to force the popover to always be visible. This is useful for custom transitions and animations using conditional blocks.

openFocus -

Override the default focus behavior on open

closeFocus -

Override the default focus behavior on close

defaultOpen false
boolean

Whether the popover is open by default or not.

open -
Writable<boolean>

A writable store that controls whether or not the popover is open.

See Bring Your Own Store

onOpenChange -
ChangeFn<boolean>

A callback called when the value of the open store should be changed.

See Change Functions

ids -
Record<'trigger' | 'content', string>

Override the internally generated ids for the elements.

Elements

Element Description

The builder store used to create the popover trigger.

The builder store used to create the popover content.

The builder store used to create the popover close button.

The builder store used to create the popover arrow.

States

State Description
open

A writable store which represents the open state of the popover.

Options

Option Description
positioning

A configuration object which determines how the floating element is positioned relative to the trigger.

disableFocusTrap

Whether to disable the focus trap.

arrowSize

The size of the arrow which points to the trigger in pixels.

closeOnEscape

Whether or not to close the popover when the escape key is pressed.

closeOnOutsideClick

Whether or not to close the popover when the user clicks outside of it.

preventScroll

Whether or not to prevent scrolling of the document when the popover is open.

portal

The element or selector to render the popover into. Nested floating elements are automatically rendered into their parent if not specified. Pass in null to disable portalling.

forceVisible

Whether or not to force the popover to always be visible. This is useful for custom transitions and animations using conditional blocks.

openFocus

Override the default focus behavior on open

closeFocus

Override the default focus behavior on close

IDs

Option Description
trigger

The writable store that represents the id of the trigger element.

content

The writable store that represents the id of the content element.

trigger

The button(s) which open/close the popover.

Data Attributes

Data Attribute Value
[data-state]

'open' | 'closed'

[data-melt-popover-trigger]

Present on all trigger elements.

Custom Events

Event Value
m-click (e: ) => void
m-keydown (e: ) => void

content

The popover content.

Data Attributes

Data Attribute Value
[data-melt-popover-content]

Present on all content elements.

close

The button(s) which close the popover.

Data Attributes

Data Attribute Value
[data-melt-popover-close]

Present on all close elements.

Custom Events

Event Value
m-click (e: ) => void
m-keydown (e: ) => void

arrow

The optional arrow element.

Data Attributes

Data Attribute Value
[data-arrow]

'true'

[data-melt-popover-arrow]

Present on all arrow elements.

Accessibility

Adheres to the Dialog WAI-ARIA design pattern

Key Behavior
Space

Toggles the popover.

Enter

Toggles the popover.

Tab

Moves focus to the next focusable element; all focusable elements in the popover are included in the page Tab sequence.

Shift + Tab

Moves focus to the previous focusable element; all focusable elements in the popover are included in the page Tab sequence.

Esc

Closes the popover and moves focus to the trigger element.