ckeditor_tooltip

CKEditor 5 Tooltip adds a fully-featured, accessible tooltip widget directly into the CKEditor 5 toolbar on Drupal 10 and 11 sites. Select any text in a body field, click the Tooltip button, fill in a modal dialog, and the selection becomes a dashed-underline anchor that displays a styled popup on hover, click, or keyboard focus — no coding, no shortcodes, no custom field types, and no external libraries required. Ten built-in style themes are included out of the box, with full per-instance control over colour, typography, size, animation, position, and behaviour.

Features

Ten Style Themes

• Dark — Deep navy background with white text. The default theme; works well on light page backgrounds.
• Light — White background with dark text and a subtle border. Suits dark or image-heavy pages.
• Info — Blue background with white text. Contextual information, help text, glossary definitions.
• Success — Green background with white text. Positive indicators, completion notes, green-flag flags.
• Warning — Amber/orange background with white text. Cautions, prerequisites, important caveats.
• Danger — Red background with white text. Errors, destructive actions, critical notices.
• Glass — Semi-transparent dark gradient with white text. Modern frosted-glass look for contemporary designs.
• Bordered — White background with a coloured border and matching text. Pick any border colour via a colour picker; text automatically matches the chosen colour.
• Custom — Pick any background colour with a native colour picker; foreground text is automatically adjusted for WCAG-compliant contrast.
• None — No preset theme applied; inherits all colour and typography from the surrounding page stylesheet.

Editor Experience

• No coding required — Every option is set through a tabbed modal dialog opened from the CKEditor 5 toolbar button. No shortcodes, no field configuration, no template edits.
• Live preview — A real-time popup preview updates inside the dialog as you change any setting, so editors see exactly what site visitors will see before saving.
• Edit in place — Clicking an existing tooltip in the editor reopens the dialog with all current values pre-populated.
• One-click removal — When editing an existing tooltip, a Remove Tooltip button strips the widget and restores the plain text selection.
• Character counter — A live counter beneath the content field tracks usage against the 2,000-character limit.
• Rich tooltip content — The content field accepts plain text or limited HTML: bold, italic, underline, links, images, headings, lists, code blocks, blockquotes, and more (30+ allowed tags). Broken or unclosed tags are fixed automatically.
• Optional title heading — An optional heading line is displayed above the content inside the popup.

Appearance Options

• Font size — Seven sizes from XS (9 px) to 3XL (24 px), or inherit from the page.
• Font colour — Override the theme text colour with any custom hex colour via a colour picker, or keep the theme default.
• Text alignment — Left, centre, or right.
• Padding — Compact, Normal, or Spacious inner spacing.
• Corner radius — Sharp (0 px), Rounded (6 px), Soft (12 px), or Pill (999 px).
• Shadow — None, Subtle, Normal, or Dramatic drop shadow.
• Opacity — 100 %, 95 %, 90 %, 80 %, or 70 %.

Behaviour Options

• Trigger — Hover (desktop) or Click / Tap. Mobile always uses tap regardless of this setting.
• Position — Top, Bottom, Left, or Right. Automatically flips when viewport space is limited.
• Max width — XS (150 px) through XL (600 px); automatically clamped to fit small screens.
• Max height — Optional cap with a scrollbar for overflow — ideal for long glossary entries.
• Animation — Nine entrance animations: None, Fade, Scale, Slide, Bounce, Flip-X, Flip-Y, Rotate, Zoom.
• Show delay — None, 200 ms, 500 ms, or 800 ms before the popup appears — prevents accidental hover triggers.
• Hide delay — Grace period (0–500 ms) before hiding on mouse-leave — prevents flickering.
• Close button — Optional × button inside the popup; especially useful for click-triggered tooltips.
• Interactive mode — Keeps the popup open while the mouse is inside it, so users can select text or click links.
• Keyboard focus trigger — Shows the tooltip when the anchor receives keyboard focus.
• Directional arrow — Toggle the small triangle pointer from the popup toward the anchor text.

Advanced Options

• Custom HTML ID — Attach a unique id to the popup element for CSS or JavaScript targeting.
• Extra CSS classes — Add space-separated class names to the popup for theme-level overrides.

Technical Highlights

• Clean HTML storage — Each tooltip is a single <span class="ckeditor-tooltip" data-tooltip-*="…"> element. No tokens, no shortcodes, no custom database tables.
• Zero external dependencies — No CDN, no npm package, no third-party JS library. Everything runs on Drupal core APIs plus a small self-contained JavaScript plugin.
• Automatic asset loading — The built-in Tooltip Asset Loader text filter scans saved HTML and attaches the frontend CSS and JS only on pages that actually contain tooltips — zero overhead on pages without them.
• Three-layer security — Client-side JS sanitizer, server-side PHP Xss::filter(), and a per-attribute regex sanitization pass on every save and filter run.
• CSS custom properties — All visual values are exposed as --tooltip-* CSS variables, making theme overrides a one-line stylesheet change.
• WCAG 2.1 AA accessible — Keyboard-navigable, ARIA-labelled, visible focus ring, respects prefers-reduced-motion.

Post-Installation

After enabling the module, two configuration steps are required before tooltips appear:

1. Enable the text format filter.
   
   Go to Configuration → Content authoring → Text formats and editors (/admin/config/content/formats). Click Configure next to the format used on your body fields (typically Full HTML). Under Enabled filters, tick Tooltip Asset Loader and click Save configuration. Without this filter, tooltips will be displayed as plain text on the front end and no CSS or JS will be loaded.
2. Add the toolbar button.
   
   On the same text format configuration page, scroll to the CKEditor 5 toolbar section. Drag the Tooltip button from the Available items tray into an active toolbar row. Click Save configuration, then clear caches (drush cr).

If your text format uses a Limit allowed HTML tags filter, you must also allow the full <span> element with all its data-tooltip-* attributes, or switch to a format without tag restrictions. The exact attribute list to add is shown in the module's built-in help page at Help → CKEditor Tooltip (/admin/help/ckeditor_tooltip).

Tooltips can now be inserted from the editor toolbar:

1. Place your cursor in a body field, select the anchor text, and click the Tooltip button in the toolbar.
2. Fill in the Content field — plain text or limited HTML is accepted.
3. Adjust Appearance, Behaviour, and Advanced settings as needed. The Live Preview panel updates in real time.
4. Click Save — the selected text becomes a dashed-underline anchor in the editor.
5. Save the node. The tooltip is stored as a <span> with data-tooltip-* attributes.
6. To edit later, click the tooltip anchor in the editor to reopen the dialog with all values pre-populated.
7. To remove a tooltip, open the dialog and click Remove Tooltip.

Additional Requirements

• Drupal 10.x or 11.x
• PHP 8.1 or higher
• Drupal core modules: CKEditor 5, Editor, and Filter — all included in Drupal core ≥ 9.3 and enabled by default

No contributed modules, no external libraries, and no CDN dependencies are required. The module is self-contained.

Recommended Modules / Libraries

• Token — Allows token-based dynamic values (e.g. current user name, site name) inside tooltip content fields when used alongside a token-processing filter.
• Editor Advanced Link — Useful when editors need to insert hyperlinks with custom attributes inside tooltip content. Both plugins share the same CKEditor 5 toolbar without conflict.
• CKEditor 5 Premium Features — If your editorial workflow uses revision history, track changes, or real-time collaboration, CKEditor Tooltip coexists cleanly alongside premium plugins as an independent toolbar plugin.
• A Redis or Memcache cache backend — For high-traffic pages with many tooltips, a persistent cache backend reduces the cost of re-running the text filter on every page request.

Similar Projects

• CKEditor Abbreviation (CKEditor 4) — Provides an abbreviation tooltip using the HTML <abbr> element in the legacy CKEditor 4 toolbar. CKEditor Tooltip is built exclusively for CKEditor 5 (the default editor in Drupal 10 and 11), uses a <span> element with data-* attributes, supports rich HTML content inside the popup, and adds ten style themes, nine entrance animations, colour pickers, and full behaviour controls — none of which were available in the CKEditor 4 equivalent.
• Native <abbr title=""> — The browser's built-in abbreviation tooltip is pure HTML and needs no module, but the rendering is entirely controlled by the operating system (a plain unformatted system tooltip), it cannot contain HTML content, it has no animation or positioning control, and it is inaccessible to touch users. CKEditor Tooltip replaces it with a fully styled, interactive, mobile-friendly popup.
• JavaScript tooltip libraries (Tippy.js, Floating UI, etc.) added via a custom theme — These libraries require hand-coded template changes and a developer to wire up each trigger element. CKEditor Tooltip provides the same rendering quality directly inside the editor UI with no theme changes, no developer involvement, and a per-instance configuration dialog for content editors.

Supporting This Module

If CKEditor Tooltip saves you time on your project, the best ways to support continued development are:

• Report bugs and suggest features in the project issue queue.
• Contribute patches, additional test coverage, or documentation improvements via the issue queue.
• Post a review on the project page — community ratings help other Drupal developers discover the module.
• Help test release candidates against new Drupal 10 and 11 minor versions.

When reporting an issue, please include your Drupal core version, PHP version, browser, the exact steps to reproduce, and any relevant output from Reports → Recent log messages (/admin/reports/dblog) filtered by the ckeditor_tooltip channel.

Community Documentation

• Full installation, configuration, architecture, and troubleshooting documentation is available in the README.md file included in the module.
• A complete settings reference — covering all appearance, behaviour, and advanced options — is in the README under Appearance Options, Behaviour Options, and Advanced Options.
• A developer guide explaining how to add new data-tooltip-* attributes (schema, converters, form, filter, tests) is in the README under Developer Guide and also in the module's built-in help page at /admin/help/ckeditor_tooltip.
• For an explanation of the three-layer XSS security model (client-side JS sanitizer → PHP form → server-side filter), see the Security section of the README.
• Video walkthroughs, tutorial articles, and live demo links are welcome contributions — please post them in the issue queue and they will be linked here.