A tooltip is for a short text without interaction. A list of actions on click is the job of CdsMenu, and a dialog with a form and buttons is the job of CdsModal.

Inside the tooltip CdsOverlay does the work: it calculates the coordinates, flips the tooltip when there is not enough room near the edge of the screen, and keeps it next to the activator while scrolling. That is why the positioning and opening props of the tooltip are shared with the overlay.

Variations

Activator

The element the tooltip is attached to is set through the activator slot: the slot props (v-bind="props") put the hover handlers and the aria-describedby attribute on it. The content of the tooltip comes from the text prop or from the default slot when you need markup. If the activator is already there and you would rather not wrap it, put CdsTooltip inside it with activator="parent" — that is how the examples in “Placement” and in the scenarios below are built.

Sandbox Storybook

<script setup lang="ts">
import { CdsButton, CdsTooltip } from '@central-design-system/components';
</script>

<template>
  <div class="flex flex-wrap items-center justify-center gap-2">
    <CdsTooltip text="Текст всплывающей подсказки">
      <template #activator="{ props }">
        <CdsButton text="Проп text" v-bind="props" />
      </template>
    </CdsTooltip>

    <CdsTooltip>
      <template #activator="{ props }">
        <CdsButton variant="soft" color="brand" text="Слот default" v-bind="props" />
      </template>
      Подсказка с <strong>разметкой</strong> внутри
    </CdsTooltip>
  </div>
</template>

Placement

The location prop sets the side of the activator the tooltip appears on: top by default, bottom, left, right — and their combinations with an alignment (top left, bottom right). If there is not enough room, the tooltip flips to the opposite side by itself. The offset prop tunes the distance to the activator.

Sandbox Storybook

<script setup lang="ts">
import { CdsButton, CdsTooltip } from '@central-design-system/components';

const locations = [
  { location: 'left', icon: 'arrow-left' },
  { location: 'top', icon: 'arrow-up' },
  { location: 'bottom', icon: 'arrow-down' },
  { location: 'top left', icon: 'arrow-up-right' },
  { location: 'top right', icon: 'arrow-up-left' },
  { location: 'bottom left', icon: 'arrow-down-right' },
  { location: 'bottom right', icon: 'arrow-down-left' },
  { location: 'right', icon: 'arrow-right' }
] as const;
</script>

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsButton
      v-for="{ location, icon } in locations"
      :key="location"
      variant="soft"
      color="neutral"
      :icon="icon"
      :aria-label="location"
    >
      <CdsTooltip activator="parent" :location="location">Всплывающая подсказка</CdsTooltip>
    </CdsButton>
  </div>
</template>

Arrow

The arrow points at the activator and follows the actual position of the tooltip — including after an automatic flip near the edge of the screen. The hide-arrow prop hides it.

Sandbox Storybook

<script setup lang="ts">
import { CdsButton, CdsTooltip } from '@central-design-system/components';
</script>

<template>
  <div class="flex flex-wrap justify-center gap-4">
    <CdsTooltip location="top" text="Со стрелкой">
      <template #activator="{ props }">
        <CdsButton text="Со стрелкой" v-bind="props" />
      </template>
    </CdsTooltip>

    <CdsTooltip location="top" hide-arrow text="Без стрелки">
      <template #activator="{ props }">
        <CdsButton variant="soft" color="neutral" text="Без стрелки" v-bind="props" />
      </template>
    </CdsTooltip>
  </div>
</template>

Opening behavior

By default the tooltip opens on hover and on keyboard focus, with no delay. The open-delay and close-delay props add a pause — the tooltip does not blink when the cursor passes by. The open-on-click prop together with :open-on-hover="false" switches opening to a click.

Sandbox Storybook

<script setup lang="ts">
import { CdsButton, CdsTooltip } from '@central-design-system/components';
</script>

<template>
  <div class="flex flex-wrap items-center justify-center gap-2">
    <CdsTooltip text="Открылась сразу по наведению">
      <template #activator="{ props }">
        <CdsButton text="Наведение" v-bind="props" />
      </template>
    </CdsTooltip>

    <CdsTooltip open-delay="300" close-delay="200" text="Открылась после паузы 300 мс">
      <template #activator="{ props }">
        <CdsButton variant="soft" color="brand" text="С задержкой" v-bind="props" />
      </template>
    </CdsTooltip>

    <CdsTooltip open-on-click :open-on-hover="false" text="Открылась по клику">
      <template #activator="{ props }">
        <CdsButton variant="soft" color="brand" text="По клику" v-bind="props" />
      </template>
    </CdsTooltip>
  </div>
</template>

Controlling the display

v-model opens and closes the tooltip from code — this is how you show it in response to interface events, not only on hover.

Sandbox Storybook

<script setup lang="ts">
import { CdsButton, CdsTooltip } from '@central-design-system/components';
import { ref } from 'vue';

const active = ref(false);
</script>

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsButton
      variant="soft"
      color="brand"
      :text="active ? 'Скрыть подсказку' : 'Показать подсказку'"
      @click="active = !active"
    />

    <CdsTooltip v-model="active" text="Подсказкой управляет v-model">
      <template #activator="{ props }">
        <CdsButton variant="soft" color="neutral" icon="info" aria-label="Информация" v-bind="props" />
      </template>
    </CdsTooltip>
  </div>
</template>

Guidelines

Storybook

Scenarios

Icon button bar

A tooltip gives an icon button back the name of its action. CdsTooltip lives inside the button with activator="parent" — there is no need to wrap the markup. aria-label is still required: the tooltip appears on hover, while the name of the action must be available at all times.

Sandbox Storybook

<script setup lang="ts">
import { CdsButton, CdsTooltip } from '@central-design-system/components';

const actions = [
  { icon: 'edit', label: 'Редактировать' },
  { icon: 'copy', label: 'Дублировать' },
  { icon: 'download', label: 'Скачать' },
  { icon: 'delete', label: 'Удалить' }
];
</script>

<template>
  <div class="flex justify-center gap-1">
    <CdsButton
      v-for="action in actions"
      :key="action.icon"
      size="sm"
      variant="soft"
      color="neutral"
      :icon="action.icon"
      :aria-label="action.label"
    >
      <CdsTooltip activator="parent" :text="action.label" />
    </CdsButton>
  </div>
</template>

Truncated text

When space is limited, long titles are cut off with truncate — the tooltip shows the full text on hover over the line. The same text prop serves both as the content of the line and as the content of the tooltip.

Sandbox Storybook

<script setup lang="ts">
import { CdsTooltip } from '@central-design-system/components';

const documents = [
  'Договор поставки оборудования № 42-СТ от 14 марта',
  'Счёт на оплату № 5512 от 2 апреля',
  'Акт сверки взаиморасчётов за первый квартал'
];
</script>

<template>
  <div class="m-auto flex w-[240px] flex-col gap-1">
    <div v-for="doc in documents" :key="doc" class="truncate text-100">
      {{ doc }}
      <CdsTooltip activator="parent" :text="doc" />
    </div>
  </div>
</template>

Unavailable action

A disabled button should not stay silent — the tooltip explains why the action is closed. A button with disabled has its mouse events turned off, so the tooltip is attached to a wrapper through activator="parent". The disabled prop of the tooltip itself turns it off as soon as the action becomes available.

Sandbox Storybook

<script setup lang="ts">
import { CdsButton, CdsCheckbox, CdsTooltip } from '@central-design-system/components';
import { ref } from 'vue';

const ready = ref(false);
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsCheckbox v-model="ready" label="Документы прикреплены" hide-details />

    <div class="inline-block">
      <CdsTooltip activator="parent" :disabled="ready" text="Прикрепите документы, чтобы отправить заявку" />
      <CdsButton :disabled="!ready" text="Отправить заявку" />
    </div>
  </div>
</template>

Confirming an action

A tooltip can confirm an instant action when there is no room for a message — copying to the clipboard, for example. The display is driven by v-model on click, and :open-on-hover="false" keeps the tooltip from opening on a plain hover. After a second and a half a timer closes it on its own.

Sandbox Storybook

<script setup lang="ts">
import { CdsButton, CdsTooltip } from '@central-design-system/components';
import { ref } from 'vue';

const copied = ref(false);

let timer: ReturnType<typeof setTimeout>;

function copy() {
  copied.value = true;
  clearTimeout(timer);
  timer = setTimeout(() => (copied.value = false), 1500);
}
</script>

<template>
  <div class="flex justify-center">
    <CdsTooltip v-model="copied" :open-on-hover="false" text="Ссылка скопирована">
      <template #activator="{ props }">
        <CdsButton
          variant="soft"
          color="brand"
          prepend-icon="link"
          text="Скопировать ссылку"
          v-bind="props"
          @click="copy"
        />
      </template>
    </CdsTooltip>
  </div>
</template>

Onboarding

The interactive prop allows interaction with the content: hovering the tooltip does not close it, and the elements inside stay clickable. So that the pointer can cross the gap from the activator to the tooltip, an interactive tooltip closes after a 250 ms delay; an explicit close-delay overrides it. Together with open-on-click and v-model this makes an onboarding tooltip: a “Learn more” link and a button that closes the tooltip. The width prop keeps the text width comfortable to read.

Sandbox Storybook

<script setup lang="ts">
import { CdsButton, CdsTooltip } from '@central-design-system/components';
import { ref } from 'vue';

const active = ref(false);
</script>

<template>
  <div class="flex justify-center">
    <CdsTooltip v-model="active" interactive location="end" open-on-click :open-on-hover="false" width="268">
      <template #activator="{ props }">
        <CdsButton variant="soft" color="neutral" icon="message" aria-label="Что нового" v-bind="props" />
      </template>

      <div class="flex flex-col py-1">
        <div class="mb-1">
          <strong>Комментарии к заявке</strong>
        </div>
        <p>Теперь вопросы поставщику можно задавать прямо в карточке заявки — нажмите на иконку комментария.</p>
        <div class="mt-4 flex items-center justify-between">
          <a href="#" class="underline">Узнать больше</a>
          <CdsButton variant="solid" color="inverse" text="Понятно" @click="active = false" />
        </div>
      </div>
    </CdsTooltip>
  </div>
</template>

API

Props

Name	Type	Default	Description
activator	(string & {}) | Element | "parent" | ComponentPublicInstance | undefined	—	The element that activates the component
activatorProps	Record<string, any> | undefined	{}	Props for the activator element
attach	string | boolean | Element | undefined	—	Sets the DOM element the overlay content is moved to. It accepts a direct element reference, a querySelector string, or true to disable moving. By default the body element is used. Changing this prop is usually not recommended except for edge cases: the default positioning algorithm handles most scenarios better than it can without moving, and unexpected behavior may appear if the menu ends up being a child of its activator.
closeDelay	string | number | undefined	—	Delay in milliseconds before the component closes. Works only together with open-on-hover.
closeOnBack	boolean | undefined	false	Closes the overlay content when the browser Back button is pressed or $router.back() is called, cancelling the original navigation. persistent overlays cancel the navigation and animate as if they were clicked outside instead of closing.
closeOnContentClick	boolean | undefined	—	Hide the component on a click on the content
color	string | undefined	—	Background color of the tooltip.
contained	boolean | undefined	—	Limits the size of the component and of its grid to the offset parent. Implies the absolute and attach props. (Note: the parent element must have position: relative.)
contentClass	any	—	Applies a custom class to the content element. This is handy because the content is moved to the beginning of the cds-app component (unless attach is set) and cannot be selected with classes passed to the component directly.
contentProps	any	—	Applies custom props to the moved content
disabled	boolean | null | undefined	null	Disabled state
eager	boolean | undefined	true	Renders the content of the component right away. Useful when you have content that is not in the DOM but has to be indexed for SEO.
height	string | number | undefined	—	Component height
hideArrow	boolean | undefined	—	Hides the arrow pointing at the activator. The arrow is shown by default.
id	string | undefined	—	Unique id that links the tooltip to its activator. Generated automatically when omitted.
interactive	boolean | undefined	—	Allows interaction with the tooltip content: hovering the content does not close it. The tooltip closes after a 250 ms delay unless closeDelay is set, so the pointer can cross the gap between the activator and the tooltip.
location	Anchor | undefined	'top'	Sets the anchor point used to position the component, aligning it horizontally, vertically or in both directions
locationStrategy	"static" | "connected" | LocationStrategyFunction | undefined	'connected'	Sets the way the overlay content is positioned. By default static is used, which centers the content in its container. Use connected to attach the content to the activator element.
maxHeight	string | number | undefined	—	Maximum component height
maxWidth	string | number | undefined	—	Maximum component width
minHeight	string | number | undefined	—	Minimum component height
minWidth	string | number | undefined	0	Minimum component width
modelValue	boolean | undefined	—	The v-model value of the component. If the component supports the multiple prop, an empty array is used by default.
noClickAnimation	boolean | undefined	—	Disables the bounce effect on a click outside the content element when persistent is set.
offset	string | number | number[] | undefined	10	Increases the distance to the target. If two numbers are passed, the second one shifts the anchor sideways, away from the target.
opacity	string | number | undefined	—	Opacity of the scrim element. Applies only when scrim=true.
openDelay	string | number | undefined	—	Delay in milliseconds before the component opens. Works only together with open-on-hover.
openOnClick	boolean | undefined	false	Show the component on a click on the activator
openOnFocus	boolean | undefined	—	Show the component when the activator gets focus
openOnHover	boolean | undefined	true	Show the component on hover over the activator
origin	Anchor | "auto" | "overlap" | undefined	'auto'	Sets the anchor point of the overlay content that is aligned with the location anchor of the target. With "auto" the opposite side of the location point is used. With "overlap" the same anchor point is used, so the overlay overlaps the target. It also sets the CSS transform-origin property for the enter/leave transitions.
persistent	boolean | undefined	—	A click outside the element or the Esc key does not close it.
scrim	string | boolean | undefined	false	Backdrop shown while the overlay is active. Accepts true/false to toggle the backdrop and a string to set its color.
scrollStrategy	"none" | "close" | "block" | "reposition" | ScrollStrategyFunction | undefined	'reposition'	Strategy applied when the component is active and the user scrolls the page.
stickToTarget	boolean | undefined	—	Lets the overlay content go off screen while scrolling.
target	(string & {}) | Element | "parent" | ComponentPublicInstance | "cursor" | [x: number, y: number] | undefined	—	When locationStrategy is set to "connected", specify the element or the array of x, y coordinates the overlay is positioned against. By default the activator element is used.
text	string | undefined	—	Text of the tooltip. Used when the default slot is not passed.
theme	string | undefined	—	Component theme
transition	string | boolean | (TransitionProps & { component?: Component | undefined; }) | null | undefined	null	Transition animation
viewportMargin	string | number | undefined	12	Sets a custom viewport margin for the overlay content
width	string | number | undefined	—	Component width
zIndex	string | number | undefined	2000	The z-index value of the component.

Events

Name	Type	Description
update:modelValue	[value: boolean]	Fires when the tooltip is shown or hidden. Passes the new visibility state

Slots

Name	Type	Description
activator	{ isActive: boolean; props: Record<string, any>; targetRef: TemplateRef; }	Slot for the element that acts as the activator of the overlay.
default	{ isActive: Ref<boolean, boolean>; }	Slot for the overlay content.

Exposed

Name	Type	Description
activatorEl	HTMLElement | undefined	The DOM element of the activator.
activatorRef	TemplateRef	Template ref for assigning the activator manually.
animateClick	() => void	Runs the bounce animation of the content — the same as on a click outside a persistent overlay.
contentEl	HTMLElement | undefined	The DOM element of the overlay content.
globalTop	boolean	Whether the overlay is the top one in the global stack of open overlays.
rootEl	HTMLElement | undefined	The root DOM element of the overlay.
scrimEl	HTMLElement | undefined	The DOM element of the scrim that dims the page.
targetEl	HTMLElement | undefined	The DOM element of the positioning target.
targetRef	TemplateRef	Template ref for assigning the positioning target manually.
updateLocation	((e: Event) => void) | undefined	Recalculates the position of the content relative to the target.