GUILD OF GLEKS UIv21.19.0

gogTooltip

Tooltip

A hover/focus tooltip as a directive, not a component — drop it on any element, a gog-* component's own host tag or a plain native one, and that element needs to know nothing about it.

Overview

Import the directive and put it on the trigger.

typescript
import { GogTooltipDirective } from '@guildofgleks/ui';

@Component({
  // ...
  imports: [GogTooltipDirective],
})

Basic usage — hover or tab onto any of these:

Draft
<gog-button gogTooltip="Save changes">Save</gog-button>
<gog-chip gogTooltip="Not visible to anyone else yet">Draft</gog-chip>
<gog-icon name="info" gogTooltip="An icon works too" />

Examples

Position

auto (the default) picks whichever side has room, preferring top, then bottom, then right, then left. An explicit side still flips to its opposite when it has no room but the opposite does, so a tooltip near the viewport edge stays readable rather than clipped. The bubble also caps its width against the viewport.

@for (position of positions; track position) {
  <gog-button variant="outline" [gogTooltip]="'Placed ' + position" [gogTooltipPosition]="position">
    {{ position }}
  </gog-button>
}

Text and templates

gogTooltip takes a string, or a TemplateRef for richer content. A long string wraps at --gog-tooltip-max-width; past --gog-tooltip-max-height the bubble scrolls inside an internal gog-scroll. Keep it a hint: a tooltip cannot hold a control, since nothing in it can be reached by keyboard.

<gog-button variant="outline" gogTooltip="Save changes">Save</gog-button>
<!-- A long string wraps at the bubble's width cap. -->
<gog-button
  variant="outline"
  gogTooltip="Publishing makes this version visible to everyone with the link, including people outside your organisation. Earlier versions stay in the history."
>
  Publish
</gog-button>
<gog-button variant="outline" [gogTooltip]="shortcut">Undo</gog-button>
<ng-template #shortcut>Undo <kbd>Ctrl+Z</kbd></ng-template>

<gog-button variant="outline" [gogTooltip]="deployHint">Deploy</gog-button>
<ng-template #deployHint>
  <strong>Deployment blocked</strong>
  <p>Two checks are still running. <gog-tag variant="warning" size="xsm">CI</gog-tag></p>
</ng-template>

<!-- Taller than --gog-tooltip-max-height: it scrolls inside the bubble. -->
<gog-button variant="outline" [gogTooltip]="longText">Read the long one</gog-button>

Delays

gogTooltipShowDelay defaults to 300 ms, which keeps tooltips from flashing as the pointer crosses a toolbar; gogTooltipHideDelay defaults to 100 ms, which is what lets the pointer travel from the trigger onto the bubble.

<gog-button variant="outline" gogTooltip="No delay" [gogTooltipShowDelay]="0">0 ms</gog-button>
<gog-button variant="outline" gogTooltip="The default">300 ms</gog-button>
<gog-button variant="outline" gogTooltip="A full second" [gogTooltipShowDelay]="1000">
  1000 ms
</gog-button>

Hoverable, dismissible, and disabled

Move the pointer from the trigger onto the bubble: it stays, so a long one can be read (WCAG 2.1 SC 1.4.13). Press Escape while it shows: it goes, and the trigger keeps focus. gogTooltipDisabled turns one off without removing the directive.

<!-- Move onto the bubble: it stays. Press Escape: it goes, and the trigger keeps focus. -->
<gog-button variant="outline" gogTooltip="Hints can be switched off" [gogTooltipDisabled]="muted()">
  Hint {{ muted() ? 'off' : 'on' }}
</gog-button>
<gog-toggle label="gogTooltipDisabled" [(checked)]="muted" />

App-wide defaults — GOG_CONFIG

Position and both delays fall back to GOG_CONFIG.tooltip before their defaults, so a house style is set once; an instance's own input still wins. In an app the provider goes in app.config.ts — see Global Configuration.

<!-- No position or delay of its own: both come from the config. -->
<gog-button variant="outline" gogTooltip="Below, at once">Configured</gog-button>
<gog-button variant="outline" gogTooltip="The instance wins" gogTooltipPosition="right">
  gogTooltipPosition="right"
</gog-button>

Restyling one bubble

The bubble is appended to document.body, so it is never clipped by an ancestor's overflow: hidden — and so a --gog-tooltip-* token set on an ancestor of the trigger never reaches it. gogTooltipClass puts a class on the bubble itself, and the rules for that class have to come from a global stylesheet:

html
<button gogButton gogTooltip="Styled" gogTooltipClass="brand-tooltip">Styled</button>
css
/* styles.css — global, because the bubble is outside every component. */
.brand-tooltip {
  --gog-tooltip-bg: var(--gog-accent-color);
  --gog-tooltip-color: var(--gog-surface-color);
}

Visually the bubble is the same floating-panel recipe as a dialog panel or a dropdown — surface background, plain border, panel shadow — rather than a bespoke inverted bubble, so it reads as part of a themed app.

Accessibility

Shown on both hover and keyboard focus, dismissible with Escape, and hoverable so a long bubble can actually be read.

  • Description — while the bubble shows, the trigger points aria-describedby at it, so the hint is read after the trigger's own name. Hidden, it is not in the tree at all. The attribute goes on the element that takes focus — on a gog-button, the inner <button>21.15.0 — and the tooltip adds its id to whatever is already there and removes only its own, so a field's error message stays linked.
  • Keyboard — focusing the trigger shows the bubble, Escape dismisses it. Focus is tracked with focusin / focusout, which keeps it replay-safe under SSR event replay.
  • Only on something focusable — a tooltip on an element that cannot take focus is out of reach for a keyboard user. The icon in the overview is reachable by hover only; on a real page, put the hint on a control.
  • Inside a dialog the tooltip stacks above it — the dialog panel raises --gog-tooltip-z the same way it raises the dropdown's.

API Reference

Inputs

NameTypeDefaultDescription
gogTooltipstring | TemplateRef<unknown> | nullnullThe bubble’s content. A plain string for the common case, or a TemplateRef for richer markup.
gogTooltipPosition'auto' | 'top' | 'bottom' | 'left' | 'right'GOG_CONFIG.tooltip.position ?? 'auto'Which side the bubble renders on. auto prefers top, then bottom, then right, then left. An explicit side still flips to its opposite if the requested one has no room but the opposite does.
gogTooltipShowDelaynumberGOG_CONFIG.tooltip.showDelay ?? 300Milliseconds of hover or focus before the bubble appears.
gogTooltipHideDelaynumberGOG_CONFIG.tooltip.hideDelay ?? 100Milliseconds before it disappears. The gap is what lets the pointer travel from the trigger onto the bubble.
gogTooltipDisabledbooleanfalseSuppresses the tooltip without removing the directive.
gogTooltipClassstring''A class applied straight to the bubble, for restyling or resizing one instance. It must come from an unscoped (global) stylesheet — the bubble lives on document.body, outside any component’s scoped styles.

Global Configuration

Set any of these once with provideGogConfig() instead of repeating them on every instance — an instance's own input still wins when it sets one itself. See Global Configuration for the full reference.

  • GOG_CONFIG.tooltip.position
  • GOG_CONFIG.tooltip.showDelay
  • GOG_CONFIG.tooltip.hideDelay

Styling Tokens

Every CSS custom property the tooltip paints with. Override any of them — on a subtree or a theme — to restyle it. See the Theming guide for the full token-layering model, or the Theme Generator to tweak these live.

TokenDescription
--gog-tooltip-bg / -color / -border-color / -shadow / -radiusThe bubble surface. Deliberately the same floating-panel recipe as a dialog or dropdown, not a bespoke inverted bubble.
--gog-tooltip-max-width / -max-heightContent wraps at the width and scrolls past the height, inside an internal gog-scroll.
--gog-tooltip-padding / -gap / -arrow-sizeBubble padding, its distance from the trigger, and the arrow.
--gog-tooltip-font-family / -font-size / -line-heightBubble typography.
--gog-tooltip-z / -transition-durationStacking order (raised inside a dialog so a tooltip stacks above it) and fade timing.