Tooltips in a Nutshell

Hovers, says its piece, gets out of the way. Shortcode tooltips for WordPress with no dependencies, six colour presets on one settings page, and a drop-in for the simple_tooltip shortcode of the closed Simple Tooltips plugin.

[nutshell content='Short explanation']Visible label[/nutshell]
[simple_tooltip content='Short explanation']Visible label[/simple_tooltip]

Both render the same thing: the label with a dotted underline, and a bubble with the explanation on hover, keyboard focus or tap.

Why

Simple Tooltips was closed on wordpress.org on 2023-07-27 for a security issue (CVE-2023-25958, a stored XSS in its settings that needs administrator rights, unpatched). It will never be updated again and cannot be reinstalled from the directory. Roughly ten thousand sites still run it, and deleting it leaves [simple_tooltip …] printed in the page.

This plugin registers the same shortcode with the same attributes. Deactivate Simple Tooltips, activate this one, and every tooltip is back, without editing a page. The original's per-tooltip bubblewidth, bubblebgcolor and bubblecolor are honoured; its style, bubbleopacity and bubbleposition are ignored (position is decided by the viewport, opacity was a 2013 fashion).

What it does

• Accessible. The bubble is a real element with role="tooltip"; the trigger is focusable and points at it with aria-describedby, so a screen reader hears the label and the explanation. Escape closes it. The pointer can move onto the bubble without closing it (WCAG 1.4.13).
• Stays on screen. Flips below the trigger near the top of the viewport, shifts sideways near the edges, and fits phones (max-width: min(300px, 100vw - 16px)).
• Line breaks survive. <br> and paragraph boundaries inside the shortcode text become line breaks in the bubble.
• Safe output. Tooltip text is plain text and escaped; the label goes through wp_kses_post.
• Small. About 2 KB of CSS on every page, 2 KB of JS only on pages that render a tooltip.
• Divi aware. Lifts the column that holds an open tooltip, so sibling columns do not cover it. Harmless outside Divi.

Install

Download tooltips-in-a-nutshell.zip from the latest release and upload it under Plugins → Add New → Upload Plugin. Updates then show up on the Plugins screen like any other plugin's: the bundled Plugin Update Checker (MIT) watches this repository's releases.

Styling

Settings → Tooltips has a preset dropdown (Slate, Carmine, Ocean, Moss, Plum, Night), an optional accent colour and the bubble width, with a live preview that is the real tooltip. A site plugin can add presets through the nutshell_tooltips_presets filter.

Underneath, everything is six CSS custom properties. A :root rule in the theme or under Appearance → Customize → Additional CSS wins over the settings page:

:root {
  --nutshell-accent: #b0132e;   /* border, underline, arrow   (default #333333) */
  --nutshell-bg: #ffffff;       /* bubble background          (#ffffff) */
  --nutshell-text: #111111;     /* bubble text                (#111111) */
  --nutshell-width: 320px;      /* maximum bubble width       (300px) */
  --nutshell-font-size: 0.8em;  /* bubble text size           (0.8em) */
  --nutshell-radius: 4px;       /* corner radius              (4px) */
}

A theme with its own tooltip styles can drop the stylesheet: add_filter( 'nutshell_tooltips_load_style', '__return_false' );

What it deliberately does not do

HTML, links or images inside the bubble; click-to-open popovers; a block; an options pile. A tooltip with links in it is a popover, and Shortcodes Ultimate or Tippy.js do that well.

Development

php test/render.php          # renders seven cases through a WordPress stub, writes test/test.html
bin/build-zip.sh             # builds the release asset tooltips-in-a-nutshell.zip

test/test.html links the real stylesheet and script; serve the folder over HTTP to try hover, keyboard and viewport edges in a browser.

Release

1. Bump Version: in the plugin header, NUTSHELL_TOOLTIPS_VERSION, and Stable tag plus the changelog in readme.txt.
2. Commit, tag vX.Y.Z, push.
3. bin/build-zip.sh, then attach the zip to the GitHub release for that tag. The update checker installs the attached asset, not GitHub's automatic source zip.

Licence

GPL-2.0-or-later. Plugin Update Checker is MIT, see vendor/plugin-update-checker/license.txt.

Made by Krassnigg Digital, Graz.