Svelte action to display a tooltip

Demo

LIVE DEMO

Installation

npm i @untemps/svelte-use-tooltip

Usage

Basic usage

<script lang="ts">
    import { useTooltip } from '@untemps/svelte-use-tooltip';

    const _onTooltipClick = (arg: string, event: Event) => {
        console.log(arg, event);
    };
</script>

<div
    use:useTooltip={{
        position: 'right',
        contentSelector: '#tooltip-template',
        contentActions: {
            '*': {
                eventType: 'click',
                callback: _onTooltipClick,
                callbackParams: ['ok'],
                closeOnCallback: true
            }
        },
        containerClassName: `tooltip tooltip-right`,
        animated: true,
        animationEnterClassName: 'tooltip-enter',
        animationLeaveClassName: 'tooltip-leave',
        enterDelay: 100,
        leaveDelay: 100,
        offset: 20
    }}
    class="target"
>
    Hover me
</div>
<template id="tooltip-template">
    <span class="tooltip__content">Hi! I'm a <i>fancy</i> <strong>tooltip</strong>!</span>
</template>

<style>
    .target {
        width: 10rem;
        height: 3rem;
        background-color: white;
        color: black;
        display: flex;
        align-items: center;
        justify-content: center;
        box-shadow: 0 0 5px 0 rgba(0, 0, 0, 0.5);
    }

    .target:hover {
        cursor: pointer;
        background-color: black;
        color: white;
    }

    .tooltip__content {
        background-color: yellow;
        color: black;
    }

    :global(.tooltip) {
        position: absolute;
        z-index: 9999;
        max-width: 120px;
        background-color: #ee7008;
        color: #fff;
        text-align: center;
        border-radius: 6px;
        padding: 0.5rem;
    }

    :global(.tooltip::after) {
        content: '';
        position: absolute;
        margin-left: -5px;
        border-width: 5px;
        border-style: solid;
    }

    :global(.tooltip-right::after) {
        top: calc(50% - 5px);
        left: -5px;
        border-color: transparent #ee7008 transparent transparent;
    }

    :global(.tooltip-enter) {
        animation: fadeIn 0.2s linear forwards;
    }

    :global(.tooltip-leave) {
        animation: fadeOut 0.2s linear forwards;
    }

    @keyframes fadeIn {
        from {
            opacity: 0;
            transform: translateX(50px);
        }
        to {
            opacity: 1;
            transform: translateX(0);
        }
    }
    @keyframes fadeOut {
        to {
            opacity: 0;
            transform: translateX(-50px);
        }
    }
</style>

API

Props	Type	Default	Description
content	string	null	Text content to display in the tooltip. In development, a console.warn is emitted if neither content nor contentSelector is provided.
contentSelector	string	null	Selector of the content to display in the tooltip. Takes precedence over content when both are provided. In development, a console.warn is emitted if the selector matches no element in the DOM.
contentActions	object	null	Configuration of the tooltip actions (see Content Actions). Each key is a CSS selector; each value is a ContentAction object or an array of ContentAction objects, allowing multiple listeners per element. The special '*' key targets the entire tooltip container and works without contentSelector. All other keys require contentSelector to be set — if they are provided without it, a console.warn is emitted and the non-'*' actions are cleared. When contentActions is set and the content contains focusable elements (buttons, links, inputs…), the tooltip receives role="dialog", aria-haspopup, aria-expanded, and a focus trap; the trigger also gains tabindex="0" for keyboard reachability. If contentActions is set but the content has no focusable elements, the tooltip keeps role="tooltip" with no focus management. The tabindex is removed when contentActions is unset or destroy() is called.
containerClassName	string	null	Class name to apply to the tooltip container. When not set, the tooltip receives the auto-generated classes __tooltip __tooltip-{position}.
position	string	'top'	Position of the tooltip. Available values: 'top', 'bottom', 'left', 'right'. If the tooltip would overflow the viewport, it automatically switches to the position with the most available space. For 'left'/'right', when width is 'auto', the width shrinks to fit before switching positions (down to a minimum of 80 px).
animated	boolean	false	Flag to animate tooltip transitions. The default classes __tooltip-enter / __tooltip-leave (from useTooltip.css) are already wrapped in @media (prefers-reduced-motion: no-preference). If you supply custom animationEnterClassName / animationLeaveClassName, wrap your own keyframes in the same media query. Do not use animation: none for the reduce case — it suppresses animationend, causing the tooltip to linger for up to 1 s before the timeout fallback fires. Use animation-duration: 0.001ms instead so the event fires immediately.
animationEnterClassName	string	'__tooltip-enter'	Class name to apply to the tooltip enter transition.
animationLeaveClassName	string	'__tooltip-leave'	Class name to apply to the tooltip leave transition.
enterDelay	number	0	Delay before showing the tooltip in milliseconds.
leaveDelay	number	0	Delay before hiding the tooltip in milliseconds.
onEnter	func	null	Callback triggered when the tooltip appears: (event?: Event) => void. Receives the native DOM event that triggered the transition — MouseEvent on hover, FocusEvent on focus, TouchEvent when using touchBehavior — or undefined when shown programmatically via the open prop.
onLeave	func	null	Callback triggered when the tooltip disappears: (event?: Event) => void. Receives the native DOM event that triggered the transition — MouseEvent on mouseleave, FocusEvent on focusout, KeyboardEvent on Escape, TouchEvent when using touchBehavior — or undefined when hidden programmatically via the open prop.
onPlacementChange	func	null	Callback triggered when the tooltip auto-flips to a different position due to viewport overflow: (from: TooltipPosition, to: TooltipPosition) => void. from is the declared position, to is the actual rendered position. Useful to sync custom arrow classes or layout indicators with the effective placement. Fires regardless of containerClassName.
offset	number	10	Distance between the tooltip and the target in pixels. Minimum enforced value is 5.
width	string	'auto'	Width of the tooltip. Use 'auto' to let the tooltip shrink-fit the trigger width, or a CSS size value (e.g. '200px') to allow it to exceed the trigger width.
disabled	boolean	false	Flag to disable the tooltip.
open	boolean	undefined	Programmatically control tooltip visibility. true shows the tooltip and locks it open — hover/focus events and Escape are ignored while the lock is active. false is a one-shot close: hides the tooltip and immediately releases the lock so hover/focus resumes normally. undefined (or not passed) leaves normal hover/focus behavior unchanged. Has no effect when disabled is true.
portal	boolean	true	When true (default), the tooltip is appended to document.body and positioned with position: fixed, avoiding stacking-context issues caused by CSS transform, filter, or perspective on ancestor elements. When false, the tooltip is appended as a direct child of the target element and positioned with position: relative — matching the pre-v4 behavior.
touchBehavior	string	undefined	Controls how the tooltip responds to touch events. 'hover' mirrors mouse hover — touchstart shows the tooltip and touchend/touchcancel hide it. 'toggle' toggles visibility on touchend on the target; a touchstart anywhere outside the target dismisses it. When not set (default), no touch listeners are registered.
showOn	string[]	['mouseenter', 'focusin']	DOM event types that show the tooltip. Any valid event type can be used (e.g. ['click'] to show on click only). Touch event types (touchstart, touchend, touchcancel) are supported and registered as passive listeners automatically. Changing this prop via update() replaces the listeners atomically. When an event type appears in both showOn and hideOn, a single toggle listener is registered instead of separate show/hide ones — first trigger shows, second hides, and so on.
hideOn	string[]	['mouseleave', 'focusout']	DOM event types that hide the tooltip. Pass [] to keep the tooltip visible until dismissed by Escape, open: false, or programmatic removal. Touch event types (touchstart, touchend, touchcancel) are supported and registered as passive listeners automatically. Changing this prop via update() replaces the listeners atomically. When an event type appears in both showOn and hideOn, a single toggle listener is registered instead of separate show/hide ones — first trigger shows, second hides, and so on.
ariaLabel	string	'Tooltip'	Accessible label for interactive tooltips (role="dialog"). Override the default "Tooltip" value to provide a more descriptive or localized label — screen readers announce this as the dialog name. Has no effect on non-interactive tooltips (role="tooltip").

TypeScript

The package ships TypeScript types. The main types you may need when composing options or building wrappers:

import type {
    TooltipOptions,
    TooltipPosition,
    ContentAction,
    ContentActionValue,
    ContentActions
} from '@untemps/svelte-use-tooltip';

Content and Content Selector

The tooltip content can be specified either by the content prop or the contentSelector prop. When both are provided, contentSelector takes precedence.

content must be a text string that will be displayed as is in the tooltip.

It's useful for most of the use cases of a tooltip however sometimes you need to display some more complex content, with interactive elements or formatted text.

To do so, you may use the contentSelector prop that allows to specify the selector of an element from the DOM.

The best option is to use a template HTML element although you may also use a plain element. In this case, it will remain in the DOM and will be cloned in the tooltip.

Content Actions

The contentActions prop allows to handle interactions within the tooltip content.

Each element inside the content parent may configure its own action since it can be queried using the key-selector.

Each value in the contentActions object can be either a single action object (ContentAction) or an array of action objects (ContentAction[]), allowing you to attach multiple events to the same element.

Note: All selector keys except '*' require contentSelector to be set. If non-'*' keys are provided without a contentSelector, a console.warn is emitted and those actions are cleared. The '*' key (whole-tooltip listener) works without contentSelector.

<script lang="ts">
    import { useTooltip } from '@untemps/svelte-use-tooltip';
</script>

<div
    use:useTooltip={{
        contentSelector: '#content',
        contentActions: {
            '#button1': {
                eventType: 'mouseenter',
                callback: (arg) => console.log(arg),
                callbackParams: ["Haha you're hovering the button 1"],
                closeOnCallback: false
            },
            '#button2': {
                eventType: 'click',
                callback: (arg1, arg2) => console.log(arg1, arg2),
                callbackParams: ["Haha you've clicked the", 'button 2'],
                closeOnCallback: true
            }
        }
    }}
>
    Hover me
</div>
<span id="content">
    <button id="button1">Action 1</button>
    <button id="button2">Action 2</button>
</span>

Props	Type	Default	Description
eventType	string	null	Type of the event. All available events can be used.
callback	function	null	Function to be used as event handler. The callback always receives the items of callbackParams as leading arguments, followed by the native Event object as the last argument: callback(...callbackParams, event). Use event.target or event.currentTarget to identify the element that triggered the interaction.
callbackParams	array	null	List of arguments to pass to the event handler as leading arguments, before the native Event object.
closeOnCallback	boolean	false	Flag to automatically close the tooltip when the event handler is triggered.

Multiple events per element

Pass an array of action objects to attach multiple listeners to the same element:

<div
    use:useTooltip={{
        contentSelector: '#content',
        contentActions: {
            '#button1': [
                {
                    eventType: 'click',
                    callback: (arg) => console.log('clicked', arg),
                    callbackParams: ['button 1'],
                    closeOnCallback: true
                },
                {
                    eventType: 'mouseenter',
                    callback: () => console.log('hovered button 1')
                }
            ]
        }
    }}
>
    Hover me
</div>
<span id="content">
    <button id="button1">Action 1</button>
</span>

All listeners attached this way are automatically removed when the tooltip is hidden or destroyed.

* selector

If you need the whole tooltip content to be interactive, you can use the special * key:

<script lang="ts">
    import { useTooltip } from '@untemps/svelte-use-tooltip';
</script>

<div
    use:useTooltip={{
        content: 'Foo',
        contentActions: {
            '*': {
                eventType: 'click',
                callback: (arg) => console.log(arg),
                callbackParams: ['Haha you clicked the tooltip'],
                closeOnCallback: true
            }
        }
    }}
>
    Hover me
</div>

If you combine the * selector with other events, its callback will be triggered along with the other ones.

Development

The component can be served for development purpose on http://localhost:5173/ running:

yarn dev

Contributing

Contributions are warmly welcomed:

• Fork the repository
• Create a feature branch
• Develop the feature AND write the tests (or write the tests AND develop the feature)
• Commit your changes using Conventional Commits with sentence-case subject (e.g. feat: Add offset prop)
• Submit a Pull Request