Popover

experimental

The Popover component is a wrapper for rich content that floats above other elements on the page. It is shown or hidden by interacting with a trigger element such as a button. Unlike a tooltip, it is usually triggered via click instead of hover, and it can contain interactive elements.

The component is implemented using the native Popover API.

Examples

Base

Usually the trigger for a popover is a <button> element. However, you can also use any other HTML element you like. By default, opening a popover will close any other open popovers and it can be closed by clicking outside the content. The behavior can be changed with the behavior property.

Accessibility Note:

If your trigger does not have a visible label, make sure to provide an accessible or visually hidden label for assistive technologies.

Accessibility Note:

You can use the aria-haspopup attribute on the trigger to indicate the type of the interactive popup that this element triggers, usually dialog or menu; this should match the role of the popover content. You can see all possible values here.

Show code

HTML

<section>
    <o-popover>
        <o-button> Open popover! </o-button>

        <template #content>
            <b>Lorem ipsum dolor sit amet</b>, consectetur warning elit.
            <i>Fusce id fermentum quam</i>.
            <o-icon icon="heart" variant="danger" />
        </template>
    </o-popover>
</section>

Position

The direction in which the popover opens can be explicity defined using the position property. By default, the direction is automatically calculated based on the distance to the edge of the window.

Additionally, adding the teleport property will move the content to the referenced DOM location instead of the current one.

Show code

HTML

<section class="odocs-spaced">
    <o-field>
        <o-switch v-model="teleport" label="Teleport to Body" />
    </o-field>

    <p>
        <o-popover position="right" :teleport="teleport">
            <o-button label="Right Popover" />

            <template #content>
                <h4 style="margin-top: 0">Heading</h4>
                <p>
                    Lorem ipsum dolor sit amet, consectetur warning elit.
                    Fusce id fermentum quam
                </p>
                <a href="#">Some Link</a>
            </template>
        </o-popover>

        <o-popover position="top" :teleport="teleport">
            <o-button label="Top Popover" />

            <template #content>
                <h4 style="margin-top: 0">Heading</h4>
                <p>
                    Lorem ipsum dolor sit amet, consectetur warning elit.
                    Fusce id fermentum quam
                </p>
                <a href="#">Some Link</a>
            </template>
        </o-popover>

        <o-popover position="bottom" :teleport="teleport">
            <o-button label="Bottom Popover" />

            <template #content>
                <h4 style="margin-top: 0">Heading</h4>
                <p>
                    Lorem ipsum dolor sit amet, consectetur warning elit.
                    Fusce id fermentum quam
                </p>
                <a href="#">Some Link</a>
            </template>
        </o-popover>

        <o-popover position="left" :teleport="teleport">
            <o-button label="Left Popover" />

            <template #content>
                <h4 style="margin-top: 0">Heading</h4>
                <p>
                    Lorem ipsum dolor sit amet, consectetur warning elit.
                    Fusce id fermentum quam
                </p>
                <a href="#">Some Link</a>
            </template>
        </o-popover>
    </p>
</section>

JS

import { ref } from "vue";

const teleport = ref(false);

Delay

The appearance of the content can be delayed using the delay property.

Show code

HTML

<section>
    <o-popover content="The content is shown after 1000ms" :delay="1000">
        <o-button label="Delayed" />
    </o-popover>
</section>

Closeable

Using closeable a close button can be added to the content.

Show code

HTML

<section>
    <o-popover closeable behavior="manual">
        <template #default="{ open }">
            <o-button @click="open"> Open popover! </o-button>
        </template>

        <template #content>
            <b>Lorem ipsum dolor sit amet</b>, consectetur warning elit.
            <i>Fusce id fermentum quam</i>.
            <o-icon icon="heart" variant="danger" />
        </template>
    </o-popover>
</section>

Backdrop

The the backdrop property allows a full-page overlay to be added to the top-layer of the page. By default, attempting to interact with the backdrop will close the popover.

Show code

HTML

<section>
    <o-popover backdrop>
        <o-button> Open popover! </o-button>

        <template #content>
            <b>Lorem ipsum dolor sit amet</b>, consectetur warning elit.
            <i>Fusce id fermentum quam</i>.
            <o-icon icon="heart" variant="danger" />
        </template>
    </o-popover>
</section>

Modal

When the modal property is added, the popover appears in the middle of the screen as a modal-style overlay with a full-page backdrop. The position property is ignored when the modal property is used.

Accessibility Note:

The popover modal style is mainly useful for improving the mobile experience. If you want to create a true modal, the ODialog element is the way to go.

Show code

HTML

<section>
    <o-popover modal>
        <o-button> Open popover! </o-button>

        <template #content>
            <b>Lorem ipsum dolor sit amet</b>, consectetur warning elit.
            <i>Fusce id fermentum quam</i>.
            <o-icon icon="heart" variant="danger" />
        </template>
    </o-popover>
</section>

Programmatically

This component provides a programmatic interface that can be accessed by the useOruga() composable. The composable can be used from outside of the Vue instance. For example, it can be used in Pinia or Vue Router with this syntax:

import { useOruga } from "@oruga-ui/oruga-next";
const oruga = useOruga();
oruga.popover.open({...});

The programmatic popover composable requires a trigger property in order to define the target element to which the popover will be attached to.

A programmatic instance returns a promise to await for. The promise gets resolved when the popover gets closed.

Show code

HTML

<section class="odocs-spaced">
    <p>
        <o-button
            label="Open Text Popover"
            size="medium"
            variant="primary"
            @click="openTextPopover()" />

        <o-button
            label="Open Image Popover"
            size="medium"
            variant="primary"
            @click="openImagePopover()" />
    </p>

    <div ref="target" style="background-color: var(--vp-c-brand-3)">
        Container with programmatic popover
    </div>
</section>

JS

import { h, useTemplateRef } from "vue";
import { useOruga } from "@oruga-ui/oruga-next";

const oruga = useOruga();

const target = useTemplateRef("target");

function openTextPopover(): void {
    oruga.popover.open(
        {
            // the target element the popover will be attached to
            target: target,
            content: "This overlay can have some usefull information.",
        },
        // placing target here again to mount the popover inside the target instead of body
        target,
    );
}

function openImagePopover(): void {
    // here we use a render function to create an dynamic inline component (https://vuejs.org/guide/extras/render-function)
    const vnode = h("img", {
        alt: "This is the Oruga Logo!",
        src: "https://avatars2.githubusercontent.com/u/66300512?s=200&v=4",
    });

    oruga.popover.open({
        target: target,
        position: "bottom",
        backdrop: true,
        component: vnode,
    });
}

Popover Component

A popover is a content container that displays rich content over the top of other content.

<o-popover></o-popover>

Props

Prop name	Description	Type	Values	Default
active	Whether popover is active or not, use v-model:active to make it two-way binding	boolean	-	false
animation	Show and dismiss animation	string	-	From config: popover: {   animation: "fade" }
ariaCloseLabel	Accessibility label for the close button	string	-	From config: popover: {   ariaCloseLabel: "Close" }
backdrop	Adds a backdrop to the background	boolean	-	false
behavior	The behavior of the popover.	"auto" | "hint" | "manual"	auto, hint, manual	"auto"
clipScroll	Set true to remove the body scrollbar. When false, a non-scrollable scrollbar will be kept to avoid moving the background, but will set the body to a fixed position, which may break some layouts.	boolean	-	From config: popover: {   clipScroll: false }
closeIcon	Close icon name	string	-	From config: popover: {   closeIcon: "close" }
closeIconSize	Close icon size	string	-	From config: popover: {   closeIconSize: undefined }
closeable	Adds close button to the content	boolean	-	From config: popover: {   closeable: false }
component	Component to be injected. Close the component by emitting a 'close' event — $emit('close')	C	-
content	Content body text, unnecessary when content slot is used	string	-
delay	Defines a delay (in ms) before the content appears	number	-
disabled	The component will be disabled	boolean	-	false
events	Events to be binded to the injected component	EmitsToProps<ComponentEmit<C>>	-
iconPack	Icon pack to use for the close icon	string	mdi, fa, fas and any other custom icon pack	From config: popover: {   iconPack: undefined }
id	A unique HTML id for the popover element	string	-	useId()
modal	Defines if the popover should be shown as centered modal - the position is ignored when true	boolean	-	false
override	Override existing theme classes completely	boolean	-
position	The position of the popover relative to the trigger	PopoverPosition	top, bottom, left, right, center, [top, right], [top, left], [bottom, left], [bottom, right]	From config: popover: {   position: "top" }
props	Props to be binded to the injected component	ComponentProps<C>	-
role	A role for the content element.	"dialog" | "menu" | "tooltip"	-
target	Define the target element to which the popover gets connected programmatically.	MaybeElement	-
teleport	Append the component to another part of the DOM. Set true to append the component to the body. In addition, any CSS selector string or an actual DOM node can be used.	boolean | object | string	-	From config: popover: {   teleport: false }
title	Content header title, unnecessary when title slot is used	string	-

Events

Event name	Properties	Description
update:active	value boolean - updated active prop	active prop two-way binding
close	event Event - native event	on active state changes to false
open	event Event - native event	on active state changes to true

Slots

Name	Description	Bindings
default	Define a trigger here	active boolean - popover active state open (): void - function to open the popover
title	Override the popover title, default is title prop	close (): void - function to close the popover
close	Define a custom close icon
content	Override the popover content, default is content prop	close (): void - function to close the popover

Class Inspector

Classes applied to the element:

➜ Want to know how does the Class Inspector work?

Class props inspector is useful to see class props you want to use to customize Oruga components and how they change a component. You can click on Inspect button to find the exact element where a specific class prop acts.

In the Class props inspector there are other columns:

Class prop

This column contains the name of the Class prop you want to inspect.
If you find a name with a link ( ▷ classPropName) this refers to a subitem (e.g. Dropdown Item in Dropdown).

Description

This column contains the description of the Class prop you want to inspect.
👉 This icon indicates some warning, e.g. this Class prop is visible only on mobile.

Props

This column contains a list of props that activate the class, e.g. if a class prop contains disabled prop it means that only when the component has disabled prop.

Suffixes

This column contains all the possible suffixes that you'll receive if you use a function to customize your Class prop.

Class prop	Description	Props	Suffixes
rootClass	Class of the root element.
disabledClass	Class of the root element when disabled.	disabled
activeClass	Class of the root element when active.	active
teleportClass	Class of the root element when teleported.	teleport
contentClass	Class of the content element.
contentActiveClass	Class of the content element when active.	active
contentModalClass	Class of the content element when shown as modal.	modal
contentBackdropClass	Class of the content when should has a backdrop.	modal
headerClass	Class of the content header element.	title
bodyClass	Class of the content body element.
closeClass	Class of the close element.
scrollClipClass	Class of the body when is open and scroll is clipped.	clipScroll
scrollKeepClass	Class of the body when is open and scroll is keeped.	clipScroll

Sass Variables

Current theme ➜ Oruga

The theme does not have any custom variables for this component.

Current theme ➜ Bulma

The theme does not have any custom variables for this component.

Current theme ➜ Bootstrap

The theme does not have any custom variables for this component.