Add section to UX guidelines for hover #8135

Activity

1. Kaitlin Brooks (kkbrooks)

   added

   API documentationAPI reference issuesAPI reference issues

   doc-enhancementsuggested addition or improvementsuggested addition or improvement

   extensibilityextension author content under /apiextension author content under /api

   on Mar 11, 2025
2. Kaitlin Brooks (kkbrooks)

   self-assigned this

   on Mar 11, 2025
3. Tyriar commented on Mar 12, 2025

   

   Daniel Imms (Tyriar)

   on Mar 12, 2025

   Contributor

   More actions

   Here are my notes I presented and action items at the end:

   Hover consistency

   Background

   • Rich content
   • Better looking than standard
   • More control

   Custom vs native

   The custom hover is mostly spread throughout the workbench but there are some cases where title is still used:

   

   

   

   Default setupDelayedHover

   setupDelayedHover(target, { content })

   Shows above the target element, aligned to the top-left.

   

   This top-left behavior originated from monaco.

   

   Default setupDelayedHoverAtMouse

   setupDelayedHoverAtMouse({ content })

   Shows just below and to the right of the cursor.

   

   This aligns closest with the native title hover.

   Locking

   Normally you can only mouse over the hover if it contains a link or action in the status bar.

   Holding alt will "lock" the hover, adding a 2px border and making the hover not go away when the mouse is moved, regardless of the specific options used. This is an accessibility feature useful to all to select text or when we explicitly hideOnHover.

   Options

   There are many options that allow devs a lot of control on how these hovers are shown. The biggest one being showPointer which centers the hover and adds a pointer.

   Some examples:

   Activity bar

   

   this._register(this.hoverService.setupDelayedHover(this.container, () => ({
   	content: this.computeTitle(),
   	position: {
   		hoverPosition: this.options.hoverOptions.position(),
   	},
   	persistence: {
   		hideOnKeyDown: true,
   	},
   	appearance: {
   		showPointer: true,
   		compact: true,
   	}
   }), { groupId: 'composite-bar-actions' }));

   Terminal tab

   

   return this._hoverService.showDelayedHover({
       ...options,
       actions: context.hoverActions,
       target: element,
       appearance: {
           showPointer: true
       },
       position: {
           hoverPosition: this._terminalConfigurationService.config.tabs.location === 'left' ? HoverPosition.RIGHT : HoverPosition.LEFT
       }
   }, { groupId: 'terminal-tabs-list' });

   Extension view item

   

   This uses the simpler API meaning it must manage the groupId and delay logic itself:

   return this.hoverService.showHover({
   	...options,
   	additionalClasses: ['extension-hover'],
   	position: {
   		hoverPosition: this.options.position(),
   		forcePosition: true,
   	},
   	persistence: {
   		hideOnKeyDown: true,
   	}
   }, focus);

   Questions

   • When should we use the 3 main types?
     • At mouse (no pointer)
     • Aligned with element/text (no pointer)
     • With pointer and centered
       • Should this be the default for showDelayedHover? Should we have a showDelayedHoverWithPointer?
       • Naming could be "PointerHover" and "MouseHover"?
         • TextHover vs Regular (pointer)?
   • Should hideOnKeyDown: true be the default?
     • Probably flip default, understand why
   • compact is used inconsistently. When should we use this?
   • Could we get rid of forcePosition if we handled the small space case better?
     • A lot of times this is used to force a horizontal only position.
     • If we marked a hover as horizontally (sidebar) or vertically (status bar) positioned, maybe we could avoid being explicit about the exact position and avoid the need for forcePosition as it's implied?

   Internal API for the VS Code devs: https://github.com/microsoft/vscode/blob/d81f6ad5b8fe26ed793a47e6911d75bafee7b3de/src/vs/base/browser/ui/hover/hover.ts#L12-L376

   Action items

   • UX to dig up MS guidelines, we should read those and come up with our own guidelines
   • hideOnKeyDown: true should be the default? Maybe we don't need it at all?
   • compact: true is a special case, we need clear guidelines to follow
   • Add hoverPosition: 'horizontal' | 'vertical' which should render forcePosition maybe obsolete completely and simplify usage
   • Aligning with text should be a special case not the default
   • Change showHover to showInstantHover, and showDelayedHover* to showHover*?
     • showDelayedHover -> showHoverAtText
     • showDelayedHoverAtMouse -> showHoverAtMouse
     • showDelayedHover will default showPointer: true?
4. Joanna Oikawa (jo-oikawa)

   unassigned

   Kaitlin Brooks (kkbrooks)

   on Sep 22, 2025
5. Nick Trogh (ntrogh)

   self-assigned this

   on Jun 23, 2026