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',
        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;
    }

    @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.
contentSelector	string	null	Selector of the content to display in the tooltip. Takes precedence over content when both are provided.
contentActions	object	null	Configuration of the tooltip actions (see Content Actions).
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.
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.
onLeave	func	null	Callback triggered when the tooltip disappears.
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.

TypeScript

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

import type {
    TooltipOptions,
    TooltipPosition,
    ContentAction,
    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.

One event by element is possible so far as elements are referenced by selector. The last one declared in the contentActions object has precedence over the previous ones.

<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.
callbackParams	array	null	List of arguments to pass to the event handler in.
closeOnCallback	boolean	false	Flag to automatically close the tooltip when the event handler is triggered.

* 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