Подсказка — для короткого текста без взаимодействия. Список действий по клику покажет CdsMenu, а диалог с формой и кнопками — CdsModal.

Внутри подсказки работает CdsOverlay: он считает координаты, переворачивает подсказку, когда у края экрана не хватает места, и держит её рядом с активатором при скролле. Поэтому пропсы позиционирования и открытия у подсказки общие с оверлеем.

Вариации

Активатор

Элемент, к которому привязана подсказка, задаётся слотом activator: пропсы слота (v-bind="props") вешают на него обработчики наведения и атрибут aria-describedby. Содержимое подсказки — проп text или слот default, когда нужна разметка. Если активатор уже свёрстан и оборачивать его не хочется, положите CdsTooltip внутрь с activator="parent" — так сделаны примеры в «Расположении» и сценариях ниже.

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>

Расположение

Проп location задаёт, с какой стороны от активатора появится подсказка: top по умолчанию, bottom, left, right — и их сочетания с выравниванием (top left, bottom right). Если места не хватает, подсказка сама перевернётся к противоположному краю. Расстояние до активатора настраивает offset.

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>

Стрелка

Стрелка указывает на активатор и следует за фактическим положением подсказки — в том числе после автоматического переворота у края экрана. Проп hide-arrow её скрывает.

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>

Способ открытия

По умолчанию подсказка открывается по наведению курсора и по фокусу с клавиатуры, без задержек. Пропсы open-delay и close-delay добавляют паузу — подсказка не мигает, когда курсор проходит мимо. Проп open-on-click с :open-on-hover="false" переключает открытие на клик.

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>

Управление показом

v-model открывает и закрывает подсказку из кода — так её показывают в ответ на события интерфейса, а не только на наведение.

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>

Рекомендации

Storybook

Сценарии использования

Панель кнопок-иконок

Кнопке-иконке подсказка возвращает название действия. CdsTooltip лежит внутри кнопки с activator="parent" — оборачивать разметку не нужно. aria-label при этом обязателен: подсказка появляется при наведении, а название действия должно быть доступно всегда.

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>

Обрезанный текст

Когда место ограничено, длинные названия обрезаются truncate — подсказка показывает полный текст при наведении на строку. Тот же проп text служит и содержимым строки, и содержимым подсказки.

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>

Недоступное действие

Заблокированная кнопка не должна молчать — подсказка объясняет, почему действие закрыто. У кнопки с disabled отключены события мыши, поэтому подсказка вешается на обёртку через activator="parent". Проп disabled самой подсказки выключает её, как только действие становится доступным.

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>

Подтверждение действия

Подсказка может подтверждать мгновенное действие без места под сообщение — например, копирование в буфер обмена. Показом управляет v-model по клику, а :open-on-hover="false" не даёт подсказке открываться от простого наведения. Через полторы секунды таймер закрывает её сам.

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>

Онбординг

Проп interactive разрешает взаимодействие с содержимым: наведение на подсказку не закрывает её, а элементы внутри остаются кликабельными. Чтобы курсор успел перейти с активатора на подсказку через зазор между ними, интерактивная подсказка закрывается с задержкой 250 мс; явный close-delay её заменяет. Вместе с open-on-click и v-model из этого собирается подсказка-онбординг: ссылка «Узнать больше» и кнопка, которая закрывает подсказку. Проп width держит ширину текста удобной для чтения.

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

Пропсы

Имя	Тип	По умолчанию	Описание
activator	(string & {}) | Element | "parent" | ComponentPublicInstance | undefined	—	Элемент, который будет активировать компонент
activatorProps	Record<string, any> | undefined	{}	Свойства для элемента активатора
attach	string | boolean | Element | undefined	—	Указывает, в какой элемент DOM следует переместить содержимое overlay. Может быть прямой ссылкой на элемент, строкой querySelector или значением true для отключения перемещения. По умолчанию используется элемент body. Как правило, не рекомендуется изменять это свойство, за исключением крайних случаев: алгоритм позиционирования по умолчанию должен справляться с большинством сценариев лучше, чем это возможно без перемещения, и может возникнуть непредвиденное поведение, если меню окажется дочерним элементом своего активатора.
closeDelay	string | number | undefined	—	Время ожидания в миллисекундах перед закрытием компонента. Работает только с параметром open-on-hover.
closeOnBack	boolean | undefined	false	Закрывает содержимое оверлея при нажатии кнопки «Назад» в браузере или вызове $router.back(), отменяя исходную навигацию. persistent оверлеи отменяют навигацию и анимируются так, как будто по ним щелкнули за пределами оверлея, вместо того чтобы закрываться.
closeOnContentClick	boolean | undefined	—	Скрыть компонент по клику на контент
color	string | undefined	—	Цвет фона подсказки.
contained	boolean | undefined	—	Ограничивает размер компонента и сетки в соответствии с его смещенным родительским элементом. Подразумевает использование свойств absolute и attach. (Примечание: родительский элемент должен иметь свойство position: relative.)
contentClass	any	—	Применяет пользовательский класс к отдельному элементу. Это удобно, поскольку содержимое перемещается в начало компонента cds-app (если не указан параметр attach) и не может быть выделено с помощью классов, переданных непосредственно в компонент.
contentProps	any	—	Применяет кастомные свойства (props) к перемещаемому контенту
disabled	boolean | null | undefined	null	Заблокированное состояние
eager	boolean | undefined	true	Принудительно рендерит содержимое компонента при его использовании. Это полезно, если у вас есть контент, который не отображается в DOM, но который необходимо проиндексировать для SEO.
height	string | number | undefined	—	Высота компонента
hideArrow	boolean | undefined	—	Скрывает стрелку-указатель, направленную на активатор. По умолчанию стрелка отображается.
id	string | undefined	—	Уникальный идентификатор для связывания подсказки с её активатором. Если не указано, будет сгенерирован автоматически.
interactive	boolean | undefined	—	Разрешает взаимодействие с содержимым подсказки: наведение курсора на контент не закрывает её. Чтобы курсор успел пересечь зазор между активатором и подсказкой, она закрывается с задержкой 250 мс, если closeDelay не задан явно.
location	Anchor | undefined	'top'	Указывает точку привязки для позиционирования компонента с использованием ориентиров для выравнивания по горизонтали, по вертикали или по обоим направлениям
locationStrategy	"static" | "connected" | LocationStrategyFunction | undefined	'connected'	Определяет способ позиционирования содержимого оверлея. По умолчанию используется значение static, при котором содержимое центрируется в контейнере. Используйте connected для привязки к элементу-активатору.
maxHeight	string | number | undefined	—	Максимальная высота компонента
maxWidth	string | number | undefined	—	Максимальная ширина компонента
minHeight	string | number | undefined	—	Минимальная высота компонента
minWidth	string | number | undefined	0	Минимальная ширина компонента
modelValue	boolean | undefined	—	Значение компонента v-model. Если компонент поддерживает свойство multiple, по умолчанию используется пустой массив.
noClickAnimation	boolean | undefined	—	Отключает эффект bounce при нажатии за пределами элемента контента при использовании атрибута persistent.
offset	string | number | number[] | undefined	10	Увеличивает расстояние до цели. Если передать два числа, второе значение смещает анкер вбок и в сторону от цели.
opacity	string | number | undefined	—	Прозрачность элемента «scrim». Применяется только в том случае, если св-во scrim=true.
openDelay	string | number | undefined	—	Время ожидания в миллисекундах перед открытием компонента. Работает только с параметром open-on-hover.
openOnClick	boolean | undefined	false	Показать компонент по клику на активатор
openOnFocus	boolean | undefined	—	Показать компонент по фокусу на активатор
openOnHover	boolean | undefined	true	Показать компонент по наведению на активатор
origin	Anchor | "auto" | "overlap" | undefined	'auto'	Устанавливает точку привязки для содержимого наложения, которая выравнивается по точке привязки «location» на объекте-цели. При значении «auto» используется противоположная сторона точки «location». При значении «overlap» используется та же точка привязки, в результате чего наложение перекрывает объект-цель. Также задает значение CSS-свойства transform-origin для transitions enter/leave.
persistent	boolean | undefined	—	Клик за пределами элемента или нажатие клавиши Esc не приведет к его закрытию.
scrim	string | boolean | undefined	false	Фон при активации overlay. Принимает значения true/false для включения фона и строку для определения цвета.
scrollStrategy	"none" | "close" | "block" | "reposition" | ScrollStrategyFunction | undefined	'reposition'	Стратегия, применяемая при активации компонента и прокрутке страницы пользователем.
stickToTarget	boolean | undefined	—	Позволяет контенту наложения выходить за пределы экрана при прокрутке.
target	(string & {}) | Element | "parent" | ComponentPublicInstance | "cursor" | [x: number, y: number] | undefined	—	Если для параметра locationStrategy задано значение «connected», необходимо указать элемент или массив координат x, y, относительно которых должен располагаться оверлей. По умолчанию в качестве такого элемента используется элемент-активатор.
text	string | undefined	—	Текст всплывающей подсказки. Используется, если не передан слот default.
theme	string | undefined	—	Тема компонента
transition	string | boolean | (TransitionProps & { component?: Component | undefined; }) | null | undefined	null	Анимация перехода
viewportMargin	string | number | undefined	12	Устанавливает пользовательские viewport margin для содержимого наложения
width	string | number | undefined	—	Ширина компонента
zIndex	string | number | undefined	2000	Значение z-index для компонента.

События

Имя	Тип	Описание
update:modelValue	[value: boolean]	Сработало при показе или скрытии подсказки. Передаёт новое состояние видимости

Слоты

Имя	Тип	Описание
activator	{ isActive: boolean; props: Record<string, any>; targetRef: TemplateRef; }	Слот для элемента, который будет выступать в роли активатора для оверлея.
default	{ isActive: Ref<boolean, boolean>; }	Слот для контента оверлея.

Exposed

Имя	Тип	Описание
activatorEl	HTMLElement | undefined	DOM-элемент активатора.
activatorRef	TemplateRef	Template ref для назначения активатора вручную.
animateClick	() => void	Запускает bounce-анимацию контента — как при клике мимо persistent-оверлея.
contentEl	HTMLElement | undefined	DOM-элемент контента оверлея.
globalTop	boolean	Является ли оверлей верхним в глобальном стеке открытых оверлеев.
rootEl	HTMLElement | undefined	Корневой DOM-элемент оверлея.
scrimEl	HTMLElement | undefined	DOM-элемент подложки (scrim), затемняющей страницу.
targetEl	HTMLElement | undefined	DOM-элемент цели позиционирования.
targetRef	TemplateRef	Template ref для назначения цели позиционирования вручную.
updateLocation	((e: Event) => void) | undefined	Пересчитывает позицию контента относительно цели.