Cool customisable tooltips made from pure CSS

npm install cooltipz-css
GitHub stars GitHub stars GitHub release (latest by date) Latest release

Getting started

To get started using Cooltipz.css in your project, all you need to do is:

  1. Install cooltipz-css via CDN, npm or yarn
  2. Add an aria-label and a direction to any non self-closing HTML tag
  3. (Optional) Add any modifiers and/or customise your own tooltip

Depending on your preference, you can choose to use classes or data- attributes.



jsDelivr hits (npm)

In the below CDN links:

<link rel="stylesheet" href="" />
@import url('');

Package manager (npm or yarn)

npm downloads npm downloads

First, install it via npm

npm install cooltipz-css --save

Or, install it via yarn

yarn add cooltipz-css

Then, import it into your JavaScript

import 'cooltipz-css';

Or, import the SCSS or CSS into your Sass/SCSS

In the below imports, replace :file with one of the options below:

/* Webpack */
@import '~cooltipz-css/:file';

/* Non webpack */
@import 'path/to/node_modules/cooltipz-css/:file';


Exactly one direction value is required.

<button aria-label="Tooltip message" data-cooltipz-dir="top">...</button>
<!-- OR -->
<button aria-label="Tooltip message" class="cooltipz--top">...</button>

Now you have your basic tooltip, try some of the modifiers and try customising your own tooltip.


By default, the tooltip's content will not wrap. If you want the tooltip content to wrap, use one of the size modifiers below.

<button aria-label="Tooltip message" data-cooltipz-dir="top" data-cooltipz-size="fit">...</button>
<!-- OR -->
<button aria-label="Tooltip message" class="cooltipz--top cooltipz--fit">...</button>

Use data-cooltipz-dir="custom" or class="cooltipz--custom" if you want to manually implement new lines and have the width automatically adjust to the longest line. You can implement a newline with the &#xa; character.

<button aria-label="Tooltip message&#xa;with new line" data-cooltipz-dir="top" data-cooltipz-size="custom">...</button>
<!-- OR -->
<button aria-label="Tooltip message&#xa;with new line" class="cooltipz--top cooltipz--custom">...</button>

No animation

You can disable animation for a single tooltip:

<button aria-label="Tooltip message" data-cooltipz-dir="top" data-cooltipz-static>...</button>
<!-- OR -->
<button aria-label="Tooltip message" class="cooltipz--top cooltipz--static">...</button>

Or you can disable animation on all tooltips by customising the --cooltipz-timing custom property:

:root {
  --cooltipz-timing: 0;

Animation is automatically disabled if the user's preferences are set to prefers reduced motion.

Always visible

You can make a tooltip always appear:

<button aria-label="Tooltip message" data-cooltipz-dir="top" data-cooltipz-visible>...</button>
<!-- OR -->
<button aria-label="Tooltip message" class="cooltipz--top cooltipz--visible">...</button>

This can also be useful if you need to programmatically show a tooltip.

Special characters

Not a problem.

<button aria-label="&copy; &reg; &#9742; &#9850; &#8709; 😎🚗🍔💩👏✔❤ ā¨¸ā¨¤ ā¨¸āŠā¨°āŠ€ ā¨…ā¨•ā¨žā¨˛" data-cooltipz-dir="top" data-cooltipz-visible>...</button>

Font Awesome

A little setup is required to use Font Awesome's unicode values in the tooltip's aria-label attribute.

You will need to set a value for the --cooltipz-fontawesome custom property.

<button aria-label="&#xf03e; &#xf200; &#xf188; &#xf007;" data-cooltipz-dir="top">...</button>

Font Awesome 4

If you are using Font Awesome 4, add the following to your CSS:

:root {
  --cooltipz-fontawesome: FontAwesome;

Font Awesome 5

If you are using Font Awesome 5, you will need to find the relevant font-family for your usage of Font Awesome listed here and set it to the --cooltipz-fontawesome custom property, for example:

:root {
  --cooltipz-fontawesome: "Font Awesome 5 Free";


There are 19 custom properties for you to customise your own tooltips.

CSS/SCSS Variable Description Default Valid values
--cooltipz-bg-color $cooltipz-bg-color Tooltip background colour #1f1f1f Accepts any valid value for background-color
--cooltipz-border-width $cooltipz-border-width Tooltip border width 0 Accepts any valid value for border-width
--cooltipz-border-style $cooltipz-border-style Tooltip border style solid Accepts any valid value for border-style
--cooltipz-border-color $cooltipz-border-color Tooltip border colour (use this to also define the arrow colour) #1f1f1f (same as bg colour) Accepts any valid value for border-color
--cooltipz-text-color $cooltipz-text-color Tooltip text colour #fff Accepts any valid value for color
--cooltipz-font-size $cooltipz-font-size Tooltip font size 0.75rem Accepts any valid value for font-size
--cooltipz-font-family $cooltipz-font-family Tooltip font font-family If you're overriding the font-family and you are using Font Awesome, you need to ensure that you state var(--cooltipz-fontawesome) in there somewhere, otherwise the icons won't display. verdana, geneva, tahoma, var(--cooltipz-fontawesome, Arial), sans-serif Accepts any valid value for font-family
--cooltipz-slide $cooltipz-slide Distance for tooltip to travel into view 6px Accepts any valid value for translate (single values only)
--cooltipz-border-radius $cooltipz-border-radius Tooltip border radius 0.125rem Accepts any valid value for border-radius
--cooltipz-timing $cooltipz-timing Time for tooltip to appear 120ms Accepts any valid value for transition-duration
--cooltipz-cursor $cooltipz-cursor The cursor shown on the element the tooltip is attached to pointer Accepts any valid value for cursor
--cooltipz-small $cooltipz-small The width of a size small tooltip 6.25rem Accepts any valid value for width
--cooltipz-medium $cooltipz-medium The width of a size medium tooltip 12.5rem Accepts any valid value for width
--cooltipz-large $cooltipz-large The width of a size large tooltip 18.75rem Accepts any valid value for width
--cooltipz-delay-show $cooltipz-delay-show The timed delay for the tooltip to show 0s Accepts any valid value for transition-delay
--cooltipz-delay-hide $cooltipz-delay-hide The timed delay for the tooltip to hide 0s Accepts any valid value for transition-delay
--cooltipz-arrow-size $cooltipz-arrow-size The size of the tooltip arrow 0.3125rem Accepts any valid value for border-width
--cooltipz-arrow-offset $cooltipz-arrow-offset Tooltip arrow offset 0px Accepts any valid value for translate (single values only)
$cooltipz-attribute The attribute the tooltips are bound to (can only customise in SCSS - not available in CSS) aria-label Accepts any valid HTML attribute

To customise all tooltips, place your custom properties in the :root selector:

:root {
  --cooltipz-bg-color: #ffffff;
  --cooltipz-text-color: #000000;
  --cooltipz-font-size: 1.2rem;

Or you can customise specific tooltips. The below example will customise any tooltips on the .custom element and and children of it:

.custom {
  --cooltipz-arrow-size: 1.5rem;
  --cooltipz-cursor: help;
  --cooltipz-timing: 0;

See our CodePen for lots of examples of customisation:

See the Pen Cooltipz.css - Cool tooltips made from pure CSS by Jack Domleo (@jackdomleo7) on CodePen.


Important: Cooltipz.css uses the ::before and ::after psuedo elements to display the tooltips, so be cautious of the following:

Feedback and support

We appreciate any feedback, good or bad and are always looking for new ideas to improve the user experience (UX), developer experience (DX) and accessibility of the tooltips. You may want to consider:


Cooltipz.css is licensed under MIT. As a minimum, you are required to KEEP AND NOT REMOVE the following code at the beginning of your downloaded/installed Cooltipz.css CSS, where :version is replaced with the version number you are using:

/*! Cooltipz.css v:version | MIT License | */

Cooltipz.css is FREE for personal and commercial use.