Usage
Via data attributes
<button
type="button"
class="inline-block rounded bg-danger px-7 pb-2.5 pt-3 text-sm font-medium uppercase leading-normal text-white shadow-danger-3 transition duration-150 ease-in-out hover:bg-danger-accent-300 hover:shadow-danger-2 focus:bg-danger-accent-300 focus:shadow-danger-2 focus:outline-none focus:ring-0 active:bg-danger-600 active:shadow-danger-2 dark:shadow-black/30 dark:hover:shadow-dark-strong dark:focus:shadow-dark-strong dark:active:shadow-dark-strong"
data-twe-toggle="popover"
data-twe-title="Popover title"
data-twe-content="And here's some amazing content. It's very engaging. Right?">
Click to toggle popover
</button>
Via JavaScript
const exampleEl = document.getElementById('example');
const popover = new Popover(exampleEl, options);
const exampleEl = document.getElementById('example');
const popover = new twe.Popover(exampleEl, options);
Making popovers work for keyboard and assistive technology users
To allow keyboard users to activate your popovers, you should only add
them to HTML elements that are traditionally keyboard-focusable and
interactive (such as links or form controls). Although arbitrary HTML
elements (such as
<span>s) can be made focusable by adding the
tabindex="0" attribute, this will add potentially annoying
and confusing tab stops on non-interactive elements for keyboard users,
and most assistive technologies currently do not announce the popover’s
content in this situation. Additionally, do not rely solely on
hover as the trigger for your popovers, as this will make
them impossible to trigger for keyboard users.
While you can insert rich, structured HTML in popovers with the
html option, we strongly recommend that you avoid adding an
excessive amount of content. The way popovers currently work is that, once
displayed, their content is tied to the trigger element with the
aria-describedby attribute. As a result, the entirety of the
popover’s content will be announced to assistive technology users as one
long, uninterrupted stream.
Additionally, while it is possible to also include interactive controls
(such as form elements or links) in your popover (by adding these elements
to the
allowList or allowed attributes and tags), be aware that
currently the popover does not manage keyboard focus order. When a
keyboard user opens a popover, focus remains on the triggering element,
and as the popover usually does not immediately follow the trigger in the
document’s structure, there is no guarantee that moving forward/pressing
TAB will move a keyboard user into the popover itself. In
short, simply adding interactive controls to a popover is likely to make
these controls unreachable/unusable for keyboard users and users of
assistive technologies, or at the very least make for an illogical overall
focus order. In these cases, consider using a modal dialog instead.
Options
Options can be passed via data attributes or JavaScript. For data
attributes, append the option name to data-twe-, as in
data-twe-content="your content".
Note: For security reasons the sanitize,
sanitizeFn and allowList options cannot be
supplied using data attributes.
|
Name
|
Type
|
Default
|
Description |
container
|
string/element/boolean
|
false
|
Appends the popover to a specific element. Example:
container: 'body'. This option is
particularly useful in that it allows you to position the
popover in the flow of the document near the triggering
element - which will prevent the popover from floating
away from the triggering element during a window resize.
|
content
|
string/element/function
|
-
|
Default content value if
data-twe-content attribute isn't present. If
a function is given, it will be called with its this
reference set to the element that the popover is attached
to.
|
html
|
boolean
|
false
|
Insert HTML into the popover. If false,
innerText property will be used to insert
content into the DOM. Use text if you're worried about XSS
attacks.
|
placement
|
string/function
|
'right'
|
How to position the popover - auto | top | bottom | left |
right. When auto is specified, it will
dynamically reorient the popover. When a function is used
to determine the placement, it is called with the popover
DOM node as its first argument and the triggering element
DOM node as its second. The this context is
set to the popover instance.
|
selector
|
string/boolean
|
false
|
If a selector is provided, popover objects will be
delegated to the specified targets. In practice, this is
used to enable dynamic HTML content to have popovers
added. See this and an informative example.
|
template
|
string
|
` <div class="opacity-0 transition-opacity
duration-150 ease-in-out absolute top-0 left-0 z-[1070]
block max-w-[267px] break-words bg-white bg-clip-padding
border border-neutral-100 rounded-lg shadow-2 text-sm
not-italic font-normal text-left no-underline
underline-offset-auto normal-case leading-6
tracking-normal break-normal whitespace-normal
dark:border-white/10 dark:bg-surface-dark
dark:text-white data-[popper-reference-hidden]:hidden"
role="tooltip"> <h3 data-twe-popover-header-ref
class="py-2 px-4 mb-0 border-b-2 border-neutral-100
rounded-t-lg font-medium empty:hidden
dark:border-white/10"></h3> <div
data-twe-popover-body-ref class="p-4 text-surface
dark:text-white"></div> </div> `
|
Base HTML to use when creating the popover. The popover's
title will be injected into the
.popover-header. The popover's content will
be injected into the .popover-body.
|
title
|
string/element/function
|
-
|
Default title value if title attribute isn't
present. If a function is given, it will be called with
its this reference set to the element that the popover is
attached to.
|
trigger
|
string
|
'click'
|
How popover is triggered - click |
hover | focus |
manual. You may pass multiple triggers;
separate them with a space. manual cannot be
combined with any other trigger.
|
offset
|
number/string
|
0
|
Offset of the popover relative to its target. For more
information refer to Popper's
offset docs.
|
fallbackPlacement
|
string/array
|
'flip'
|
Allow to specify which position Popper will use on
fallback. For more information refer to Popper's
behavior docs.
|
boundary
|
element/string
|
'clippingParents'
|
Overflow constraint boundary of the popover (applies only
to Popper's preventOverflow modifier). Accepts the values
of
'viewport', 'window',
'scrollParent', or an HTMLElement reference
(via JavaScript only). For more information refer to
Popper's
detectOverflow docs.
|
sanitize
|
boolean
|
true
|
Enable or disable the sanitization. If activated
'template', 'content' and
'title' options will be sanitized.
|
allowList
|
object
|
Default value
|
Object which contains allowed attributes and tags.
|
sanitizeFn
|
null/function
|
null
|
Here you can supply your own sanitize function. This can
be useful if you prefer to use a dedicated library to
perform sanitization.
|
popperConfig
|
null/object
|
{ hide: true }
|
To change Bootstrap's default Popper config, see
Popper's configuration.
|
Data attributes for individual popovers:
Options for individual popovers can alternatively be specified through
the use of data attributes, as explained above.
Methods
Asynchronous methods and transitions:
All API methods are asynchronous and start a
transition. They return to the caller as soon as the
transition is started but before it ends. In
addition, a method call on a
transitioning component will be ignored.
|
Method
|
Description
|
Example |
show
|
Reveals an element’s popover.
Returns to the caller before the popover has actually
been shown
(i.e. before the shown.twe.popover event
occurs). This is considered a “manual” triggering of the
popover. Popovers whose title and content are both
zero-length are never displayed.
|
myPopover.show()
|
hide
|
Hides an element’s popover.
Returns to the caller before the popover has actually
been hidden
(i.e. before the hidden.twe.popover event
occurs). This is considered a “manual” triggering of the
popover.
|
myPopover.hide()
|
toggle
|
Toggles an element’s popover.
Returns to the caller before the popover has actually
been shown or hidden
(i.e. before the shown.twe.popover or
hidden.twe.popover event occurs). This is
considered a “manual” triggering of the popover.
|
myPopover.toggle()
|
dispose
|
Hides and destroys an element’s popover. Popovers that use
delegation (which are created using the
selector option) cannot be individually
destroyed on descendant trigger elements.
|
myPopover.dispose()
|
enable
|
Gives an element’s popover the ability to be shown.
Popovers are enabled by default.
|
myPopover.enable()
|
disable
|
Removes the ability for an element’s popover to be shown.
The popover will only be able to be shown if it is
re-enabled.
|
myPopover.disable()
|
toggleEnabled
|
Toggles the ability for an element’s popover to be shown
or hidden.
|
myPopover.toggleEnabled()
|
update
|
Updates the position of an element’s popover.
|
myPopover.update({delay: { "show": 500, "hide": 100
}})
|
getInstance
|
Static method which allows you to get the popover instance
associated with a DOM element.
|
Popover.getInstance()
|
getOrCreateInstance
|
Static method which allows you to get the popover instance
associated with a DOM element or create a new one in case
it wasn't initialized.
|
Popover.getOrCreateInstance()
|
const exampleTriggerEl = document.getElementById('example');
const popover = new Popover(exampleTriggerEl);
popover.show();
const exampleTriggerEl = document.getElementById('example');
const popover = new twe.Popover(exampleTriggerEl);
popover.show();
Events
|
Event type
|
Description |
show.twe.popover
|
This event fires immediately when the
show instance method is called.
|
shown.twe.popover
|
This event is fired when the popover has been made
visible to the user (will wait for CSS transitions to
complete).
|
hide.twe.popover
|
This event is fired immediately when the
hide instance method has been called.
|
hidden.twe.popover
|
This event is fired when the popover has finished being
hidden from the user (will wait for CSS transitions to
complete).
|
inserted.twe.popover
|
This event is fired after the
show.twe.popover event when the popover
template has been added to the DOM.
|
const myPopoverTrigger = document.getElementById('myPopover')
myPopoverTrigger.addEventListener('hidden.twe.popover', () => {
// do something...
});