Popover

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

Загружается...

Функциональность

Компонент позволяет отобразить всплывающее окно, позиционированное рядом с якорным элементом. В качестве якорного используется элемент, переданный в свойство children.

Механизм вызова всплывающего окна

Свойство trigger определяет способ взаимодействия, при котором всплывающее окно будет отображаться или скрываться.

`"click"`

Показ/скрытие происходит при нажатии на якорный элемент;

Загружается...

`"hover"`

Показ происходит при наведении мыши на якорных элемент, скрытие - при отведении.

Используйте как единственный механизм активации только для декоративных элементов в сочетании с aria-hidden и disableFocusTrap (см. секцию Доступность (a11y))

Загружается...

`"focus"`

Показ происходит при фокусе на якорном элементе, скрытие - при потере фокуса;

Загружается...

Показ/скрытие контролируется только через свойство shown. Обработчик, переданный в свойство onShownChange, будет вызываться при нажатии за пределами якорного и всплывающего элементов, а также по кнопке ESC.

Загружается...

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

Загружается...

Текстовые метки

Старайтесь сопровождать элемент текстовым описанием для корректной работы скринридеров. Для этого необходимо вручную передавать некоторые параметры.

у всплывающего элемента обязательно должен быть указан role ↗. Зачастую это либо "tooltip" ↗, либо "dialog" ↗;
у якорного элемента, в зависимости от role всплывающего элемента, должны быть заданы атрибуты aria-*. Какие именно можно ознакомиться в документации конкретного role.

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

Если нужно, чтобы контент из Popover был доступен, комбинируйте hover с триггером focus.

// ❌ WCAG
<Popover trigger="hover">{children}</Popover>
 
// ✅ WCAG
<Popover trigger={['hover', 'focus']}>{children}</Popover>

Свойства и методы

Свойство	Описание
`arrow`	`boolean` Отображать ли стрелку, указывающую на якорный элемент. По умолчанию: `-`
`arrowHeight`	`number` Высота стрелки. Складывается с `mainAxis`, чтобы стрелка не залезала на якорный элемент. По умолчанию: `-`
`ArrowIcon`	`ComponentType<SVGAttributes<SVGSVGElement>>` Пользовательская SVG иконка. Требования: Иконка по умолчанию должна быть направлена вверх (a.k.a `IconUp`). Чтобы избежать проблемы с пространством между стрелкой и контентом на некоторых экранах, растяните кривую по высоте на `1px` и увеличьте на этот размер `height` и `viewBox` SVG. (смотри https://github.com/VKCOM/VKUI/pull/4496 ↗). Передайте высоту иконки в параметр `arrowHeight`. В значении высоты можно исключить хак с `1px` из п.2. Убедитесь, что компонент принимает все валидные для SVG параметры. Убедитесь, что SVG и её элементы наследует цвет через `fill="currentColor"`. По умолчанию: `-`
`arrowPadding`	`number` Безопасная зона вокруг стрелки, чтобы та не выходила за края контента. По умолчанию: `-`
`arrowProps`	`PopoverArrowProps` Позволяет набросить на стрелку пользовательские атрибуты. По умолчанию: `-`
`autoFocus`	`boolean \| "root"` Управление автоматическим фокусом при открытии всплывающего элемента. По умолчанию: `-`
`children`	`ReactElement<unknown, string \| JSXElementConstructor<any>>` Целевой элемент. Всплывающее окно появится возле него. ⚠️ Если это пользовательский компонент, то он должен: предоставлять параметры либо `getRootRef`, либо `ref` (cм. `React.forwardRef()`) для получения ссылки на DOM-узел; принимать DOM атрибуты и события. По умолчанию: `-`
`closeAfterClick`	`boolean` При `trigger="hover"` закрывает всплывающий элемент при нажатии на целевой элемент. По умолчанию: `-`
`content`	`ReactNode \| FloatingContentRenderProp` Содержимое всплывающего окна. При передаче контента в виде render prop ↗, в аргументе функции можно получить метод `onClose`, с помощью которого можно программно закрывать всплывающее окно. По умолчанию: `-`
`customMiddlewares`	`{ name: string; options?: any; fn: (state: { placement: Placement; platform: Platform; strategy: Strategy; x: number; y: number; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; elements: Elements; }) => Promisable<...>; }[]` Массив кастомных модификаторов для Popper (необходимо мемоизировать). По умолчанию: `-`
`defaultShown`	`boolean` Начальное состояние всплывающего элемента. По умолчанию: `-`
`disableCloseOnClickOutside`	`boolean` Отключает закрытие нажатием на область вне целевого и всплывающего элемента. По умолчанию: `-`
`disableCloseOnEscKey`	`boolean` Отключает закрытие нажатием на кнопку ESC. По умолчанию: `-`
`disabled`	`boolean` Блокирует изменение состояния. По умолчанию: `-`
`disableFlipMiddleware`	`boolean` Указанное значение `placement` форсируется, даже если для выпадающего элемента недостаточно места. Не оказывает влияния при `placement` значениях - `'auto' \| 'auto-start' \| 'auto-end'` По умолчанию: `-`
`disableFocusTrap`	`boolean` Позволяет отключить захват фокуса. По умолчанию: `-`
`disableInteractive`	`boolean` Отключает взаимодействие со всплывающим элементом. По умолчанию: `-`
`disableShiftMiddleware`	`boolean` Позволяет отключить смещение по главной оси, которое не даёт всплывающему элементу выходить за границы видимой области. По умолчанию: `-`
`getRootRef`	`Ref<HTMLDivElement>` По умолчанию: `-`
`hideWhenReferenceHidden`	`boolean` Принудительно скрывает компонент если целевой элемент вышел за область видимости. По умолчанию: `-`
`hoverDelay`	`number \| [number, number]` Количество миллисекунд, после которых произойдёт показ/скрытие всплывающего элемента при наведении. Чтобы задать разное время на показ и скрытие, передайте массив типа `[<показ>, <скрытие>]`. Используется только для `trigger="hover"`. По умолчанию: `-`
`keepMounted`	`boolean` Используется для того, чтобы не удалять всплывающий элемент из DOM дерева при скрытии. По умолчанию: `-`
`noStyling`	`boolean` Отключает у всплывающего элемента стилизацию по умолчанию. У `content`: background border-radius box-shadow. У `arrow`: color. Используется в случае, если необходимо стилизовать по своему. Для `arrow` color можно определить через в `arrowProps.iconClassName` или `arrowProps.iconStyle`. По умолчанию: `-`
`offsetByCrossAxis`	`number` Отступ по вспомогательной оси. По умолчанию: `-`
`offsetByMainAxis`	`number` Отступ по главной оси. По умолчанию: `-`
`onPlacementChange`	`OnPlacementChange` В зависимости от области видимости, позиция может смениться на более оптимальную, чтобы всплывающий элемент вместился в эту область видимости. По умолчанию: `-`
`onReferenceHiddenChange`	`((hidden: boolean) => void)` Событие скрытия / раскрытия компонента при использовании свойства `hideWhenReferenceHidden`. Стоит иметь ввиду, что событие также будет вызвано и при новом рендере компонента По умолчанию: `-`
`onShownChange`	`OnShownChange` Вызывается при каждом изменении видимости всплывающего элемента. По умолчанию: `-`
`onShownChanged`	`OnShownChange` Вызывается при каждом изменении видимости всплывающего элемента, но после завершении анимации. По умолчанию: `-`
`placement`	`PlacementWithAuto` По умолчанию компонент выберет наилучшее расположение сам, но приоритетное можно задать с помощью этого свойства. По умолчанию: `-`
`restoreFocus`	`RestoreFocusType` Нужно ли после закрытия всплывающего элемента возвращать фокус на предыдущий активный элемент. По умолчанию: `-`
`sameWidth`	`boolean` Выставлять ширину равной target элементу. По умолчанию: `-`
`shown`	`boolean` Если передан, то всплывающий элемент будет показано/скрыто в зависимости от значения свойства. По умолчанию: `-`
`strategy`	`Strategy` Стратегия позиционирования всплывающего элемента. `"fixed"` - позиционируется, используя `position: fixed`. Является значением по умолчанию `"absolute"` - позиционируется, используя `position: absolute`, относительно ближайшего элемента с `position: relative` `strategy="absolute"` Рекомендуется использовать с `usePortal={false}`. И нужно не забыть обернуть в элемент с `position: relative` По умолчанию: `-`
`trigger`	`TriggerType` Механика вызова всплывающего элемента. `"click"` – показывается/скрывается только при нажатии. `"hover"` – будет показываться/скрывается при наведении/отведении мыши. `"focus"` – будет показываться/скрывается при фокусе/потере фокуса мыши. `"manual"` – будет показываться/скрывается только через свойство `shown`. `onShownChange` будет вызываться при нажатии за пределы целевого и всплывающего элементов, а также по кнопке ESC. ⚠️`"hover"` на тач-устройствах будет работать как `"click"`, с одним лишь нюансом, что не будет закрываться при повторном нажатии на целевой элемент. Для закрытия необходимо нажать на область вне целевого элемента и выпадающего окна. Избегайте использования `trigger="hover"` как единственного механизма активации, так как пользователи клавиатуры или скринридеров не смогут использовать компонент По умолчанию: `-`
`usePortal`	`boolean \| HTMLElement \| RefObject<HTMLElement>` По умолчанию используется document.body. По умолчанию: `-`
`zIndex`	`string \| number` Перебивает zIndex заданный по умолчанию. По умолчанию: `-`

ModalPageHeader

Popper

Popover

Функциональность

Механизм вызова всплывающего окна

`"click"`

`"hover"`

`"focus"`

`"manual"`

Хук usePopover

Текстовые метки

Свойства и методы