Banquette

A popover is a floating component that sticks to another element. It can be used to make tooltips for example.

Basic usage

There are two ways of creating a popover:

using the bt-popover component,
using the v-bt-popover directive.

As a directive

The easiest way to show a popover is through the directive:

<bt-icon name="home" v-bt-popover="'I\'m above the icon'"></bt-icon>

WARNING

Please note that the string is quoted. Because the directive expects an expression.

<bt-icon v-bt-popover="'I\'m above the icon'"></bt-icon> <!-- Works -->
<bt-icon v-bt-popover="I'm above the icon"></bt-icon>    <!-- Does NOT work -->

You can also give it an object of options:

<bt-icon name="home" v-bt-popover="{content: 'I\'m on the left of the icon', placement: 'left'}"></bt-icon>

As a component

Popovers can also be create via the bt-popover component:

<bt-button name="home">
    Hover me
    <bt-popover placement="right">
        <span>My content comes <b>from a slot</b>.</span>
    </bt-popover>
</bt-button>

Placement

Popovers rely on PopperJSopen in new window, so you can use any of the placement it supports:

NOTE

Please check out this section that covers Popper's configuration.

Target

The target of a popover is the element it will stick to.

If the popover is created through a directive, the target cannot be changed. It will always be the element on which the directive has been put onto.

But if the popover is created through a bt-popover component, you can control the target via the target prop. The target can be changed dynamically, as demonstrated below:

TIP

The target can either be:

an element: any HTML element,
a ref (as in the demo): the popover will search all the parents for the ref,
a css selector: anything querySelectoropen in new window can take. Please note that the matching is performed on the parent element for anything that is not an id. If the selector starts with # the match is done on the whole document.

Multiple targets

A popover can target multiple elements.

Interactive

You can prevent the popover from disappearing when the user mouse leaves the target element by adding a interactive prop:

Teleport

By default, the popover spawn where the component is defined. But it can create problems if the container is too small to contain it. In such a case, you can teleport it elsewhere using the teleport prop. Here is a demo to illustrate:

TIP

The teleport prop is directly passed to the to prop of Teleportopen in new window component.

Visibility control

By default, the popover visibility is controlled by events on its target. The popover is shown when the target is hovered.

But you can change this behavior using the showOn and hideOn props.

Show on

Controls the type of event that make the popover visible, possible values are:

mouseenter: show the popover when the mouse enters one of its targets,
click: show the popover when a click is made on one of its targets,
focus: show the popover when one of its targets takes focus.

Hide on

Controls the type of event that make the popover hide, possible values are:

mouseleave: automatically set when showOn is set to hover and hideOn is null
click: hide the popover when clicking on the target
click-outside: hide the popover when clicking outside of any of its targets
mousedown-outside: hide the popover when a mousedown event is triggered outside of any of its targets
blur: hide the popover on the blur event of the focused target

TIP

If no value is set to hideOn, an inverse event will automatically be set for each possible value of showOn:

for hover, the inverse is mouseleave,
for click, the inverse is click-outside,
for focus, the inverse is blur.

Manual control

You can also control the visibility yourself, via the visible prop (null by default).

If visible is set to a non-null value, it takes priority on the showOn and hideOn props discussed above, which become useless.

<bt-popover :visible="true">
    I'll always be visible.
</bt-popover>

Content rendering

By default, the content of a popover is only rendered when it is shown, and destroyed when hidden. But in some cases you may when to render it all the time, even when hidden.

You can control this via the render-hidden prop:

<bt-popover render-hidden>
    My content will always be rendered.
</bt-popover>

As you can see with the little increment component inside the popover is reset each time the popover is shown in one case and not on the other.

Delay

You can delay the appearance and disappearance of the popover via the showDelay and hideDelay props. They expect a number of milliseconds to wait.

PopperJS

Popovers rely on PopperJSopen in new window for their placement. Several props are shortcuts to Popper's configuration.

Placement

The placement prop is directly passed to Popper with no change. It is covered here.

<bt-popover placement="bottom-end">...</bt-popover>

Show arrow

Adds the arrow modifier to the Popper config if true (default behavior).

See Popper's documentationopen in new window.

Offset

Adds the offset modifier if non-null. Set to [0, 10] by default.

See Popper's documentationopen in new window.

Default configuration

The following modifiers are applied by default:

{
    placement: /** `placement prop */,
    modifiers: [
        {
            name: 'preventOverflow',
            options: {altAxis: true}
        },
        {
            name: 'computeStyles',
            options: {adaptive: false}
        },
        // Only if the `offset` prop is defined.
        {
            name: 'offset',
            options: {offset: /** `offset` prop */}
        },
        // Only if `showArrow` is `true`.
        {
            name: "arrow",
            options: {padding: 10}
        }
    ]
}

Custom configuration

You can override the default configuration via the popperOptions prop:

<bt-popover :popper-options="{strategy: 'fixed'}"></bt-popover>

WARNING

Please note that the configuration is not merged recursively, so you can remove default modifiers.

This means that doing:

<bt-popover :popper-options="{modifiers: []}"></bt-popover>

will remove all the default modifiers.

Props

Method	Description	Default
target	Custom target element.	`null`
content	Content of the popover. Use the `default` slot if not defined.	`null`
allow-html	If `true`, the HTML containing in the `content` prop will be interpreted.	`false`
placement	PopperJS placement of the popover relative to its target.	`'top'`
show-arrow	If `true`, show the arrow.	`true`
visible	Control the visibility of the popover. If `null` (the default behavior), the visibility is controlled by events sets on the targets elements. These events can be configured using the `showOn` and `hideOn` props. Note that this prop takes priority over every other way to show/hide the popover. Meaning that if visible is `true` for example, calling hide() will do nothing.	`null`
show-on	Defines the type of event listeners to add on the targets to make the popover visible. Possible values are: `mouseenter`: will show the popover when the mouse enters one of its targets, `click`: will show the popover when a click is made on one of its targets, `focus`: will show the popover when one of its targets take the focus. If no value is set to `hide-on`, an inverse event will automatically be set for each on the above, to hide the popover: `mouseenter`: will set a `mouseleave` event as well, `click`: will toggle the popover and hide the popover when clicking outside it, `focus`: will set `blur` event as well.	`mouseenter`
hide-on	Defines the type of event listeners to add on the targets to make the popover disappear. Possible values are: `mouseleave`: automatically set when `show-on` is set to `mouseenter` and `hide-on` is `null`, `click`: hide the popover when clicking on the target, `click-outside`: hide the popover when clicking outside any of its targets, `mousedown-outside`: hide the popover when a mousedown event is triggered outside any of its targets, `blur`: hide the popover on the `blur` event of the focused target.	`null`
show-delay	Time to wait in milliseconds before showing the popover when its visibility becomes `true` through a DOM event.	`0`
hide-delay	Time to wait in milliseconds before hiding the popover when its visibility becomes `false` through a DOM event.	`{mouseleave: 200}`
interactive	If `true`, the popover will remain visible while the mouse is over its content.	`false`
flip	Enable/disable the `flip` modifier of Popper.	`true`
prevent-overflow	Enable/disable the `preventOverflow` modifier of Popper.	`true`
compute-styles	Enable/disable the `computeStyles` modifier of Popper.	`true`
teleport	An HTML element or selector to teleport the popover into. If set to `'auto'`, the popover will automatically teleport to the body it a parent with an `overflow: hidden` is found.	`'auto'`
z-index	The z-index to apply on the floating element.	`'auto'`
offset	To translate the popover from its original position. Example: `[20, 0]`: The popper is offset 20px along the reference, `[0, 20]`: The popper is offset 20px away from the reference, `20`: translates to [0, 20].	`[0, 10]`
popper-options	Custom options object directly passed to PopperJS. Beware, internal modifiers will be overridden if defined here, making the following props inoperative: `showArrow`, `offset`.	`null`
transition	If `false` the popover will use not use the Transitionopen in new window component for its transitions, If a `string` is given, it will be used as the name of the transition to apply, `undefined` will use the default transition.	`undefined`
render-hidden	If `true` the dropdown content is always rendered, even when hidden.	`false`

Slots

Name Description

Name	Description
default	Contain the content of the popover. If not defined, the `content` prop is used instead. Props: none

default

Contain the content of the popover. If not defined, the content prop is used instead.

Props: none

Theming

Below the list of all CSS variables and selectors available to customize the appearance of the component. If you're not familiar on how the theming works, please refer to the VueThemes documentation.

Variables

Variable	Default	Comment
fontFamily	`var(--bt-font-family-base)`	-
fontSize	`var(--bt-font-size-sm)`	-
fontWeight	`var(--bt-font-weight-medium)`	-
textColor	`var(--bt-text-color-white)`	-
backgroundColor	`var(--bt-color-gray-800)`	-
borderColor	`var(--bt-color-gray-800)`	-
borderStyle	`var(--bt-border-style-base)`	-
borderWidth	`var(--bt-border-width-base)`	-
borderRadius	`var(--bt-border-radius-base)`	-
zIndex	`var(--bt-z-index-popover)`	-
shadow	`var(--bt-shadow-popover)`	-

Selectors

Name	Comment
root	The content container.
arrow	The arrow.

Examples:

cssSelectors: {
    root: {
        background: '...'
    },
    arrow: {
        background: '...'
    }
}

# Popover

# Basic usage

# As a directive

# As a component

# Placement

# Target

# Multiple targets

# Interactive

# Teleport

# Visibility control

# Show on

# Hide on

# Manual control

# Content rendering

# Delay

# PopperJS

# Placement

# Show arrow

# Offset

# Default configuration

# Custom configuration

# Props

# Slots

# Theming

# Variables

# Selectors

Popover

Basic usage

As a directive

As a component

Placement

Target

Multiple targets

Interactive

Teleport

Visibility control

Show on

Hide on

Manual control

Content rendering

Delay

PopperJS

Placement

Show arrow

Offset

Default configuration

Custom configuration

Props

Slots

Theming

Variables

Selectors