Tooltips in Adapt

Tooltips in Adapt

Tooltips provide contextual information when users hover over or focus on interactive elements. They are commonly used for navigation buttons, hot graphic pins, and other icon-based controls that benefit from additional labeling.

Behavior

• Tooltips appear on mouseover and keyboard focus after a 500ms delay
• Tooltips hide on mouseout, blur, click, or pressing Escape
• On mouseover, screen readers announce the tooltip text
• On keyboard focus, screen readers read the target's aria-label (the tooltip is visually displayed but not re-announced)
• Tooltips automatically reposition to stay within the viewport

---

Tooltip Settings

Global tooltip settings are configured in course.json under the _tooltips object:

"_tooltips": {
  "_isEnabled": true,
  "_position": "outside bottom middle right",
  "_allowTest": false
}

Attributes

Attribute	Type	Description
_isEnabled	Boolean	Enables or disables tooltips globally. Default: true
_position	String	Default position for all tooltips. See Position Syntax below. Default: "outside bottom middle right"
_allowTest	Boolean	Enables test mode for development. Default: false

---

Position Syntax

The _position attribute uses a string with up to four space-separated values:

<area> <side> <arrow position> <flow>

Position Parts

Part	Values	Default	Description
<area>	outside, inside	outside	Whether tooltip appears outside or inside the target element
<side>	top, bottom, left, right, middle	middle	Which side of the target the tooltip appears on
<arrow position>	start, middle, end	middle	Position of the arrow along the side (relative to the target)
<flow>	top, bottom, left, right, middle	middle	Direction the tooltip extends from the arrow

All parameters are optional. Omitted values use their defaults.

Position Examples

"_position": "bottom middle right"

Tooltip below target, arrow in middle, content flows to the right.

"_position": "outside top start left"

Tooltip above target, arrow at start of side, content flows left.

"_position": "right middle"

Tooltip to the right of target, vertically centered.

Common Patterns

• Navigation buttons: "outside bottom middle right" - tooltip below, flowing right
• Hot graphic pins: "outside bottom middle middle" - tooltip below, centered

Invalid Positions

outside middle is invalid because "middle" is not a side on the outside of a target. It will be corrected to top or left depending on the flow orientation, with a console warning.

inside middle is valid, as the inside area does have a middle position.

---

Tooltip API

The tooltip system is available as a singleton module:

import tooltips from 'core/js/tooltips';

register(config)

Registers a tooltip configuration that can be referenced by ID.

tooltips.register({
  _id: 'my-button',
  _isEnabled: true,
  text: 'Click to continue',
  disabledText: 'Complete the activity first',
  _position: 'outside bottom middle right'
});

Returns: A TooltipItemModel instance.

getTooltip(id)

Retrieves a registered tooltip by its ID.

const tooltip = tooltips.getTooltip('my-button');
if (tooltip && tooltip.get('_isEnabled')) {
  // Tooltip exists and is enabled
}

Returns: A TooltipItemModel or undefined.

show(tooltip, $element)

Displays a tooltip adjacent to a DOM element.

const tooltip = tooltips.getTooltip('my-button');
tooltips.show(tooltip, $('.my-button'));

hide([tooltipItem])

Hides a tooltip. If no argument provided, hides the most recently shown tooltip.

tooltips.hide();           // Hide last tooltip
tooltips.hide(tooltipItem); // Hide specific tooltip

isShowing(tooltip)

Checks if a tooltip is currently displayed.

if (!tooltips.isShowing(tooltip)) {
  tooltips.show(tooltip, $element);
}

Returns: Boolean.

---

Tooltip Configuration

When registering a tooltip, the following properties are available:

Property	Type	Required	Description
_id	String	Yes	Unique identifier for the tooltip
_isEnabled	Boolean	No	Enable/disable the tooltip. Default: true
text	String	No	Tooltip content (HTML supported)
disabledText	String	No	Text when target is disabled. Defaults to text
_position	String	No	Position string. Inherits from course defaults
_isStatic	Boolean	No	If true, tooltip persists until explicitly hidden
_classes	String	No	Additional CSS classes for the tooltip

---

HTML Integration

Add tooltips to elements using the data-tooltip-id attribute:

<button class="nav__btn" data-tooltip-id="back" aria-label="Back">
  <span class="icon"></span>
</button>

The data-tooltip-id value must match a registered tooltip's _id.

JSX Template Example

<button
  className="nav__btn"
  data-tooltip-id={this.model.get('_id')}
  aria-label={ariaLabel}
>
  {children}
</button>

---

Template Variables

Tooltip text supports template variables using {{variableName}} syntax:

{{ariaLabel}}

Uses the target element's aria-label attribute or .aria-label child text:

{
  "_id": "back-button",
  "text": "{{ariaLabel}}"
}

Component Properties

For components like Hot Graphic, you can reference item properties:

{
  "_tooltip": {
    "_isEnabled": true,
    "text": "{{title}}"
  }
}

---

Styling

Tooltip appearance is customized through LESS variables in your theme:

@tooltip-color: rgba(0,0,0,0.85);    // Background color
@tooltip-text-color: @white;          // Text color
@tooltip-radius: 0.35rem;             // Border radius (max 1rem)
@tooltip-offset: 0.35rem;             // Arrow distance from tooltip edge (max 1rem)
@tooltip-arrow-width: 0.7rem;         // Arrow width (max 1rem)
@tooltip-arrow-height: 0.35rem;       // Arrow height
@tooltip-arrow: true;                 // Show/hide arrows globally
@tooltip-distance: 1rem;              // Distance from target element
@tooltip-viewport-padding: 8px;       // Padding from viewport edges

---

Accessibility

The tooltip system includes several accessibility features:

ARIA Support

• Tooltip container has role="region" and aria-live="assertive"
• Target elements receive aria-describedby pointing to the tooltip
• Content is announced by screen readers on mouseover

Keyboard Navigation

• Tab: Focus moves to tooltip targets, triggering tooltip display
• Escape: Closes the currently displayed tooltip

Disabled State

When a target element has aria-disabled="true" or the .is-disabled class, the tooltip displays disabledText instead of text.

Focus Management

Tooltips triggered by programmatic focus (e.g., after closing a popup) are suppressed to avoid unexpected announcements.

---

Test Mode

For development and debugging, enable test mode to visualize all possible tooltip positions:

"_tooltips": {
  "_isEnabled": true,
  "_allowTest": true
}

With test mode enabled, hold Ctrl while hovering over any tooltip target to display all position combinations simultaneously.

---

Algorithm

The positioning algorithm works in stages:

1. Defaults: Calculate appropriate defaults and validate the _position attribute
2. Initial Render: Position tooltip as configured
3. Overflow Check: If needed, swap sides, switch axis, or fill available space
4. Edge Snapping: Snap to viewport edges as a last resort; content is truncated if necessary

The algorithm prefers the configured position but adapts when encountering viewport boundaries. Large tooltips attempt to fill the largest available space.