﻿---
description: Компонент всплывающей подсказки.
tags: overlay
---

# Tooltip \[tag:component]

Небольшое всплывающее окно-подсказка, открывающееся при наведении мыши на `children` (или при нажатии на мобильных устройствах).
Обычно подсказка содержит только текст. Если внутри нужна ссылка или другое действие, используйте `enableInteractive`.

```jsx
<Tooltip hideWhenReferenceHidden strategy="absolute" disableFlipMiddleware placement="bottom" description="Привет" shown>
  <Button>Наведи</Button>
</Tooltip>
```

```jsx
<Tooltip placement="right" description="Привет">
  <Button>Наведи</Button>
</Tooltip>
```

## Интерактивная подсказка

Свойство `action` позволяет добавить в подсказку интерактивный элемент. Установите `enableInteractive`,
чтобы при наведении на содержимое подсказка оставалась открытой. Свойство `closable` добавляет кнопку закрытия.

```jsx
<Tooltip
  title="Как работают подсказки"
  description="Узнайте больше о компоненте Tooltip и его возможностях."
  action={
    <Button size="s" href="https://vkui.io/components/tooltip">
      Подробнее
    </Button>
  }
  enableInteractive
  closable
>
  <Button>Наведи</Button>
</Tooltip>
```

## Пользовательская стрелка

Воспользуйтесь свойством `ArrowIcon`, чтобы переопределить иконку, которая используется по умолчанию.

Пользовательский компонент иконки должен удовлетворять следующим требованиям:

1. Иконка по умолчанию должна быть отрисована в направлении вверх.
2. Чтобы избежать проблемы с пространством между стрелкой и контентом на некоторых экранах,
   растяните кривую по высоте на `1px` и увеличьте на этот размер `height` и `viewBox` SVG.
   (смотри [https://github.com/VKCOM/VKUI/pull/4496](https://github.com/VKCOM/VKUI/pull/4496)).
3. Убедитесь, что компонент принимает все валидные для SVG параметры.
4. Убедитесь, что SVG и её элементы наследует цвет через `fill="currentColor"`.
5. Если стрелка наезжает на якорный элемент, то увеличьте смещение между целевым и всплывающим элементами.

```jsx
const ARROW_HEIGHT = 11;

const CustomIcon = (props) => {
  return (
    <svg
      width="80"
      height={ARROW_HEIGHT}
      viewBox={`0 0 80 ${ARROW_HEIGHT}`}
      xmlns="http://www.w3.org/2000/svg"
      {...props}
    >
      <path d="M40 0C33 5.5 20 10 0 10v1h80v-1C60 10 47 5.5 40 0Z" fill="currentColor" />
    </svg>
  );
};

return (
  <Tooltip
    description="У этого тултипа кастомная стрелка"
    offsetByCrossAxis={ARROW_HEIGHT}
    arrowPadding={6}
    ArrowIcon={CustomIcon}
    shown
  >
    <Button>Якорь</Button>
  </Tooltip>
);
```

## Хук useTooltip \[#use-tooltip]

Вы можете использовать хук `useTooltip`, который позволяет устанавливать якорный элемент для `Tooltip`,
не прокидывая его в качестве `children`:

```jsx
const { anchorRef, anchorProps, tooltip } = useTooltip({
  placement: 'right',
  description: 'Привет',
});

return (
  <>
    {tooltip}
    <Button getRootRef={anchorRef} {...anchorProps}>
      Наведи на меня
    </Button>
  </>
);
```

## Доступность (a11y) \[#a11y]

### Использование `disableTriggerOnFocus`

Использования `disableTriggerOnFocus` приводит к тому, что единственным механизмом активации тултипа остается `"hover"`, из-за этого события наведения не генерируются при клавиатурной навигации или скринридером.

В связи с этим данное свойство стоит использовать только для декоративных элементов с `aria-hidden`.

```jsx
<Tooltip
  aria-hidden="true"
  disableTriggerOnFocus
  description="Какая-то информация"
  aria-label="Тултип с какой-то информацией"
>
  <Button>Якорь</Button>
</Tooltip>
```

## Свойства и методы \[#api]

### Tooltip

| Свойство                  | Тип                                                           | По умолчанию | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------- | ------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `action`                  | `ReactNode`                                                   | `-`          | Элемент действия.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `appearance`              | `"accent" \| "neutral" \| "white" \| "black" \| "inversion"`  | `-`          | Стиль отображения подсказки.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `arrowHeight`             | `number`                                                      | `-`          | Высота стрелки. Складывается с `mainAxis`, чтобы стрелка не залезала на якорный элемент.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `ArrowIcon`               | `ComponentType<SVGAttributes<SVGSVGElement>>`                 | `-`          | Пользовательская SVG иконка.  Требования:  1. Иконка по умолчанию должна быть направлена вверх (a.k.a `IconUp`). 2. Чтобы избежать проблемы с пространством между стрелкой и контентом на некоторых экранах,    растяните кривую по высоте на `1px` и увеличьте на этот размер `height` и `viewBox` SVG.    (смотри [https://github.com/VKCOM/VKUI/pull/4496](https://github.com/VKCOM/VKUI/pull/4496)). 3. Убедитесь, что компонент принимает все валидные для SVG параметры. 4. Убедитесь, что SVG и её элементы наследует цвет через `fill="currentColor"`. 5. Если стрелка наезжает на якорный элемент, то увеличьте смещение между целевым и всплывающим элементами. |
| `arrowPadding`            | `number`                                                      | `-`          | Безопасная зона вокруг стрелки, чтобы та не выходила за края контента.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `children`                | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | `-`          | Целевой элемент. Всплывающее окно появится возле него.  > ⚠️ Если это пользовательский компонент, то он должен: > 1. предоставлять параметры либо `getRootRef`, либо `ref` (cм. `React.forwardRef()`) для получения ссылки на DOM-узел; > 2. принимать DOM атрибуты и события.                                                                                                                                                                                                                                                                                                                                                                                            |
| `className`               | `string`                                                      | `-`          | Пользовательские css-классы, будут добавлены на root-элемент.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `closable`                | `boolean`                                                     | `-`          | Добавляет возможность закрыть тултип через иконку-крестик.  > Работает в сочетании с `enableInteractive` или при использовании `shown` и `onShownChange`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `closeIconLabel`          | `string`                                                      | `-`          | Скрытый текст для кнопки закрытия.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `defaultShown`            | `boolean`                                                     | `-`          | Начальное состояние всплывающего элемента.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `description`             | `ReactNode`                                                   | `-`          | Текст тултипа.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `disableArrow`            | `boolean`                                                     | `-`          | Скрывает стрелку, указывающую на якорный элемент.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `disableCloseAfterClick`  | `boolean`                                                     | `-`          | Отключает закрытие по нажатию.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `disableFlipMiddleware`   | `boolean`                                                     | `-`          | Указанное значение `placement` форсируется, даже если для выпадающего элемента недостаточно места. Не оказывает влияния при `placement` значениях - `'auto' \| 'auto-start' \| 'auto-end'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `disableShiftMiddleware`  | `boolean`                                                     | `-`          | Позволяет отключить смещение по главной оси, которое не даёт всплывающему элементу выходить за границы видимой области.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `disableTriggerOnFocus`   | `boolean`                                                     | `-`          | Отключает появление при фокусе.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `enableInteractive`       | `boolean`                                                     | `-`          | Добавляет возможность наводить на тултип.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `getRootRef`              | `Ref<HTMLDivElement>`                                         | `-`          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `hideWhenReferenceHidden` | `boolean`                                                     | `-`          | Принудительно скрывает компонент если целевой элемент вышел за область видимости.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `hoverDelay`              | `number \| [number, number]`                                  | `-`          | Количество миллисекунд, после которых произойдёт показ/скрытие всплывающего элемента при наведении.  > Чтобы задать разное время на показ и скрытие, передайте массив типа `[<показ>, <скрытие>]`.  > Используется только для `trigger="hover"`.                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `maxWidth`                | `string \| number \| null`                                    | `-`          | Перебивает максимальную ширину заданную по умолчанию.  Передача `null` полностью сбрасывает установку `max-width` на элемент.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `offsetByCrossAxis`       | `number`                                                      | `-`          | Отступ по вспомогательной оси.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `offsetByMainAxis`        | `number`                                                      | `-`          | Отступ по главной оси.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `onPlacementChange`       | `OnPlacementChange`                                           | `-`          | В зависимости от области видимости, позиция может смениться на более оптимальную, чтобы всплывающий элемент вместился в эту область видимости.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `onReferenceHiddenChange` | `((hidden: boolean) => void)`                                 | `-`          | Событие скрытия / раскрытия компонента при использовании свойства `hideWhenReferenceHidden`.  > Стоит иметь ввиду, что событие также будет вызвано и при новом рендере компонента                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `onShownChange`           | `OnShownChange`                                               | `-`          | Вызывается при каждом изменении видимости всплывающего элемента.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `overflowPadding`         | `Padding`                                                     | `-`          | Отступ для смещения.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `placement`               | `PlacementWithAuto`                                           | `-`          | По умолчанию компонент выберет наилучшее расположение сам, но приоритетное можно задать с помощью этого свойства.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `ref`                     | `Ref<HTMLDivElement>`                                         | `-`          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `shown`                   | `boolean`                                                     | `-`          | Передача `boolean` позволяет контролировать состояния показа и скрытия вручную. Используйте совместно с `onShownChange`.  > Если нужно разово инициировать показ тултипа при первом рендере, то используйте `defaultShown`.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `strategy`                | `Strategy`                                                    | `-`          | Стратегия позиционирования всплывающего элемента.  - `"fixed"` - позиционируется, используя `position: fixed`. Является значением по умолчанию - `"absolute"` - позиционируется, используя `position: absolute`, относительно ближайшего элемента с `position: relative`  > `strategy="absolute"` Рекомендуется использовать с `usePortal={false}`. И нужно не забыть обернуть в элемент с `position: relative`                                                                                                                                                                                                                                                           |
| `title`                   | `ReactNode`                                                   | `-`          | Заголовок тултипа.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `titleId`                 | `string`                                                      | `-`          | \[a11y] Id для заголовка тултипа. Можно использовать для связи элемента с `role="dialog"` и заголовка через `aria-labelledby`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `usePortal`               | `boolean \| HTMLElement \| RefObject<HTMLElement \| null>`    | `-`          | По умолчанию используется document.body.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `zIndex`                  | `string \| number`                                            | `-`          | Перебивает zIndex заданный по умолчанию.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

### useTooltip

| Свойство                  | Тип                                                          | По умолчанию                  | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------- | ------------------------------------------------------------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `action`                  | `ReactNode`                                                  | `-`                           | Элемент действия.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `appearance`              | `"accent" \| "neutral" \| "white" \| "black" \| "inversion"` | `neutral`                     | Стиль отображения подсказки.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `arrowHeight`             | `number`                                                     | `8`                           | Высота стрелки. Складывается с `mainAxis`, чтобы стрелка не залезала на якорный элемент.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `ArrowIcon`               | `ComponentType<SVGAttributes<SVGSVGElement>>`                | `-`                           | Пользовательская SVG иконка.  Требования:  1. Иконка по умолчанию должна быть направлена вверх (a.k.a `IconUp`). 2. Чтобы избежать проблемы с пространством между стрелкой и контентом на некоторых экранах,    растяните кривую по высоте на `1px` и увеличьте на этот размер `height` и `viewBox` SVG.    (смотри [https://github.com/VKCOM/VKUI/pull/4496](https://github.com/VKCOM/VKUI/pull/4496)). 3. Убедитесь, что компонент принимает все валидные для SVG параметры. 4. Убедитесь, что SVG и её элементы наследует цвет через `fill="currentColor"`. 5. Если стрелка наезжает на якорный элемент, то увеличьте смещение между целевым и всплывающим элементами. |
| `arrowPadding`            | `number`                                                     | `10`                          | Безопасная зона вокруг стрелки, чтобы та не выходила за края контента.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `className`               | `string`                                                     | `-`                           | Пользовательские css-классы, будут добавлены на root-элемент.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `closable`                | `boolean`                                                    | `-`                           | Добавляет возможность закрыть тултип через иконку-крестик.  > Работает в сочетании с `enableInteractive` или при использовании `shown` и `onShownChange`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `closeIconLabel`          | `string`                                                     | `-`                           | Скрытый текст для кнопки закрытия.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `defaultShown`            | `boolean`                                                    | `-`                           | Начальное состояние всплывающего элемента.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `description`             | `ReactNode`                                                  | `-`                           | Текст тултипа.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `disableArrow`            | `boolean`                                                    | `false`                       | Скрывает стрелку, указывающую на якорный элемент.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `disableCloseAfterClick`  | `boolean`                                                    | `false`                       | Отключает закрытие по нажатию.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `disableFlipMiddleware`   | `boolean`                                                    | `false`                       | Указанное значение `placement` форсируется, даже если для выпадающего элемента недостаточно места. Не оказывает влияния при `placement` значениях - `'auto' \| 'auto-start' \| 'auto-end'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `disableShiftMiddleware`  | `boolean`                                                    | `false`                       | Позволяет отключить смещение по главной оси, которое не даёт всплывающему элементу выходить за границы видимой области.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `disableTriggerOnFocus`   | `boolean`                                                    | `false`                       | Отключает появление при фокусе.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `enableInteractive`       | `boolean`                                                    | `false`                       | Добавляет возможность наводить на тултип.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `getRootRef`              | `Ref<HTMLDivElement>`                                        | `-`                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `hideWhenReferenceHidden` | `boolean`                                                    | `-`                           | Принудительно скрывает компонент если целевой элемент вышел за область видимости.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `hoverDelay`              | `number \| [number, number]`                                 | `150`                         | Количество миллисекунд, после которых произойдёт показ/скрытие всплывающего элемента при наведении.  > Чтобы задать разное время на показ и скрытие, передайте массив типа `[<показ>, <скрытие>]`.  > Используется только для `trigger="hover"`.                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `maxWidth`                | `string \| number \| null`                                   | `-`                           | Перебивает максимальную ширину заданную по умолчанию.  Передача `null` полностью сбрасывает установку `max-width` на элемент.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `offsetByCrossAxis`       | `number`                                                     | `0`                           | Отступ по вспомогательной оси.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `offsetByMainAxis`        | `number`                                                     | `8`                           | Отступ по главной оси.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `onPlacementChange`       | `OnPlacementChange`                                          | `-`                           | В зависимости от области видимости, позиция может смениться на более оптимальную, чтобы всплывающий элемент вместился в эту область видимости.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `onReferenceHiddenChange` | `((hidden: boolean) => void)`                                | `-`                           | Событие скрытия / раскрытия компонента при использовании свойства `hideWhenReferenceHidden`.  > Стоит иметь ввиду, что событие также будет вызвано и при новом рендере компонента                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `onShownChange`           | `OnShownChange`                                              | `-`                           | Вызывается при каждом изменении видимости всплывающего элемента.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `overflowPadding`         | `Padding`                                                    | `-`                           | Отступ для смещения.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `placement`               | `PlacementWithAuto`                                          | `bottom`                      | По умолчанию компонент выберет наилучшее расположение сам, но приоритетное можно задать с помощью этого свойства.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `ref`                     | `Ref<HTMLDivElement>`                                        | `-`                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `shown`                   | `boolean`                                                    | `-`                           | Передача `boolean` позволяет контролировать состояния показа и скрытия вручную. Используйте совместно с `onShownChange`.  > Если нужно разово инициировать показ тултипа при первом рендере, то используйте `defaultShown`.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `strategy`                | `Strategy`                                                   | `-`                           | Стратегия позиционирования всплывающего элемента.  - `"fixed"` - позиционируется, используя `position: fixed`. Является значением по умолчанию - `"absolute"` - позиционируется, используя `position: absolute`, относительно ближайшего элемента с `position: relative`  > `strategy="absolute"` Рекомендуется использовать с `usePortal={false}`. И нужно не забыть обернуть в элемент с `position: relative`                                                                                                                                                                                                                                                           |
| `title`                   | `ReactNode`                                                  | `-`                           | Заголовок тултипа.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `titleId`                 | `string`                                                     | `-`                           | \[a11y] Id для заголовка тултипа. Можно использовать для связи элемента с `role="dialog"` и заголовка через `aria-labelledby`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `usePortal`               | `boolean \| HTMLElement \| RefObject<HTMLElement \| null>`   | `-`                           | По умолчанию используется document.body.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `zIndex`                  | `string \| number`                                           | `var(--vkui--z_index_popout)` | Перебивает zIndex заданный по умолчанию.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
