Replace BTooltip dependency with our own @floating-ui/dom based tooltip engine

Summary

Replaces the bootstrap-vue tooltip implementation (<b-tooltip> / v-b-tooltip) with a new implementation built on @floating-ui/dom. This removes a key blocker for Vue 3 migration.

Curious? Integration MR for GitLab here 👉 gitlab-org/gitlab!223882 (closed)

Why This Change?

  • bootstrap-vue is Vue 2-only and unmaintained - blocks Vue 3 migration
  • Popper.js v1 is deprecated - @floating-ui/dom is its actively maintained successor
  • Zero new dependencies - @floating-ui/dom is already in the project

Why @floating-ui/dom?

Option Verdict Reason
@floating-ui/vue ❌ Vue 3 only
@floating-ui/dom ✅ Chosen Framework-agnostic, works with Vue 2, Vue 3, and vanilla JS
Tippy.js ❌ Additional dependency; we already have @floating-ui/dom
Headless UI / Radix Vue ❌ Vue 3 only

@floating-ui/dom only handles positioning. We built the lifecycle, events, accessibility, and Vue layers ourselves - this gives us full control and enables reuse for the popover migration.

Architecture

┌─────────────────────────────────────────────────────────┐
│  GlTooltip Component    │    v-gl-tooltip Directive     │  Vue layer
├─────────────────────────┴───────────────────────────────┤
│                    tooltip_engine.js                    │  Core engine
├─────────────────────────────────────────────────────────┤
│                     @floating-ui/dom                    │  Positioning
└─────────────────────────────────────────────────────────┘

tooltip_engine.js - Framework-agnostic class handling:

  • Positioning via computePosition() with flip(), shift(), offset(), arrow() middleware
  • Auto-updating via autoUpdate()
  • Event handling (hover, focus, click triggers with delays)
  • DOM lifecycle and accessibility (role="tooltip", aria-describedby)

Directive - Parses modifiers (.top, .hover, .ds500, .html, etc.) into engine options

Component - Provides props/slots/events API for HTML tooltip content

API Compatibility

Full backward compatibility - no migration required for consumers.

  • ✅ All directive modifiers
  • ✅ All component props and events
  • ✅ Programmatic control (open, close, enable, disable)
  • ✅ Default container via setGlTooltipDefaultContainer()

Vue 2/3 Compatibility

Feature Vue 2 @vue/compat Vue 3 (native)
Directive hooks ✅ ✅ ✅
Lifecycle hooks ✅ ✅ ✅
$scopedSlots ✅ ✅ ❌ *
$on / $off ✅ ✅ ❌ *
Tooltip engine ✅ ✅ ✅

* These patterns are used in 74+ places across the codebase and will be addressed in a broader migration effort when moving from compat mode to native Vue 3.

Changes

New

  • src/components/base/tooltip/tooltip_engine.js

Modified

  • src/components/base/tooltip/tooltip.vue - Rewritten to use new engine
  • src/components/base/tooltip/tooltip.scss - Added positioning styles
  • src/directives/tooltip/tooltip.js - Rewritten to use new engine
  • src/config.js - Removed BTooltip config
  • src/scss/bootstrap_vue.scss - Removed tooltip scss import
  • src/components/base/tooltip/tooltip.stories.js - Removed bootstrap docs
  • contents/components/tooltip.md - Updated API documentation

Not Changed (Yet)

vendor/bootstrap-vue/src/components/tooltip/ is kept because BPopover extends BTooltip. Will be removed when popover is migrated.

Testing

All 36 tooltip tests pass, covering: show/hide, modifiers, containers, accessibility, programmatic control.

Edited by Thomas Hutterer

Merge request reports

Loading
Loading