CSC Design System v4
VueFlavour Vue React Angular TypeScriptPrimaryCSC UI ColorsPrimarySecondaryAccentCustom ColorsRedOrangeGreenBluePurplePink
Guides Getting started Customization Data visualization Migration guide Componentsc-accordionc-alertc-autocompletec-badgec-breadcrumbc-buttonc-button-groupc-cardc-checkboxc-color-pickerc-csc-logoc-data-tablec-date-pickerc-dividerc-file-uploadc-iconc-icon-buttonc-linkc-listc-loaderc-login-buttonsc-login-cardc-mainc-menuc-messagec-modalc-navigation-buttonc-number-fieldc-otp-inputc-pagec-paginationc-popoverc-progress-barc-progress-circlec-radio-groupc-selectc-side-navigationc-sliderc-spinnerc-statusc-stepsc-switchc-tablec-tabsc-tagsc-text-fieldc-time-pickerc-toastsc-toolbarc-tooltipc-tree-select

<c-tooltip>

A non-interactive text hint shown when its trigger is hovered or keyboard-focused, floating in the top layer on the inverted surface tier.

Usage

Put the element the tooltip describes in the trigger slot and the hint in the text prop. For formatted content, use the content slot instead — it overrides the prop but must stay non-interactive: a tooltip is never focusable and can hold no links or buttons. If the content needs to be clicked, use c-popover.

The tooltip shows after a short hover delay (configurable via the delay prop) and immediately on keyboard focus. The trigger must be focusable for keyboard and screen-reader users to reach the hint — a c-icon-button or c-button qualifies; a bare <span> does not.

When the described element cannot be slotted, point the trigger prop at it instead — its document ID, or the element itself via property binding. The tooltip then wires hover/focus onto that element, mirrors the aria-description there, and anchors the bubble to it. Supplying both routes is a misuse: the prop wins, the slotted element gets no wiring, and a console warning flags it.

When to use

  • To name an icon-only control or clarify a truncated label.
  • Never for content the user must interact with, or for information that is available nowhere else on the page for touch users — tooltips are unreliable on touch devices.

Dismissal

The tooltip hides when the pointer leaves the trigger and panel, when focus leaves the trigger, and on Escape (without moving focus). The pointer can travel from the trigger onto the tooltip without it vanishing.

Accessibility

The tooltip implements the WCAG 1.4.13 (Content on Hover or Focus) contract: dismissable, hoverable, persistent.

The tooltip content is mirrored onto the trigger (slotted or designated) as aria-description, so screen readers announce it with the trigger even while the bubble is closed. aria-describedby is not used because ARIA ID references cannot cross the shadow boundary between the light-DOM trigger and the shadow-DOM panel (ADR-0033).

Layering

The panel is a native popover in the top layer: it is never clipped by ancestor overflow and paints above modals — correct for a tooltip triggered from inside one.

Customization

Structural styling via ::part(trigger) and ::part(panel). Colours come from the inverted-surface semantic tokens (--c-surface-inverted, --c-on-surface-inverted); override the tokens to re-theme.

Examples

Basic
Vue React Angular TypeScript
<template>
  <div class="example-row">
    <c-tooltip text="Download the report as PDF">
      <c-icon-button slot="trigger" appearance="ghost" aria-label="Download">
        <c-icon :path="mdiDownload" />
      </c-icon-button>
    </c-tooltip>

    <c-tooltip position="bottom" text="Remove the report permanently">
      <c-icon-button slot="trigger" appearance="ghost" aria-label="Remove">
        <c-icon :path="mdiTrashCanOutline" />
      </c-icon-button>
    </c-tooltip>
  </div>
</template>

<script setup lang="ts">
import { mdiDownload, mdiTrashCanOutline } from '@mdi/js';
</script>

API reference

<c-tooltip>

A non-interactive text hint shown when its trigger is hovered or keyboard-focused, floating in the top layer on the inverted surface tier.

Properties

PropertyAttributeTypeDefaultDescription
delaydelaynumber400 Delay before the tooltip shows on hover, in milliseconds. Keyboard focus shows the tooltip immediately, regardless of this value. Defaults to `400`.
distancedistancenumber4 Distance from the trigger to the tooltip, in pixels. Defaults to `4`.
openopenbooleanfalse Whether the tooltip is open. Two-way: emits `change:open`.
positionpositionCTooltipPosition'top' Preferred placement of the tooltip relative to the trigger.
texttextstring'' The tooltip text. Overridden by the `content` slot when that is populated.
triggertriggerHTMLElement | string— Designated trigger: an element elsewhere in the document that the tooltip describes — its document ID, or the element itself. The same trigger concept as the `trigger` slot, supplied by reference: the tooltip wires hover/focus, mirrors `aria-description` onto it and anchors the bubble to it. When both routes are supplied, this prop wins over the slot.

Events

EventDetailDescription
change:openbooleanFired whenever the tooltip shows or hides, carrying the new open state. Named `change:open`, not `update:open`: Vue's runtime silently drops `onUpdate:*` listeners on custom elements (`isModelListener`), so a template `@update:open` would never be attached.

Slots

SlotDescription
triggerThe element the tooltip describes (e.g. a c-icon-button)
contentFormatted tooltip content, overriding the `text` prop; must stay non-interactive (ADR-0033)

CSS parts

Style from outside with c-tooltip::part(name) — parts are the library's only styling customization API.

PartDescription
triggerThe inline wrapper around the slotted trigger, serving as the panel's anchor
panelThe floating tooltip bubble positioned against the trigger

Types

Importable from the package root: import type { … } from '@cscfi/csc-ui'

CTooltipPosition

Preferred placement of the tooltip relative to its trigger: the side, and `-start`/`-end` to align their edges on the cross axis.

export type CTooltipPosition =
  | 'bottom-end'
  | 'bottom-start'
  | 'bottom'
  | 'left-end'
  | 'left-start'
  | 'left'
  | 'right-end'
  | 'right-start'
  | 'right'
  | 'top-end'
  | 'top-start'
  | 'top';