﻿---
description: Компонент для отрисовки подсказки, когда пользователю хочется представить новый функционал.
tags: overlay
---

# OnboardingTooltip \[tag:component]

Компонент для отрисовки подсказки, как правило в случаях, когда
пользователю хочется представить новый функционал.

> Для показа всплывающей подсказки по нажатию или наведению используйте [`Tooltip`](/components/tooltip).

```jsx
<OnboardingTooltip shown disableFlipMiddleware disableShiftMiddleware placement="bottom" description="Обновлённый раздел поможет найти друзей">
  <Icon20UserCheckOutline />
</OnboardingTooltip>
```

```jsx
<OnboardingTooltip shown description="Обновлённый раздел поможет найти друзей">
  <Icon20UserCheckOutline />
</OnboardingTooltip>
```

## Концепция

Показывать данные подсказки пользователю следует один раз, запоминая факт показа между
сессиями. Рекомендуется показывать подсказку сразу после того, как нужный элемент появился в зоне видимости.
Воспользуйтесь [Intersection Observer API](https://developer.mozilla.org/ru/docs/Web/API/Intersection_Observer_API) для реализации
такого поведения.

> На странице не может быть две одновременно показанных подсказки. Они всегда должны показываться
> последовательно: следующая показывается при закрытии текущей и так далее.

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

Если хочется снабдить какой-то элемент интерфейса подсказкой,
достаточно просто обернуть его в компонент `OnboardingTooltip`.

## OnboardingTooltipContainer \[tag:component]

Обычно компонент используется в контексте [`Panel`](/components/panel),
[`PanelHeader`](/components/panel-header) или [`FixedLayout`](/components/fixed-layout), поэтому вам
не нужно задумываться о позиционировании подсказки.

Если возникла потребность использовать `OnboardingTooltip` вне контекста перечисленных компонентов,
следуйте следующим инструкциям:

* в контейнере с прокруткой — замените какой-нибудь элемент, внутри которого нет прокрутки,
  на `<OnboardingTooltipContainer>` и добавьте ему css-свойство `position: relative` (или другую не-`static`);
* внутри `position: fixed` используйте `<OnboardingTooltipContainer fixed>`.

## Цветовые варианты

```jsx
<OnboardingTooltip placement="bottom" description={`appearance="accent"`} appearance="accent">
  <div style={{ width: 50, margin: 10 }}>
    <Avatar />
  </div>
</OnboardingTooltip>
<OnboardingTooltip placement="top" description={`appearance="neutral"`} appearance="neutral">
  <div style={{ width: 50, margin: 10 }}>
    <Avatar />
  </div>
</OnboardingTooltip>
<OnboardingTooltip placement="bottom" description={`appearance="white`} appearance="white">
  <div style={{ width: 50, margin: 10 }}>
    <Avatar />
  </div>
</OnboardingTooltip>
<OnboardingTooltip placement="top" description={`appearance="black"`} appearance="black">
  <div style={{ width: 50, margin: 10 }}>
    <Avatar />
  </div>
</OnboardingTooltip>
<OnboardingTooltip
  placement="bottom"
  description={`appearance="inversion"`}
  appearance="inversion"
>
  <div style={{ width: 50, margin: 10 }}>
    <Avatar />
  </div>
</OnboardingTooltip>
```

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

`OnboardingTooltip` технически является модальным окном (`role="dialog"`),
а значит у него обязательно должно быть имя — его краткое название.
Благодаря этому пользователи вспомогательных технологий знают, что это за элемент и какое у него содержимое.

Задать имя можно с помощью следующих способов:

* используя свойство `title`;
* используя свойство `aria-label`;
* используя свойство `aria-labelledby`;

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

| Свойство                 | Тип                                                           | По умолчанию   | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------ | ------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `action`                 | `ReactNode`                                                   | `-`            | Элемент действия.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `appearance`             | `"accent" \| "neutral" \| "white" \| "black" \| "inversion"`  | `-`            | Стиль отображения подсказки.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `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. Если стрелка наезжает на якорный элемент, то увеличьте смещение между целевым и всплывающим элементами. |
| `arrowOffset`            | `number`                                                      | `0`            | Сдвиг стрелки относительно текущих координат.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `arrowPadding`           | `number`                                                      | `10`           | Безопасная зона вокруг стрелки, чтобы та не выходила за края контента.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `arrowRef`               | `Element \| MutableRefObject<Element \| null> \| null`        | `-`            |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `children`               | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | `-`            | Целевой элемент. Всплывающее окно появится возле него.  > ⚠️ Если это пользовательский компонент, то он должен: > 1. предоставлять параметры либо `getRootRef`, либо `ref` (cм. `React.forwardRef()`) для получения ссылки на DOM-узел; > 2. принимать DOM атрибуты и события.                                                                                                                                                                                                                                                                                                                                                                                            |
| `className`              | `string`                                                      | `-`            | Пользовательские css-классы, будут добавлены на root-элемент.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `description`            | `ReactNode`                                                   | `-`            | Текст тултипа.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `disableArrow`           | `boolean`                                                     | `false`        | Скрывает стрелку, указывающую на якорный элемент.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `disableFlipMiddleware`  | `boolean`                                                     | `false`        | Указанное значение `placement` форсируется, даже если для выпадающего элемента недостаточно места. Не оказывает влияния при `placement` значениях - `'auto' \| 'auto-start' \| 'auto-end'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `disableFocusTrap`       | `boolean`                                                     | `-`            | Позволяет отключить захват фокуса.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `disableShiftMiddleware` | `boolean`                                                     | `false`        | Позволяет отключить смещение по главной оси, которое не даёт всплывающему элементу выходить за границы видимой области.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `getRootRef`             | `Ref<HTMLDivElement>`                                         | `-`            |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `isStaticArrowOffset`    | `boolean`                                                     | `false`        | Включает абсолютное смещение по `arrowOffset`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `maxWidth`               | `string \| number \| null`                                    | `220`          | Перебивает максимальную ширину заданную по умолчанию.  Передача `null` полностью сбрасывает установку `max-width` на элемент.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `offsetByCrossAxis`      | `number`                                                      | `0`            | Отступ по вспомогательной оси.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `offsetByMainAxis`       | `number`                                                      | `0`            | Отступ по главной оси.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `onClose`                | `((this: void) => void)`                                      | `-`            | Обработчик, который вызывается при нажатии по любому месту в пределах экрана.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `onPlacementChange`      | `OnPlacementChange`                                           | `-`            | В зависимости от области видимости, позиция может смениться на более оптимальную, чтобы всплывающий элемент вместился в эту область видимости.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `overflowPadding`        | `Padding`                                                     | `-`            | Отступ для смещения.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `overlayLabel`           | `string`                                                      | `Закрыть`      | \[a11y] Метка для подложки-кнопки, для описания того, что произойдёт при нажатии.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `placement`              | `PlacementWithAuto`                                           | `bottom-start` | По умолчанию компонент выберет наилучшее расположение сам, но приоритетное можно задать с помощью этого свойства.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `ref`                    | `Ref<HTMLDivElement>`                                         | `-`            |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `restoreFocus`           | `boolean \| (() => boolean \| HTMLElement)`                   | `true`         | Управление поведением возврата фокуса при закрытии всплывающего окна.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `shown`                  | `boolean`                                                     | `true`         | Если передан, то всплывающий элемент будет показано/скрыто в зависимости от значения свойства.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `title`                  | `ReactNode`                                                   | `-`            | Заголовок тултипа.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `titleId`                | `string`                                                      | `-`            | \[a11y] Id для заголовка тултипа. Можно использовать для связи элемента с `role="dialog"` и заголовка через `aria-labelledby`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
