Tooltip
A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it.
<dui-button variant="ButtonVariant.Outline" interestfor="--tooltip-intro">
<dui-icon name="calendar-plus"/>
Add to Calendar
</dui-button>
<dui-tooltip id="--tooltip-intro">
Save your flight or hotel dates to your calendar.
</dui-tooltip>Usage
The <dui-tooltip> Tag Helper uses the Interest Invokers and Popover APIs to display a tooltip for UI elements.
The Interest Invokers API is still experimental. See the Limitations below.
<!-- Add the element to trigger the tooltip and specify the ID of
the tooltip to trigger using the interestfor attribute -->
<dui-button interestfor="--example-tooltip">
Tooltip trigger
</dui-button>
<!-- Add the tooltip and specify its id attribute -->
<dui-tooltip id="--example-tooltip">
<!-- Add the text to display inside the tooltip -->
</dui-tooltip>Limitations
- The Interest Invokers API is not supported across all browsers yet. DuneUI includes the mfreed7/interestfor polyfill to ensure it works across all browsers. Make sure you have included the DuneUI JavaScript file in your pages.
- Not all elements can be used as an invoker element (i.e. the element that triggers the tooltip). Officially, the
<a>,<button>and<area>elements are supported, but in our tests it also works with<input>elements. As such you can use it with any of these, as well as the<dui-button>,<dui-linkbutton>,<dui-input>,<dui-select>, and<dui-textarea>Tag Helpers.
We strongly recommend you read about the Interest Invokers API on MDN to familiarise yourself with its use and limitations.
Examples
Position
Control the position of the tooltip relative to the trigger element using the position attribute. The default value is PositionArea.Top.
You can visualize the various values by using the Chrome team's Anchor Position Tool.
<div class="grid grid-cols-2 gap-4">
<dui-button variant="ButtonVariant.Outline" class="size-30"
interestfor="--tooltip-position-top-span-right">
Top<br/>Span Right
</dui-button>
<dui-button variant="ButtonVariant.Outline" class="size-30"
interestfor="--tooltip-position-right-center">
Right<br/>Center
</dui-button>
<dui-button variant="ButtonVariant.Outline" class="size-30"
interestfor="--tooltip-position-left-span-top">
Left<br/>Span Top
</dui-button>
<dui-button variant="ButtonVariant.Outline" class="size-30"
interestfor="--tooltip-position-bottom-span-left">
Bottom<br/>Span Left
</dui-button>
</div>
<dui-tooltip position="PositionArea.TopSpanRight"
id="--tooltip-position-top-span-right">
Positioned at the top of the trigger and spanning to the right
</dui-tooltip>
<dui-tooltip position="PositionArea.RightCenter"
id="--tooltip-position-right-center">
Positioned at the right center of the trigger
</dui-tooltip>
<dui-tooltip position="PositionArea.LeftSpanTop"
id="--tooltip-position-left-span-top">
Positioned at the left of the trigger and spanning to the top
</dui-tooltip>
<dui-tooltip position="PositionArea.BottomSpanLeft"
id="--tooltip-position-bottom-span-left">
Positioned at the bottom of the trigger and spanning to the left
</dui-tooltip>Offset
Control the offset of the tooltip from the trigger element by adding a margin to the tooltip.
<dui-button variant="ButtonVariant.Outline" interestfor="--tooltip-offset-20">
Offset 20px
</dui-button>
<dui-button variant="ButtonVariant.Outline" interestfor="--tooltip-offset-0">
Offset 0px
</dui-button>
<dui-tooltip id="--tooltip-offset-20" class="mt-5">
This tooltip is offset 20px from the trigger using the Tailwind <code>mt-5</code> utility
</dui-tooltip>
<dui-tooltip id="--tooltip-offset-0" class="m-0">
This tooltip is offset 0px from the trigger using the Tailwind <code>m-0</code> utility
</dui-tooltip>Delay
You can add a delay before opening and closing the tooltip by using the interest-delay-start and interest-delay-end CSS properties.
If you're using the mfreed7/interestfor Polyfill, you will need to use the
--interest-delay-start and --interest-delay-end CSS properties in addition
to the above-mentioned properties.
<dui-group>
<dui-button variant="ButtonVariant.Outline"
class="[interest-delay-start:1s] [--interest-delay-start:1s]"
interestfor="--tooltip-delay-open">
Open Delay (1000ms)
</dui-button>
<dui-button variant="ButtonVariant.Outline"
class="[interest-delay-end:1s] [--interest-delay-end:1s]"
interestfor="--tooltip-delay-close">
Close Delay (1000ms)
</dui-button>
<dui-tooltip id="--tooltip-delay-open">
Opened after 1 second
</dui-tooltip>
<dui-tooltip id="--tooltip-delay-close">
Will close after 1 second
</dui-tooltip>
</dui-group>Supported Tag Helpers
You can use <dui-tooltip> with the <dui-button>, <dui-linkbutton>, <dui-input>, <dui-select>, and <dui-textarea> Tag Helpers.
The limitations regarding which HTML elements it can be used with is due to the limitations of the Interest Invokers API.
<dui-button variant="ButtonVariant.Outline" interestfor="--tooltip-elements-button">
Button
</dui-button>
<dui-linkbutton variant="ButtonVariant.Outline" interestfor="--tooltip-elements-linkbutton">
Link Button
</dui-linkbutton>
<dui-input interestfor="--tooltip-elements-input"/>
<dui-textarea interestfor="--tooltip-elements-textarea"></dui-textarea>
<dui-select interestfor="--tooltip-elements-select">
<option>Item 1</option>
<option>Item 2</option>
</dui-select>
<dui-input type="radio" interestfor="--tooltip-elements-radio"/>
<dui-input type="checkbox" interestfor="--tooltip-elements-checkbox"/>
<dui-tooltip id="--tooltip-elements-button">
This is a tooltip for the button
</dui-tooltip>
<dui-tooltip id="--tooltip-elements-linkbutton">
This is a tooltip for the link button
</dui-tooltip>
<dui-tooltip id="--tooltip-elements-input">
This is a tooltip for the input
</dui-tooltip>
<dui-tooltip id="--tooltip-elements-textarea">
This is a tooltip for the textarea
</dui-tooltip>
<dui-tooltip id="--tooltip-elements-select">
This is a tooltip for the select
</dui-tooltip>
<dui-tooltip id="--tooltip-elements-radio">
This is a tooltip for the radio button
</dui-tooltip>
<dui-tooltip id="--tooltip-elements-checkbox">
This is a tooltip for the checkbox
</dui-tooltip>JavaScript API
Since <dui-tooltip> uses the Popover API, you can use the showPopover(), hidePopover() and togglePopover() methods to control visibility of the popover.
When using the JavaScript API, you also need to make sure you specify the source element to ensure the tooltip is aligned correctly with the UI element for which the tooltip is shown.
The togglePopover() method does not work correctly on Chromium browsers when you use the popover="hint" attribute - which is the default value <dui-tooltip> uses. If you want to use togglePopover() on Chromium, you must override this attribute by setting it to manual, as you can see in the example below.
<dui-stack align="StackAlign.Center">
<dui-button variant="ButtonVariant.Outline" size="ButtonSize.IconSmall"
interestfor="--tooltip-js-api" id="--tooltip-js-api-button">
<dui-icon name="braces"/>
</dui-button>
<dui-group>
<dui-button variant="ButtonVariant.Outline" id="--tooltip-js-api-open">
Open
</dui-button>
<dui-button variant="ButtonVariant.Outline" id="--tooltip-js-api-close">
Close
</dui-button>
<dui-button variant="ButtonVariant.Outline" id="--tooltip-js-api-toggle">
Toggle
</dui-button>
</dui-group>
</dui-stack>
<dui-tooltip id="--tooltip-js-api" popover="manual">
This tooltip can be controlled via the Popover JS API
</dui-tooltip>
<script>
const apiTooltip = document.getElementById('--tooltip-js-api');
const apiTooltipButton = document.getElementById('--tooltip-js-api-button');
const apiTooltipOpenButton = document.getElementById('--tooltip-js-api-open');
const apiTooltipCloseButton = document.getElementById('--tooltip-js-api-close');
const apiTooltipToggleButton = document.getElementById('--tooltip-js-api-toggle');
apiTooltipOpenButton.addEventListener('click', () => {
apiTooltip.showPopover({
source: apiTooltipButton
});
});
apiTooltipCloseButton.addEventListener('click', () => {
apiTooltip.hidePopover();
});
apiTooltipToggleButton.addEventListener('click', () => {
apiTooltip.togglePopover({
source: apiTooltipButton
});
});
</script>JavaScript Events
The Interest Invokers API fires the interest and loseinterest events on the <dui-tooltip> whenever it is shown or hidden respectively.
<dui-stack gap="StackGap.Small">
<dui-button interestfor="--tooltip-js-events" size="ButtonSize.IconSmall" variant="ButtonVariant.Outline">
<dui-icon name="braces"/>
</dui-button>
<label class="text-sm font-bold">Events:</label>
<div class="font-mono w-100 h-40 overflow-y-auto bg-gray-50" id="--tooltip-js-events-output">
</div>
</dui-stack>
<dui-tooltip id="--tooltip-js-events">
This tooltip emits JS events when it opens and closes
</dui-tooltip>
<script>
let counter = 0;
const eventsTooltip = document.getElementById('--tooltip-js-events');
const eventsTooltipEventOutput = document.getElementById('--tooltip-js-events-output');
eventsTooltip.addEventListener("interest", (e) => {
eventsTooltipEventOutput.innerText = `${++counter}: Tooltip opened\n` + eventsTooltipEventOutput.innerText;
});
eventsTooltip.addEventListener("loseinterest", (e) => {
eventsTooltipEventOutput.innerText = `${++counter}: Tooltip closed\n` + eventsTooltipEventOutput.innerText;
});
</script>