hover

Hovers and tooltips

Keep hovers Calm on first entry and Consistent while moving between related controls: the first hover waits for workbench.hover.delay, then nearby, similar targets show their hovers immediately while the hover interaction remains active. Widget boundaries must not introduce another delay.

Use custom hovers by default

• Use the widget's hover API or IHoverService, not native browser tooltips via element.title or setAttribute('title', ...). Remove conflicting HTML title attributes when introducing a custom hover.
• A widget's title or tooltip option can still be correct when the widget routes it through the custom-hover machinery. Inspect the implementation rather than banning properties by name.
• Keep native tooltips a narrow exception for controls inside an existing custom hover/context view when opening another custom hover would interfere with the parent. Pass nativeHoverDelegate through the widget's supported hoverDelegate option instead of hand-writing title attributes.
• Do not turn an entire feature native to solve one nested control's problem. The current HoverService supports limited nested hovers, so nesting is not universally impossible; check the actual parent/context-view interaction before choosing this exception.

Choose placement and pointer together

Here, pointer means the small arrow connecting the hover to its target, not the mouse cursor.

Target	Placement	Pointer
Small buttons, toolbar actions, icon actions, and other small clickable targets	Element-anchored	Always
Ordinary list/tree items with simple text tooltips	Mouse-anchored	Never
List/tree items with rich, information-heavy hovers	Element-anchored, to the left or right of the row	Always
Other UI elements	Normally element-anchored	Always when element-anchored

• For delayed element hovers, use setupDelayedHover with style: HoverStyle.Pointer, or explicitly set appearance.showPointer: true. Bare setupDelayedHover does not automatically add a pointer. HoverStyle.Pointer also defaults to compact styling; use explicit appearance options when that is not appropriate for rich content.
• For mouse placement, use setupDelayedHoverAtMouse, normally with style: HoverStyle.Mouse. Never request a pointer. This API excludes position and pointer overrides from its public options; it positions relative to the mouse.
• For rich row hovers, set position.hoverPosition to HoverPosition.LEFT or HoverPosition.RIGHT so the hover does not cover neighboring rows. Preserve normal viewport-aware fallback unless the feature specifically requires forced positioning.
• For delegate-based widgets, use placement: 'element' with a pointer, or placement: 'mouse' without one. The managed-hover path derives the pointer from the delegate's placement; preserve this pairing in custom delegates and overrides too.

Choose the API the widget supports

Read the target widget and its surrounding component before wiring a hover.

Surface	API
Existing widgets accepting hoverDelegate, such as buttons, action items, action bars, and toolbars	Pass a shared instant-enabled IHoverDelegate
New direct hover registrations, or widgets accepting hoverLifecycleOptions	Use delayed hovers with a shared lifecycle groupId
A feature already owns the triggering events and needs to control showing the hover	Use showDelayedHover(options, { groupId }) and own the returned hover's lifecycle

Prefer setupDelayedHover / setupDelayedHoverAtMouse for new direct registrations. setupManagedHover is deprecated, but existing widgets still use it internally through hoverDelegate; do not bypass their supported API or rewrite them unnecessarily.

Inject IHoverService through the constructor where available. In vs/base, where importing platform services would violate layering, use getBaseLayerHoverDelegate() for direct registrations, or accept a delegate/lifecycle option from the caller.

Do not use unconditional showInstantHover, a zero delay, a custom timer, or reducedDelay as a substitute for grouping. The first ordinary pointer-triggered hover must still respect the configured workbench delay.

Share instant-hover state across the visual group

Choose the boundary by what the user sees, not by class ownership. Two toolbars next to each other with similar-looking actions form one hover group, even though they are separate widget instances. Likewise, adjacent individually rendered action items should share state.

Delegate-based widgets

Create one createInstantHoverDelegate() at the common owner and pass the same instance to every related widget:

const hoverDelegate = this._register(createInstantHoverDelegate());

const primaryToolbar = this._register(this.instantiationService.createInstance(
	WorkbenchToolBar, primaryContainer, { hoverDelegate }
));
const secondaryToolbar = this._register(this.instantiationService.createInstance(
	WorkbenchToolBar, secondaryContainer, { hoverDelegate }
));

• The factory creates an element-placement, instant-enabled delegate. The initial hover uses the workbench delay; subsequent hovers using that instance can skip the delay during its short recently-hidden grace window.
• getDefaultHoverDelegate('element') gives element placement but does not enable instant hover.
• ToolBar and ActionBar create their own instant delegate when none is supplied. That groups items within each widget, not across two neighboring widgets. Explicitly supply the common delegate to connect them.
• Forward the incoming action-view-item options in custom actionViewItemProvider implementations, especially hoverDelegate. Pass the same delegate to separately constructed action items and buttons too. Creating a delegate per item, per toolbar, or inside the provider breaks the shared behavior.
• If constructing WorkbenchHoverDelegate for feature-specific overrides, enable { instantHover: true } for an element-placement group and share that instance. Do not accidentally disable the pointer through appearance overrides.

Delayed hovers

Choose one stable groupId for related targets and pass it in the lifecycle options, not the hover's content/appearance options:

const hoverLifecycleOptions: IHoverLifecycleOptions = { groupId: generateUuid() };

store.add(hoverService.setupDelayedHover(firstTarget, {
	content: firstTooltip,
	style: HoverStyle.Pointer
}, hoverLifecycleOptions));
store.add(hoverService.setupDelayedHover(secondTarget, {
	content: secondTooltip,
	style: HoverStyle.Pointer
}, hoverLifecycleOptions));

Here store owns this rendered surface and the tooltip strings are already localized. Create the group once for that surface, not inside each registration or options factory. Pass it into adjacent child widgets that expose hoverLifecycleOptions.

• A delayed hover skips the delay when a currently visible hover belongs to the same group. Unlike the delegate path, this is not a shared recently-hidden timer.
• Use a per-instance UUID when independent instances must stay separate. A feature-specific string is appropriate only when all uses intentionally belong to the same group.
• Do not use one generic global ID for unrelated controls, or a new ID for each item. Do not confuse groupId with IHoverOptions.id, which controls hover equality, not grouping.
• The delegate and delayed-hover mechanisms are separate. A groupId does not connect to an IHoverDelegate's state. When a visual group spans both APIs, inspect the widgets' supported extension points and align the group deliberately; do not assume the two mechanisms automatically coordinate.

For rich list rows, keep the row's group separate from dissimilar inline actions and combine it with side placement:

store.add(hoverService.setupDelayedHover(rowElement, {
	content: richContent,
	appearance: { showPointer: true },
	position: { hoverPosition: HoverPosition.RIGHT }
}, rowHoverLifecycleOptions));

Reuse rowHoverLifecycleOptions across the related rows; it contains their stable groupId.

Ownership and accessibility

• Register a newly created scoped delegate immediately with its owner's disposable store. A delegate supplied by a parent is borrowed; the parent owns its disposal.
• Register delayed-hover listeners and manually shown hover widgets with the appropriate component, template, or render store. Repeated rendering must not accumulate registrations on a long-lived store. Keep the delegate/group stable for the intended interaction lifetime.
• Use localized tooltip text. Preserve accessible names, keyboard activation, focus restoration, and Escape dismissal; a tooltip is not a substitute for an accessible label.
• For delayed hovers, setupKeyboardEvents: true adds Enter/Space handling to show and focus the hover. Use it only when those keys are not already owned by the target's action or navigation behavior.
• Keep rich hover content and its links/actions reachable. Do not force hideOnHover: true on content the user must interact with. Follow the accessibility skill for the surrounding feature.