View as Markdown
Tooltip
A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it.
Loading...
<twig:Tooltip id="tooltip-demo">
<twig:Tooltip:Trigger>
<twig:Button {{ ...tooltip_trigger_attrs }} variant="outline">Hover</twig:Button>
</twig:Tooltip:Trigger>
<twig:Tooltip:Content>
<p>Add to library</p>
</twig:Tooltip:Content>
</twig:Tooltip>
Installation
php bin/console ux:install tooltip --kit shadcn
Install the following Composer dependencies:
composer require twig/extra-bundle twig/html-extra:^3.24.0 tales-from-a-dev/twig-tailwind-extra:^1.0.0 symfony/ux-twig-component:^3.1
Copy the following file(s) into your app:
import { Controller } from '@hotwired/stimulus';
export default class extends Controller {
static values = {
delayDuration: Number,
// Using targets does not work if the elements are moved in the DOM (document.body.appendChild)
// and using outlets does not work either if elements are children of the controller element.
wrapperSelector: String,
contentSelector: String,
arrowSelector: String,
};
static targets = ['trigger', 'wrapper'];
connect() {
this.initialized = false;
this.wrapperElement = document.querySelector(this.wrapperSelectorValue);
this.contentElement = document.querySelector(this.contentSelectorValue);
this.arrowElement = document.querySelector(this.arrowSelectorValue);
if (!this.wrapperElement || !this.contentElement || !this.arrowElement) {
return;
}
this.side = this.wrapperElement.getAttribute('data-side') || 'top';
this.sideOffset = parseInt(this.wrapperElement.getAttribute('data-side-offset'), 10) || 0;
this.showTimeout = null;
this.hideTimeout = null;
this.dismiss = this.hide.bind(this);
document.body.appendChild(this.wrapperElement);
this.initialized = true;
}
disconnect() {
this.#clearTimeouts();
this.#removeDismissListeners();
if (this.wrapperElement && this.wrapperElement.parentNode === document.body) {
this.element.appendChild(this.wrapperElement);
}
}
wrapperTargetConnected() {
// This case appear when live component rerender.
// Because original wrapper is moved on body, the Smart rerender algorithm recreate a new wrapper.
if (this.wrapperElement) {
this.wrapperElement.remove();
this.connect();
}
}
show() {
if (!this.initialized) {
return;
}
this.#clearTimeouts();
const delay = this.hasDelayDurationValue ? this.delayDurationValue : 0;
this.showTimeout = setTimeout(() => {
this.wrapperElement.setAttribute('open', '');
this.contentElement.setAttribute('open', '');
this.arrowElement.setAttribute('open', '');
this.#positionElements();
// The tooltip is portaled to <body> and positioned absolutely, so it cannot follow
// the trigger on scroll. Dismiss it instead (capture scrolls from any scroller).
window.addEventListener('scroll', this.dismiss, true);
window.addEventListener('resize', this.dismiss);
this.showTimeout = null;
}, delay);
}
hide() {
if (!this.initialized) {
return;
}
this.#clearTimeouts();
this.#removeDismissListeners();
this.wrapperElement.removeAttribute('open');
this.contentElement.removeAttribute('open');
this.arrowElement.removeAttribute('open');
}
#removeDismissListeners() {
window.removeEventListener('scroll', this.dismiss, true);
window.removeEventListener('resize', this.dismiss);
}
#clearTimeouts() {
if (this.showTimeout) {
clearTimeout(this.showTimeout);
this.showTimeout = null;
}
if (this.hideTimeout) {
clearTimeout(this.hideTimeout);
this.hideTimeout = null;
}
}
#positionElements() {
const triggerRect = this.triggerTarget.getBoundingClientRect();
const contentRect = this.contentElement.getBoundingClientRect();
const arrowRect = this.arrowElement.getBoundingClientRect();
let wrapperLeft = 0;
let wrapperTop = 0;
let arrowLeft = null;
let arrowTop = null;
switch (this.side) {
case 'left':
wrapperLeft = triggerRect.left - contentRect.width - arrowRect.width / 2 - this.sideOffset;
wrapperTop = triggerRect.top - contentRect.height / 2 + triggerRect.height / 2;
arrowTop = contentRect.height / 2 - arrowRect.height / 2;
break;
case 'top':
wrapperLeft = triggerRect.left - contentRect.width / 2 + triggerRect.width / 2;
wrapperTop = triggerRect.top - contentRect.height - arrowRect.height / 2 - this.sideOffset;
arrowLeft = contentRect.width / 2 - arrowRect.width / 2;
break;
case 'right':
wrapperLeft = triggerRect.right + arrowRect.width / 2 + this.sideOffset;
wrapperTop = triggerRect.top - contentRect.height / 2 + triggerRect.height / 2;
arrowTop = contentRect.height / 2 - arrowRect.height / 2;
break;
case 'bottom':
wrapperLeft = triggerRect.left - contentRect.width / 2 + triggerRect.width / 2;
wrapperTop = triggerRect.bottom + arrowRect.height / 2 + this.sideOffset;
arrowLeft = contentRect.width / 2 - arrowRect.width / 2;
break;
}
this.wrapperElement.style.transform = `translate3d(${wrapperLeft}px, ${wrapperTop}px, 0)`;
if (arrowLeft !== null) {
this.arrowElement.style.left = `${arrowLeft}px`;
}
if (arrowTop !== null) {
this.arrowElement.style.top = `${arrowTop}px`;
}
}
}
{# @prop id string Unique identifier for the tooltip. #}
{# @prop delayDuration number Delay in milliseconds before showing the tooltip. #}
{# @block content The tooltip structure, typically includes `Tooltip:Trigger` and `Tooltip:Content`. #}
{%- props id, delayDuration = 0 -%}
{%- set _tooltip_id = id -%}
{%- set _tooltip_trigger_id = id ~ '_trigger' -%}
{%- set _tooltip_wrapper_id = id ~ '_wrapper' -%}
{%- set _tooltip_content_id = id ~ '_content' -%}
{%- set _tooltip_arrow_id = id ~ '_arrow' -%}
{%- set _tooltip_delay_duration = delayDuration -%}
{%- do provide('tooltip.triggerId', _tooltip_trigger_id) -%}
{%- do provide('tooltip.wrapperId', _tooltip_wrapper_id) -%}
{%- do provide('tooltip.contentId', _tooltip_content_id) -%}
{%- do provide('tooltip.arrowId', _tooltip_arrow_id) -%}
<div
class="{{ ('relative inline-block ' ~ attributes.render('class'))|tailwind_merge }}"
{{ attributes.defaults({
id: _tooltip_id,
'data-slot': 'tooltip',
'data-controller': 'tooltip',
'data-tooltip-delay-duration-value': _tooltip_delay_duration,
'data-tooltip-wrapper-selector-value': '#' ~ _tooltip_wrapper_id,
'data-tooltip-content-selector-value': '#' ~ _tooltip_content_id,
'data-tooltip-arrow-selector-value': '#' ~ _tooltip_arrow_id,
}) }}
>
{%- block content %}{% endblock -%}
</div>
{# @prop side 'top'|'right'|'bottom'|'left' The preferred side to display the tooltip. #}
{# @prop sideOffset number The distance in pixels from the trigger. #}
{# @block content The tooltip text or content. #}
{%- props side = 'top', sideOffset = 0 -%}
{%- set _tooltip_wrapperId = inject('tooltip.wrapperId') -%}
{%- set _tooltip_contentId = inject('tooltip.contentId') -%}
{%- set _tooltip_arrowId = inject('tooltip.arrowId') -%}
<div
id="{{ _tooltip_wrapperId }}"
data-slot="tooltip-wrapper"
data-side="{{ side }}"
data-side-offset="{{ sideOffset }}"
data-tooltip-target="wrapper"
role="presentation"
class="isolate z-50 pointer-events-none open:pointer-events-auto"
style="position: fixed; left: 0; top: 0; will-change: transform;"
>
<div
class="{{ ('z-50 inline-flex w-fit max-w-xs items-center gap-1.5 rounded-md bg-foreground px-3 py-1.5 text-xs text-background ltr:has-data-[slot=kbd]:pr-1.5 rtl:has-data-[slot=kbd]:pe-1.5 **:data-[slot=kbd]:relative **:data-[slot=kbd]:isolate **:data-[slot=kbd]:z-50 **:data-[slot=kbd]:rounded-sm invisible opacity-0 scale-95 transition-all duration-200 open:visible open:opacity-100 open:scale-100 ' ~ attributes.render('class'))|tailwind_merge }}"
{{ attributes.defaults({
id: _tooltip_contentId,
role: 'tooltip',
'data-slot': 'tooltip-content',
'data-side': side,
'data-tooltip-target': 'content',
}) }}
>
{%- block content %}{% endblock -%}
<div
id="{{ _tooltip_arrowId }}"
data-side="{{ side }}"
data-tooltip-target="arrow"
aria-hidden="true"
class="bg-foreground fill-foreground z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px] data-[side=bottom]:top-1 data-[side=left]:top-1/2! data-[side=left]:-right-1 data-[side=left]:-translate-y-1/2 data-[side=right]:top-1/2! data-[side=right]:-left-1 data-[side=right]:-translate-y-1/2 data-[side=top]:-bottom-2.5"
style="position: absolute;"
></div>{#- trim: this trailing whitespace text node would otherwise be a phantom flex item spaced by the content's gap-* class -#}
</div>
</div>
{# @block content The element that triggers the tooltip on hover/focus. #}
{%- set _tooltip_triggerId = inject('tooltip.triggerId') -%}
{%- set _tooltip_contentId = inject('tooltip.contentId') -%}
{%- set tooltip_trigger_attrs = {
id: _tooltip_triggerId,
'aria-describedby': _tooltip_contentId,
'data-slot': 'tooltip-trigger',
'data-tooltip-target': 'trigger',
'data-action': 'mouseenter->tooltip#show mouseleave->tooltip#hide focus->tooltip#show blur->tooltip#hide'|html_attr_type('sst'),
} -%}
{%- block content %}{% endblock -%}
Usage
<twig:Tooltip id="my-tooltip">
<twig:Tooltip:Trigger>
<twig:Button {{ ...tooltip_trigger_attrs }}>Hover</twig:Button>
</twig:Tooltip:Trigger>
<twig:Tooltip:Content>
<p>Add to library</p>
</twig:Tooltip:Content>
</twig:Tooltip>
Examples
Side
Use the side prop to change the position of the tooltip.
Loading...
<div class="flex flex-wrap gap-2">
{% for side in ['left', 'top', 'bottom', 'right'] %}
<twig:Tooltip id="tooltip-side-{{ side }}">
<twig:Tooltip:Trigger>
<twig:Button {{ ...tooltip_trigger_attrs }} variant="outline" class="w-fit">
{{ side|capitalize }}
</twig:Button>
</twig:Tooltip:Trigger>
<twig:Tooltip:Content side="{{ side }}">
<p>Add to library</p>
</twig:Tooltip:Content>
</twig:Tooltip>
{% endfor %}
</div>
With Keyboard Shortcut
Loading...
<twig:Tooltip id="tooltip-with-keyboard-shortcut">
<twig:Tooltip:Trigger>
<twig:Button {{ ...tooltip_trigger_attrs }} variant="outline" size="icon-sm">
<twig:ux:icon name="lucide:save" />
</twig:Button>
</twig:Tooltip:Trigger>
<twig:Tooltip:Content>
Save Changes <twig:Kbd>S</twig:Kbd>
</twig:Tooltip:Content>
</twig:Tooltip>
Disabled Button
Show a tooltip on a disabled button by wrapping it with a span.
Loading...
<twig:Tooltip id="tooltip-disabled-button">
<twig:Tooltip:Trigger>
<span class="inline-block w-fit">
<twig:Button {{ ...tooltip_trigger_attrs }} variant="outline" disabled class="pointer-events-auto">Disabled</twig:Button>
</span>
</twig:Tooltip:Trigger>
<twig:Tooltip:Content>
<p>This feature is currently unavailable</p>
</twig:Tooltip:Content>
</twig:Tooltip>
RTL
To enable RTL support, set the dir="rtl" attribute on the root element.
Loading...
<div class="flex flex-col gap-8">
{# Arabic #}
<div class="flex flex-wrap gap-2" dir="rtl">
{% for side, label in {left: 'يسار', top: 'أعلى', bottom: 'أسفل', right: 'يمين'} %}
<twig:Tooltip id="tooltip-rtl-ar-{{ side }}">
<twig:Tooltip:Trigger>
<twig:Button {{ ...tooltip_trigger_attrs }} variant="outline" class="w-fit">
{{ label }}
</twig:Button>
</twig:Tooltip:Trigger>
<twig:Tooltip:Content side="{{ side }}">إضافة إلى المكتبة</twig:Tooltip:Content>
</twig:Tooltip>
{% endfor %}
</div>
{# Hebrew #}
<div class="flex flex-wrap gap-2" dir="rtl">
{% for side, label in {left: 'שמאל', top: 'למעלה', bottom: 'למטה', right: 'ימין'} %}
<twig:Tooltip id="tooltip-rtl-he-{{ side }}">
<twig:Tooltip:Trigger>
<twig:Button {{ ...tooltip_trigger_attrs }} variant="outline" class="w-fit">
{{ label }}
</twig:Button>
</twig:Tooltip:Trigger>
<twig:Tooltip:Content side="{{ side }}">הוסף לרשימה</twig:Tooltip:Content>
</twig:Tooltip>
{% endfor %}
</div>
</div>
API Reference
<twig:Tooltip>
| Prop | Type | Default |
|---|---|---|
id Unique identifier for the tooltip.
|
string |
- |
delayDuration Delay in milliseconds before showing the tooltip.
|
number |
0 |
| Block | Description |
|---|---|
content |
The tooltip structure, typically includes Tooltip:Trigger and Tooltip:Content. |
<twig:Tooltip:Content>
| Prop | Type | Default |
|---|---|---|
side The preferred side to display the tooltip.
|
'top'|'right'|'bottom'|'left' |
'top' |
sideOffset The distance in pixels from the trigger.
|
number |
0 |
| Block | Description |
|---|---|
content |
The tooltip text or content. |
<twig:Tooltip:Trigger>
| Block | Description |
|---|---|
content |
The element that triggers the tooltip on hover/focus. |