Popovers

Popovers provide brief, contextual information or actions when users hover, focus, or click on an element.

Popovers use the Popper library for dynamic positioning and viewport detection. Include popper.min.js before Hummingbird’s JavaScript, or use hummingbird.bundle.min.js / hummingbird.bundle.js, which include Popper. See the dependencies section for more details.

Popover components integrate Bootstrap's JavaScript plugins for interactivity, paired with custom styling for a unique and consistent user experience.

Class Name	Type	Description
popover	Component	Popover component
popover-header	Inner	Popover header
popover-body	Inner	Popover body
popover-arrow	Inner	Popover arrow

Basic example

Add a popover to an element by adding the data-bs-toggle="popover" attribute. Set popover content with the data-bs-content attribute.

HTML

<button type="button" class="btn btn-subtle-neutral" data-bs-toggle="popover" data-bs-content="Here’s some exciting content to explore and enjoy.">Toggle basic popover</button>

Directions

Popovers can be placed in different directions: top, right, bottom, and left. Use the data-bs-placement attribute to specify the placement.

HTML

<button type="button" class="btn btn-subtle-neutral" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="top" data-bs-content="Top popover">
  Popover on top
</button>
<button type="button" class="btn btn-subtle-neutral" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="right" data-bs-content="Right popover">
  Popover on right
</button>
<button type="button" class="btn btn-subtle-neutral" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="bottom" data-bs-content="Bottom popover">
  Popover on bottom
</button>
<button type="button" class="btn btn-subtle-neutral" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="left" data-bs-content="Left popover">
  Popover on left
</button>

Add a title to your popover by using the data-bs-title attribute.

HTML

<button type="button" class="btn btn-subtle-neutral" data-bs-toggle="popover" data-bs-title="Popover title" data-bs-content="Here’s some exciting content to explore and enjoy.">Toggle basic popover</button>

Custom container

If parent element styles interfere with a popover, specify a custom container so the popover’s HTML is rendered within that element. This is useful for responsive tables, input groups, and similar layouts.

const popover = new hummingbird.Popover('.example-popover', {
  container: 'body'
})

When using popovers inside a modal dialog, set a custom container to ensure the popover is appended to the modal. This is important for interactive elements, as modals trap focus, preventing users from interacting with popovers outside the modal.

const popover = new hummingbird.Popover('.example-popover', {
  container: '.modal-body'
})

Custom popovers

Popovers can be customized using CSS variables. Assign a custom class with data-bs-custom-class="custom-popover" to scope styles, and override specific CSS variables for a unique appearance.

.custom-popover {
  --popover-max-width: 15rem;
  --popover-border-color: var(--color-info);
  --popover-header-bg: var(--color-info);
  --popover-header-color: var(--color-contrast);
  --popover-body-padding-x: --spacing(4);
  --popover-body-padding-y: --spacing(3);
}

HTML

<button type="button" class="btn btn-subtle-info"
  data-bs-toggle="popover" data-bs-placement="right"
  data-bs-custom-class="custom-popover"
  data-bs-title="Custom popover"
  data-bs-content="This popover is themed via CSS variables.">
  Custom popover
</button>

Dismiss on next click

Use focus to close the popover upon the next click outside the toggle element.

Dismissible popover

HTML

<a tabindex="0" class="btn btn-subtle-danger" role="button" data-bs-toggle="popover" data-bs-trigger="focus" data-bs-title="Dismissible popover" data-bs-content="Here’s some exciting content to explore and enjoy.">Dismissible popover</a>

const popover = new hummingbird.Popover('.popover-dismiss', {
  trigger: 'focus'
})

Disabled elements

Disabled elements can’t trigger popovers since they’re non-interactive. To enable popovers, wrap them in a focusable <div> or <span> with tabindex="0". For better feedback, use data-bs-trigger="hover focus" so the popover appears on hover or focus instead of click on a disabled element.

HTML

<span class="inline-block" tabindex="0" data-bs-toggle="popover" data-bs-trigger="hover focus" data-bs-content="Disabled popover">
  <button class="btn btn-primary" type="button" disabled>Disabled button</button>
</span>

CSS variables

Popover components utilize several CSS variables for customization. Below is a list of available CSS variables that can be overridden to modify the appearance of popovers:

.popover {
  --popover-zindex: 1070;
  --popover-max-width: 16rem;
  --popover-font-size: var(--text-sm);
  --popover-bg: var(--background-color-default);
  --popover-border-width: 1px;
  --popover-border-color: var(--border-color-light);
  --popover-border-radius: var(--radius-lg);
  --popover-box-shadow: var(--shadow-xl);
  --popover-header-padding-x: --spacing(4);
  --popover-header-padding-y: --spacing(3);
  --popover-margin: --spacing(2);
  --popover-header-font-size: var(--text-base);
  --popover-header-color: var(--text-color-default);
  --popover-header-bg: var(--background-color-default);
  --popover-body-padding-x: --spacing(4);
  --popover-body-padding-y: --spacing(3);
  --popover-body-color: var(--text-color-default);
  --popover-arrow-width: 0.85rem;
  --popover-arrow-height: 0.62rem;
  --popover-arrow-border-radius: --spacing(0.5);
  --popover-arrow-border-color: var(--popover-border-color);
}

Usage

Enable popovers via JavaScript:

const exampleEl = document.getElementById('example');
const popover = new hummingbird.Popover(exampleEl, options);

Popovers should only be attached to keyboard focusable and interactive HTML elements like links or form control for optimal accessibility. While other elements can be made focusable by adding tabindex="0", this practice can create confusing tab stops for keyboard users, and most assistive technologies do not announce popovers in this situation. Furthermore, relying solely on hover as the trigger is discouraged, as this makes popovers impossible to trigger for keyboard users.

Excessive content within popovers should be avoided when using the html option. When displayed, a popover’s content is tied to the trigger element with the aria-describedby attribute. This causes the entire content to be announced to assistive technology users as one long, uninterrupted stream.

Popovers do not manage keyboard focus order. Their placement in the DOM can be random, so adding interactive elements like forms or links requires careful consideration, as it may lead to an illogical focus order or render the popover’s content unreachable for keyboard users. In these cases, a modal dialog is often a more appropriate and accessible solution.

Options

Options can be passed via data attributes or JavaScript. To pass an option via a data attribute, append its name to data-bs-, as in data-bs-animation="{value}". When passing options as data attributes, the option name’s case type must be converted from “camelCase” to “kebab-case”. For example, data-bs-custom-class="beautifier" is used instead of data-bs-customClass="beautifier".

All components support an experimental reserved data attribute, data-bs-config, which can house simple component configuration as a JSON string. When an element has both data-bs-config='{"delay":0, "title":123}' and data-bs-title="456" attributes, the final title value will be 456, as separate data attributes will override values given on data-bs-config. Additionally, existing data attributes are able to house JSON values, such as data-bs-delay='{"show":0,"hide":150}'.

The final configuration object is the merged result of data-bs-config, data-bs-, and the JavaScript object, where the latest given key-value pair overrides the others.

Note: For security reasons, the sanitize, sanitizeFn, and allowList options cannot be supplied using data attributes.

Name	Type	Default	Description
`allowList`	object	Default value	An object of allowed tags and attributes. Those not explicitly allowed will be removed. Caution should be exercised when modifying this list.
`animation`	boolean	`true`	Applies a CSS fade transition to the popover.
`boundary`	string, element	`'clippingParents'`	The overflow constraint boundary of the popover. Accepts an HTMLElement reference (via JavaScript only).
`container`	string, element, false	`false`	Appends the popover to a specific element. Example: `container: 'body'`. This prevents the popover from detaching from the trigger element during a window resize.
`content`	string, element, function	`''`	The popover’s text content. If a function is given, its `this` context is set to the attachment element.
`customClass`	string, function	`''`	Adds classes to the popover when shown. Multiple classes can be separated by spaces. A function can also be passed to return a string of class names.
`delay`	number, object	`0`	Delay for showing and hiding in milliseconds (ms). Does not apply to the manual trigger type. If a number is supplied, it applies to both `hide/show`. An object can be structured as: `delay: { "show": 500, "hide": 100 }`
`fallbackPlacements`	string, array	`['top', 'right', 'bottom', 'left']`	Defines fallback placements by providing an ordered array of preferences.
`html`	boolean	`false`	Allows HTML in the popover. If true, HTML tags are rendered. If false, the `innerText` property is used. Prefer text when dealing with user-generated input to prevent XSS attacks.
`offset`	number, string, function	`[0, 8]`	The popover’s offset relative to its target. A string with comma-separated values can be passed via data attributes (e.g., `data-bs-offset="10,20"`).
`placement`	string, function	`'right'`	How to position the popover: auto, top, bottom, left, right. `auto` dynamically reorients the popover.
`popperConfig`	null, object, function	`null`	Used to change Hummingbird’s default Popper configuration. A function can be used to merge the default configuration with a custom one.
`sanitize`	boolean	`true`	Enables content sanitization for the template, content, and title options. Disabling sanitization should be done with caution.
`sanitizeFn`	null, function	`null`	Provides an alternative content sanitization function, allowing the use of a dedicated sanitization library.
`selector`	string, false	`false`	If a selector is provided, popover objects are delegated to the specified targets. This is useful for applying popovers to dynamically added DOM elements.
`template`	string	`'<div class="popover" role="tooltip"><div class="popover-arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>'`	The base HTML used to create the popover. The `.popover` class and `role="tooltip"` are required on the outermost element.
`title`	string, element, function	`''`	The popover title. If a function is given, its `this` context is set to the attachment element.
`trigger`	string	`click`	How the popover is triggered: click, hover, focus, manual. Multiple triggers can be passed, separated by a space. manual cannot be combined with other triggers.

Methods

All API methods are asynchronous and initiate a transition. They return to the caller as soon as the transition starts but before it ends. Method calls on a transitioning component will be ignored.

Method	Description
`disable`	Removes the ability for a popover to be shown. It must be re-enabled to be shown again.
`dispose`	Hides and destroys an element’s popover, removing stored data from the DOM element.
`enable`	Gives a popover the ability to be shown. Popovers are enabled by default.
`getInstance`	A static method that retrieves the popover instance associated with a DOM element.
`getOrCreateInstance`	A static method that retrieves the popover instance for a DOM element, or creates a new one if it wasn’t initialized.
`hide`	Hides an element’s popover. This is considered a “manual” trigger.
`setContent`	Provides a method for changing a popover’s content after its initialization. Accepts an object where keys are selectors within the template.
`show`	Reveals an element’s popover. This is considered a “manual” trigger. Popovers with zero-length title and content are never displayed.
`toggle`	Toggles an element’s popover. This is considered a “manual” trigger.
`toggleEnabled`	Toggles the ability for a popover to be shown or hidden.
`update`	Updates the position of an element’s popover.

The setContent method takes an object as an argument. Each property-key is a valid string option in the popover template, and each property-value can be a string | element | function | null.

Events

Event	Description
`hide.bs.popover`	This event is fired immediately when the hide instance method has been called.
`hidden.bs.popover`	This event is fired when the popover has finished being hidden (waits for CSS transitions to complete).
`inserted.bs.popover`	This event is fired after the `show.bs.popover` event when the template has been added to the DOM.
`show.bs.popover`	This event fires immediately when the `show` instance method is called.
`shown.bs.popover`	This event is fired when the popover has been made visible (waits for CSS transitions to complete).

hummingbird

Getting Started

Customize

Layout & content

Forms

Advanced Forms

Components

Popovers

Basic example

Directions

Popover with title

Custom container

Custom popovers

Dismiss on next click

Disabled elements

CSS variables

Usage

Options

Methods

Events