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.

Preview

---
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 the Popover 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:

0 offset

20px offset

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 variable
const popoverInstance = popover({
    trigger: '.popover-trigger',
    popover: '.popover'
})

// 2. On remove button click:
closePopover('.popover')
popoverInstance.remove()

// 3. Optionally disable trigger element
const triggerElement = document.querySelector('.popover-trigger')

triggerButton.disabled = true
triggerButton.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'
})

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 the Popover 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.

<- Pagination Progress ->

Request improvement for this page

Popover

Closing Functionality

Positions

Popover Events

JavaScript API