Tooltips

Introduction

Tooltips in Chassis CSS deliver contextual information and helpful hints without disrupting user workflows. Built on modern web standards with intelligent positioning via Popper.js, tooltips seamlessly integrate with your design system while maintaining accessibility and performance best practices.

Chassis CSS tooltips operate on a manual initialization model for optimal performance and control:

• Explicit initialization required to prevent performance impact on unused elements
• Intelligent positioning powered by Popper.js for dynamic placement and collision detection
• Automatic placement adjustment based on viewport constraints
• Comprehensive event integration for application logic
• Accessibility through proper ARIA attributes and keyboard navigation support
• CSS custom properties for seamless theming and brand consistency

Implementation

Before implementing tooltips, ensure these dependencies and considerations are addressed:

• Include popper.min.js before chassis.js, or use chassis.bundle.min.js
• Tooltips with empty titles will not display
• Hidden elements cannot trigger tooltips
• Use container: 'body' for complex component layouts (input groups, button groups)
• Only apply tooltips to keyboard-focusable, interactive elements for accessibility compliance
• Hide tooltips before removing their trigger elements from the DOM

Examples

Explore practical tooltip implementations demonstrating initialization patterns, positioning strategies, and customization techniques. These examples showcase Chassis CSS's flexible tooltip system across various use cases.

Initialization patterns

Tooltips require explicit initialization before use. The recommended approach is to initialize all tooltips using their data-cx-toggle attribute:

const tooltipTriggerList = document.querySelectorAll('[data-cx-toggle="tooltip"]')
const tooltipList = [...tooltipTriggerList].map(tooltipTriggerEl => new chassis.Tooltip(tooltipTriggerEl))

Interactive examples

Hover over the links below to see tooltips in action within contextual content:

<p class="muted">Placeholder text to demonstrate some <a href="#" data-cx-toggle="tooltip" data-cx-title="Default tooltip">inline links</a> with tooltips. This is now just filler, no killer. Content placed here just to mimic the presence of <a href="#" data-cx-toggle="tooltip" data-cx-title="Another tooltip">real text</a>. And all that just to give you an idea of how tooltips would look when used in real-world situations. So hopefully you've now seen how <a href="#" data-cx-toggle="tooltip" data-cx-title="Another one here too">these tooltips on links</a> can work in practice, once you use them on <a href="#" data-cx-toggle="tooltip" data-cx-title="The last tip!">your own</a> site or project.</p>

Custom appearance

Customize tooltip appearance using CSS custom properties. Apply custom classes with data-cx-custom-class="custom-tooltip" to scope styling and override CSS variables for brand-specific theming.

.custom-tooltip {
  --cx-tooltip-bg-color: var(--cx-primary-60);
  --cx-tooltip-fg-color: var(--cx-primary-20);
}

<button type="button" class="button secondary"
        data-cx-toggle="tooltip" data-cx-placement="top"
        data-cx-custom-class="custom-tooltip"
        data-cx-title="This top tooltip is themed via CSS variables.">
  Custom tooltip
</button>

Positioning system

Chassis CSS tooltips support four directional placements with automatic RTL adaptation. Popper.js handles collision detection and fallback positioning for optimal visibility.

<button type="button" class="button secondary" data-cx-toggle="tooltip" data-cx-placement="top" data-cx-title="Tooltip on top">
  Tooltip on top
</button>
<button type="button" class="button secondary" data-cx-toggle="tooltip" data-cx-placement="right" data-cx-title="Tooltip on right">
  Tooltip on right
</button>
<button type="button" class="button secondary" data-cx-toggle="tooltip" data-cx-placement="bottom" data-cx-title="Tooltip on bottom">
  Tooltip on bottom
</button>
<button type="button" class="button secondary" data-cx-toggle="tooltip" data-cx-placement="left" data-cx-title="Tooltip on left">
  Tooltip on left
</button>

And with custom HTML added:

<button type="button" class="button secondary" data-cx-toggle="tooltip" data-cx-html="true" data-cx-title="<em>Tooltip</em> <u>with</u> <b>HTML</b>">
  Tooltip with HTML
</button>

With an SVG:

Disabled elements

Elements with the disabled attribute aren't interactive, meaning users cannot focus, hover, or click them to trigger a tooltip. As a workaround, you'll want to trigger the tooltip from a wrapper <div> or <span>, ideally made keyboard-focusable using tabindex="0".

<span class="d-inline-block" tabindex="0" data-cx-toggle="tooltip" data-cx-title="Disabled tooltip">
  <button class="button primary" type="button" disabled>Disabled button</button>
</span>

Accessibility

Tooltip components in Chassis CSS prioritize accessibility through semantic markup, proper ARIA attributes, and keyboard navigation support. These features ensure tooltips enhance rather than hinder the user experience for all users.

Screen readers

Tooltips utilize standard HTML title attributes and proper ARIA labeling to communicate contextual information to assistive technologies. When implemented correctly, tooltips provide supplementary information without breaking the document flow.

Keyboard navigation

Chassis CSS tooltips provide comprehensive keyboard accessibility, ensuring equal access for all users through focus management and intuitive navigation patterns:

• Tooltips appear on focus for keyboard users, ensuring equal access to interactive elements
• Press escape to dismiss visible tooltips and return focus to the trigger element
• Tooltips don't interfere with natural tab order progression

Best practices

Follow these guidelines to ensure tooltips enhance accessibility rather than create barriers for users with disabilities.

Only apply tooltips to inherently focusable, interactive elements (links, buttons, form controls) to maintain accessibility standards. While other elements can be made focusable with tabindex="0", this creates confusing tab stops for keyboard users and may not announce properly in screen readers.

CSS

Customize tooltip appearance and behavior through Chassis CSS's comprehensive styling system, featuring CSS custom properties and Sass variables for design system integration.

Custom properties

Chassis CSS tooltips utilize CSS custom properties for runtime customization and design token integration. Local CSS variables on .tooltip enable dynamic theming while maintaining backward compatibility with Sass customization.

--#{$prefix}zindex: var(--#{$prefix}tooltip-zindex, #{$zindex-tooltip});
--#{$prefix}max-width: var(--#{$prefix}tooltip-max-width, #{$tooltip-max-width});
--#{$prefix}padding-x: var(--#{$prefix}tooltip-padding-x, #{$tooltip-padding-x});
--#{$prefix}padding-y: var(--#{$prefix}tooltip-padding-y, #{$tooltip-padding-y});
--#{$prefix}margin: var(--#{$prefix}tooltip-margin, #{$tooltip-margin});
@include map-font($tooltip-font, tooltip);
--#{$prefix}fg-color: var(--#{$prefix}tooltip-fg-color, #{$tooltip-fg-color});
--#{$prefix}bg-color: var(--#{$prefix}tooltip-bg-color, #{$tooltip-bg-color});
--#{$prefix}border-radius: var(--#{$prefix}tooltip-border-radius, #{$tooltip-border-radius});
--#{$prefix}opacity: var(--#{$prefix}tooltip-opacity, #{$tooltip-opacity});
--#{$prefix}arrow-width: var(--#{$prefix}tooltip-arrow-width, #{$tooltip-arrow-width});
--#{$prefix}arrow-height: var(--#{$prefix}tooltip-arrow-height, #{$tooltip-arrow-height});

Sass variables

Design system integration through Sass variables provides comprehensive tooltip customization for build-time theming and brand alignment.

$tooltip-font:                      $cx-font-text-small-normal;
$tooltip-max-width:                 12.5rem; //200px;
$tooltip-fg-color:                  var(--#{$prefix}fg-inverse);
$tooltip-bg-color:                  var(--#{$prefix}bg-inverse);
$tooltip-border-radius:             var(--#{$prefix}border-radius-medium);
$tooltip-opacity:                   .9;
$tooltip-padding-y:                 $spacer * .25;
$tooltip-padding-x:                 $spacer * .5;
$tooltip-margin:                    null;

$tooltip-arrow-width:               .8rem;
$tooltip-arrow-height:              .4rem;

JavaScript API

Control tooltip behavior programmatically with Chassis CSS's comprehensive JavaScript interface, featuring dynamic content generation, intelligent positioning, and accessibility features.

The tooltip plugin generates content and markup on demand, placing tooltips after their trigger element by default for optimal performance and accessibility. Initialize tooltips via JavaScript:

const exampleEl = document.getElementById('example')
const tooltip = new chassis.Tooltip(exampleEl, options)

const tooltip = new chassis.Tooltip('#example', {
  boundary: document.body // or document.querySelector('#boundary')
})

Data attributes

Individual tooltip options can be specified through data attributes for declarative configuration without JavaScript initialization.

Tooltips require minimal markup while generating semantic HTML with proper ARIA attributes for optimal accessibility and screen reader support. The required markup for a tooltip is only a data attribute and title on the HTML element:

<!-- HTML to write -->
<a href="#" data-cx-toggle="tooltip" data-cx-title="Some tooltip text!">Hover over me</a>

<!-- Generated markup by the plugin -->
<div class="tooltip cx-tooltip-auto" role="tooltip">
  <div class="tooltip-arrow"></div>
  <div class="tooltip-inner">
    Some tooltip text!
  </div>
</div>

Options

Chassis components offer flexible configuration through both data attributes and JavaScript. To use data attributes, prefix any option with data-cx- followed by the option name in kebab-case format (using hyphens instead of camelCase). For example, write data-cx-custom-class="my-class" rather than data-cx-customClass="my-class".

For more complex configurations, Chassis provides the data-cx-config attribute which accepts a JSON string of multiple settings. This approach simplifies markup when configuring several options at once. If the same option appears in both data-cx-config and as a separate data attribute (like data-cx-title), the individual attribute takes precedence. You can also use JSON values in individual attributes, such as data-cx-delay='{"show":100,"hide":200}' for more granular control.

When initializing components, Chassis merges configurations from multiple sources in this priority order: default settings, data-cx-config values, individual data-cx-* attributes, and finally any JavaScript object options. Values defined later in this sequence override earlier ones.

Popper configuration

Advanced Popper.js configuration can be customized through a function that receives the default Chassis CSS configuration and returns a modified configuration object.

const tooltip = new chassis.Tooltip(element, {
  popperConfig(defaultCxPopperConfig) {
    // const newPopperConfig = {...}
    // use defaultCxPopperConfig if needed...
    // return newPopperConfig
  }
})

Methods

Chassis CSS provides a comprehensive set of methods for programmatic tooltip control, enabling dynamic content updates and lifecycle management.

const tooltip = chassis.Tooltip.getInstance('#example') // Returns a Chassis CSS tooltip instance

// setContent example
tooltip.setContent({ '.tooltip-inner': 'another title' })

Events

Listen to tooltip lifecycle events to integrate with your application logic and create responsive user interactions.

const myTooltipEl = document.getElementById('myTooltip')
const tooltip = chassis.Tooltip.getOrCreateInstance(myTooltipEl)

myTooltipEl.addEventListener('hidden.cx.tooltip', () => {
  // do something...
})

tooltip.hide()