Popover
Display additional content in a small overlay near a target element
Use the Popover
component to display additional content or information in a small overlay that appears near the target element when triggered by a click. Popovers are useful for providing context-sensitive details without navigating away from the current page. They can be used for detailed information, tooltips with actions, interactive content, contextual help, or for notifications and alerts.
---import { Button, Popover } from 'webcoreui/astro'---
<Button className="popover-trigger">Open Popover</Button>
<Popover className="popover"> <span>Display additional content...</span></Popover>
<script> import { popover } from 'webcoreui'
popover({ trigger: '.popover-trigger', popover: '.popover' })</script>
<script> import { onMount } from 'svelte' import { Button, Popover } from 'webcoreui/svelte' import { popover } from 'webcoreui'
onMount(() => { const popoverInstance = popover({ trigger: '.popover-trigger', popover: '.popover' })
return () => { popoverInstance.remove() } })</script>
<Button className="popover-trigger">Open Popover</Button>
<Popover className="popover"> <span>Display additional content...</span></Popover>
import React, { useEffect } from 'react'import { Button, Popover } from 'webcoreui/react'import { popover } from 'webcoreui'
const Component = () => { useEffect(() => { const popoverInstance = popover({ trigger: '.popover-trigger', popover: '.popover' })
return () => { popoverInstance.remove() } }, [])
return ( <React.Fragment> <Button className="popover-trigger">Open Popover</Button>
<Popover className="popover"> <span>Display additional content...</span> </Popover> </React.Fragment> )}
export default Component
To initialize the popover, call the popover
function with a trigger
and popover
property, where:
trigger
: References the trigger element through a query selector.trigger
: References thePopover
component through a query selector.
By default, the popover will appear under the trigger element with a 10px
margin-top
. To change the amount of margin, you can pass an offset
property to the popover
function:
popover({ trigger: '.popover-trigger', popover: '.popover', offset: 0})
popover({ trigger: '.popover-trigger', popover: '.popover', offset: 20})
Closing Functionality
Opened popovers can be closed by clicking again on the trigger element, clicking outside of the popover, or hitting Esc on the keyboard. This behavior can be configured using the closeOnBlur
and closeOnEsc
properties, and the closePopover
function:
---import { Button, Popover } from 'webcoreui/astro'import { popover } from 'webcoreui'---
<Button className="popover-trigger">Open Popover</Button>
<Popover className="popover"> <span>...</span> <Button theme="secondary" className="close">Close popover</Button></Popover>
<script> import { popover, closePopover } from 'webcoreui'
popover({ trigger: '.popover-trigger', popover: '.popover', closeOnBlur: false, closeOnEsc: false })
document.querySelector('.close').addEventListener('click', () => { closePopover('.popover') })</script>
<script> import { onMount } from 'svelte' import { Button, Popover } from 'webcoreui/svelte' import { popover, closePopover } from 'webcoreui'
onMount(() => { popover({ trigger: '.popover-trigger', popover: '.popover', closeOnBlur: false, closeOnEsc: false }) })</script>
<Button className="popover-trigger">Open Popover</Button>
<Popover className="popover"> <span>...</span> <Button theme="secondary" onClick={() => closePopover('.popover')}> Close popover </Button></Popover>
import React, { useEffect } from 'react'import { Button, Popover } from 'webcoreui/react'import { popover, closePopover } from 'webcoreui'
const Component = () => { useEffect(() => { popover({ trigger: '.popover-trigger', popover: '.popover', closeOnBlur: false, closeOnEsc: false }) }, [])
return ( <React.Fragment> <Button className="popover-trigger">Open Popover</Button>
<Popover className="popover"> <span>...</span> <Button theme="secondary" onClick={() => closePopover('.popover')}> Close popover </Button> </Popover> </React.Fragment> )}
export default Component
You can also destroy popovers if you want to disable them or remove the related event listeners when a component unmounts. To achieve this, assign the popover
function call to a variable, and call the remove
method on the variable. This will render the popover non-interactive.
// 1. Assign the popover to a variableconst popoverInstance = popover({ trigger: '.popover-trigger', popover: '.popover'})
// 2. On remove button click:closePopover('.popover')popoverInstance.remove()
// 3. Optionally disable trigger elementconst triggerElement = document.querySelector('.popover-trigger')
triggerButton.disabled = truetriggerButton.innerText = 'Popover disabled'
---import { Button, Popover } from 'webcoreui/astro'---
<Button className="popover-trigger">Open Popover</Button>
<Popover className="popover"> <span>...</span> <Button theme="alert" className="remove-popover"> Remove Popover </Button></Popover>
<script> import { popover, closePopover } from 'webcoreui'
const triggerButton = document.querySelector('.popover-trigger') const removeButton = document.querySelector('.remove-popover') const popoverInstance = popover({ trigger: '.popover-trigger', popover: '.popover' })
removeButton.addEventListener('click', () => { closePopover('.popover') popoverInstance.remove()
// Optionally disable trigger button triggerButton.disabled = true triggerButton.innerText = 'Popover disabled' })</script>
<script> import { onMount } from 'svelte' import { Button, Popover } from 'webcoreui/svelte' import { popover, closePopover } from 'webcoreui'
let popoverInstance let disabled = false let buttonText = 'Open Popover'
const remove = () => { closePopover('.popover') popoverInstance.remove()
// Optionally disable trigger button disabled = true buttonText = 'Popover disabled' }
onMount(() => { popoverInstance = popover({ trigger: '.popover-trigger', popover: '.popover' })
return () => { popoverInstance.remove() } })</script>
<Button className="popover-trigger" disabled={disabled}> {buttonText}</Button>
<Popover className="popover"> <span>...</span> <Button theme="alert" onClick={remove}> Remove Popover </Button></Popover>
import React, { useState, useEffect } from 'react'import { Button, Popover } from 'webcoreui/react'import { popover, closePopover } from 'webcoreui'
const Component = () => { const [disabled, setDisabled] = useState(false) const [buttonText, setButtonText] = useState('Open Popover')
let popoverInstance
const remove = () => { closePopover('.popover') popoverInstance.remove()
// Optionally disable trigger button setDisabled(true) setButtonText('Popover disabled') }
useEffect(() => { popoverInstance = popover({ trigger: '.popover-trigger', popover: '.popover' })
return () => { popoverInstance.remove() } }, [])
return ( <React.Fragment> <Button className="popover-trigger" disabled={disabled}> {buttonText} </Button>
<Popover className="popover"> <span>...</span> <Button theme="alert" onClick={remove}> Remove Popover </Button> </Popover> </React.Fragment> )}
export default Component
- Close the popover using the
closePopover
function. - Remove the popover instance using the
remove
method. - Optionally disable the trigger button to indicate that the popover has been removed.
Positions
The Popover
component also supports the following 12 different positions:
To change the position of the popover, specify the position
property:
popover({ trigger: '.popover-trigger', popover: '.popover', position: 'bottom'})
Popover Events
When calling the popover
function, you can also optionally pass an onOpen
and onClose
property to the configuration object to listen to open and close events:
popover({ trigger: '.popover-trigger', modal: '.popover', onOpen: ({ trigger, popover, position }) => { console.log('Popover opened') }, onClose: ({ trigger, modal, position }) => { console.log('Popover closed') }})
Both methods has access to an object with the following properties:
trigger
: The DOM node for the trigger element.popover
: The DOM node for thePopover
component.position
: The popover position.
JavaScript API
type PopoverPosition = 'top' | 'top-start' | 'top-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end' | 'bottom' | 'bottom-start' | 'bottom-end'
type PopoverCallback = { trigger: HTMLElement popover: HTMLElement position: PopoverPosition | undefined}
type Popover = { trigger: string popover: string offset?: number position?: PopoverPosition closeOnBlur?: boolean closeOnEsc?: boolean onOpen?: (args: PopoverCallback) => unknown onClose?: (args: PopoverCallback) => unknown}
const popover = (config: Popover) => { remove(): void}const closePopover = (selector: string) => void
Param | Default | Purpose |
---|---|---|
trigger | - | Pass a query selector for the trigger element. |
popover | - | Pass a query selector for the popover that should be triggered. |
offset | 10 | Sets the margin of the popover from the trigger element. |
position | bottom | Sets the position of the popover relative to the trigger element. |
closeOnBlur | true | Sets whether the popover should close when the user clicks outside of it. |
closeOnEsc | true | Sets whether the popover should close when the user clicks the Esc key. |
onOpen | - | Callback function executed after a popover is opened. |
onClose | - | Callback function executed after a popover is closed. |
type PopoverProps = { id?: string className?: string}
Prop | Purpose |
---|---|
id | Pass an ID for the popover. |
className | Pass additional CSS classes for the popover. |
Request improvement for this page