Tooltip

Live Demo

Directional Tooltips

Tooltip on Icon

Tooltip on Link

HTML Content Tooltip

Tooltip Bubble

The rendered bubble appearance. The live tooltips above are injected by Bootstrap on hover/focus; this static instance shows the styled bubble for the Figma export.

Code sample

<!-- Directional tooltip on button -->
<button type="button" class="caat-button"
  data-bs-toggle="tooltip" data-bs-placement="top"
  title="Tooltip on top">Top</button>

<!-- Tooltip on icon -->
<span class="caat-tooltip" data-bs-toggle="tooltip"
  title="Helpful definition text" tabindex="0"
  role="button" aria-label="More info">
  <i class="bi bi-info-circle-fill caat-tooltip__icon"
     aria-hidden="true"></i>
</span>

<!-- Tooltip on link -->
<a href="#" class="caat-tooltip__link"
  data-bs-toggle="tooltip"
  title="Explanatory text">term</a>

<!-- HTML content tooltip -->
<button type="button" class="caat-button"
  data-bs-toggle="tooltip" data-bs-html="true"
  title="&lt;strong&gt;Bold&lt;/strong&gt;&lt;br&gt;Line two">
  Hover for details</button>

1. Summary

2. Design Tokens

3. Authoring Fields

4. Validation Rules

5. Content Guidance

• Tooltips are for supplementary information only — never place essential content inside a tooltip.
• Keep text concise: aim for one or two short sentences (under 150 characters).
• Use sentence case. Avoid all-caps.
• Do not duplicate the trigger element's visible label.
• For pension-specific terms (e.g., commuted value, credited service), provide a plain-language definition.
• Avoid interactive content (links, buttons) inside tooltips — use a Popover instead.
• Use HTML content tooltips sparingly; bold text and line breaks are acceptable, but avoid complex markup.

6. Semantic HTML

<!-- Icon trigger -->
<span class="caat-tooltip"
  data-bs-toggle="tooltip"
  title="Definition of the term"
  tabindex="0"
  role="button"
  aria-label="More information about [term]">
  <i class="bi bi-info-circle-fill caat-tooltip__icon"
     aria-hidden="true"></i>
</span>

<!-- Button trigger -->
<button type="button" class="caat-button"
  data-bs-toggle="tooltip"
  data-bs-placement="top"
  title="Supplementary text">
  Label
</button>

<!-- Link trigger -->
<a href="/page" class="caat-tooltip__link"
  data-bs-toggle="tooltip"
  title="Explanation of linked term">
  linked term
</a>

<!-- HTML content -->
<button type="button" class="caat-button"
  data-bs-toggle="tooltip"
  data-bs-html="true"
  title="&lt;strong&gt;Term&lt;/strong&gt;&lt;br&gt;Explanation">
  Label
</button>

7. CSS Contract

Key CSS rules

.tooltip-inner {
  background-color: var(--caat-blue-900);
  color: #fff;
  border-radius: var(--caat-radius);
  font-family: var(--caat-font-primary), sans-serif;
  max-width: 250px;
}

.bs-tooltip-top .tooltip-arrow::before {
  border-top-color: var(--caat-blue-900);
}

8. Accessibility

9. SEO

Transient / structural UI with no indexable content of its own — no SEO markup required. Ensure any content this component wraps or reveals stays server-rendered and crawlable.

10. Analytics

Analytics are captured through the shared data-analytics-component attribute on the component root (emitted automatically) and reported to the central data layer. Event names and payloads follow the organisation's standard analytics schema — defined centrally with the analytics team, not invented per component — so no bespoke tracking is specified here.

11. AEM Notes

• Proxy component — create at /apps/caat/components/tooltip with sling:resourceSuperType pointing to the core tooltip component or a custom HTL template.
• HTL rendering — emit the data-bs-toggle="tooltip", title, and data-bs-placement attributes server-side. Use data-sly-attribute to conditionally add data-bs-html="true".
• Client library — caat.components.tooltip (category). Include the tooltip initialisation JS. Depend on caat.vendors.bootstrap.
• Policy — allow placement selection and HTML toggle per template policy. Default placement: top.
• XSS — when HTML tooltips are enabled, sanitise content through AEM's XSSAPI before rendering in the title attribute.

12. Dialog Model

Simplified model — shows field intent and Granite UI resource types, not the literal cq:dialog node tree (e.g. select options are authored as child items nodes).

{
  "jcr:primaryType": "nt:unstructured",
  "sling:resourceType": "cq/gui/components/authoring/dialog",
  "items": {
    "tabs": {
      "items": {
        "content": {
          "items": {
            "tooltipText": {
              "sling:resourceType": "granite/ui/components/coral/foundation/form/textarea",
              "name": "./tooltipText",
              "fieldLabel": "Tooltip text",
              "required": true,
              "maxlength": 150
            },
            "triggerType": {
              "sling:resourceType": "granite/ui/components/coral/foundation/form/select",
              "name": "./triggerType",
              "fieldLabel": "Trigger type",
              "required": true,
              "items": {
                "button": { "text": "Button", "value": "button" },
                "icon":   { "text": "Icon",   "value": "icon" },
                "link":   { "text": "Link",   "value": "link" },
                "inline": { "text": "Inline element", "value": "inline" }
              }
            },
            "placement": {
              "sling:resourceType": "granite/ui/components/coral/foundation/form/select",
              "name": "./placement",
              "fieldLabel": "Placement",
              "items": {
                "top":    { "text": "Top",    "value": "top", "selected": true },
                "right":  { "text": "Right",  "value": "right" },
                "bottom": { "text": "Bottom", "value": "bottom" },
                "left":   { "text": "Left",   "value": "left" }
              }
            },
            "allowHtml": {
              "sling:resourceType": "granite/ui/components/coral/foundation/form/checkbox",
              "name": "./allowHtml",
              "text": "Allow HTML content"
            },
            "accessibleLabel": {
              "sling:resourceType": "granite/ui/components/coral/foundation/form/textfield",
              "name": "./accessibleLabel",
              "fieldLabel": "Accessible label (required for icon trigger)"
            }
          }
        }
      }
    }
  }
}

13. QA Checklist

• Tooltip appears on hover and on keyboard focus.
• Tooltip dismisses on mouse-out, blur, and Escape key.
• All four directional placements render correctly (top, right, bottom, left).
• Arrow colour matches tooltip background (--caat-blue-900).
• Icon trigger has aria-label and tabindex="0".
• Link trigger displays dotted underline and correct cursor.
• HTML content tooltip renders bold text and line breaks.
• Tooltip max-width is 250 px; long text wraps correctly.
• Focus ring (--caat-focus) visible on all trigger types.
• Screen reader announces tooltip content via aria-describedby.
• Colour contrast: white on blue-900 meets WCAG AAA (7:1+).
• Cross-browser tested: Chrome, Firefox, Safari, Edge.
• Responsive: tooltips reposition when near viewport edges.
• Analytics events fire on shown.bs.tooltip and hidden.bs.tooltip.

14. Definition of Done