Исходник ↗Песочница ↗

Popover

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

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

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

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

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

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

"click"

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

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

"hover"

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

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

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

"focus"

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

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

"manual"

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

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

Хук usePopover

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

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

Доступность (a11y)

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

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

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

trigger="hover"

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

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

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

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

Popover

СвойствоОписание
arrowboolean

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

По умолчанию: -
arrowHeightnumber

Высота стрелки. Складывается с mainAxis, чтобы стрелка не залезала на якорный элемент.

По умолчанию: -
ArrowIconComponentType<SVGAttributes<SVGSVGElement>>

Пользовательская SVG иконка.

Требования:

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

Безопасная зона вокруг стрелки, чтобы та не выходила за края контента.

По умолчанию: -
arrowPropsPopoverArrowProps

Позволяет набросить на стрелку пользовательские атрибуты.

По умолчанию: -
autoFocusboolean | "root"

Управление автоматическим фокусом при открытии всплывающего элемента.

По умолчанию: -
childrenReactElement<unknown, string | JSXElementConstructor<any>>

Целевой элемент. Всплывающее окно появится возле него.

По умолчанию: -
closeAfterClickboolean

При trigger="hover" закрывает всплывающий элемент при нажатии на целевой элемент.

По умолчанию: -
contentReactNode | 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 (необходимо мемоизировать).

По умолчанию: -
defaultShownboolean

Начальное состояние всплывающего элемента.

По умолчанию: -
disableCloseOnClickOutsideboolean

Отключает закрытие нажатием на область вне целевого и всплывающего элемента.

По умолчанию: -
disableCloseOnEscKeyboolean

Отключает закрытие нажатием на кнопку ESC.

По умолчанию: -
disabledboolean

Блокирует изменение состояния.

По умолчанию: -
disableFlipMiddlewareboolean

Указанное значение placement форсируется, даже если для выпадающего элемента недостаточно места. Не оказывает влияния при placement значениях - 'auto' | 'auto-start' | 'auto-end'

По умолчанию: -
disableFocusTrapboolean

Позволяет отключить захват фокуса.

По умолчанию: -
disableInteractiveboolean

Отключает взаимодействие со всплывающим элементом.

По умолчанию: -
disableShiftMiddlewareboolean

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

По умолчанию: -
getRootRefRef<HTMLDivElement>
По умолчанию: -
hideWhenReferenceHiddenboolean

Принудительно скрывает компонент если целевой элемент вышел за область видимости.

По умолчанию: -
hoverDelaynumber | [number, number]

Количество миллисекунд, после которых произойдёт показ/скрытие всплывающего элемента при наведении.

По умолчанию: -
keepMountedboolean

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

По умолчанию: -
noStylingboolean

Отключает у всплывающего элемента стилизацию по умолчанию.

У content:

  • background
  • border-radius
  • box-shadow.

У arrow:

  • color.

Используется в случае, если необходимо стилизовать по своему. Для arrow color можно определить через в arrowProps.iconClassName или arrowProps.iconStyle.

По умолчанию: -
offsetByCrossAxisnumber

Отступ по вспомогательной оси.

По умолчанию: -
offsetByMainAxisnumber

Отступ по главной оси.

По умолчанию: -
onPlacementChangeOnPlacementChange

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

По умолчанию: -
onReferenceHiddenChange((hidden: boolean) => void)

Событие скрытия / раскрытия компонента при использовании свойства hideWhenReferenceHidden.

По умолчанию: -
onShownChangeOnShownChange

Вызывается при каждом изменении видимости всплывающего элемента.

По умолчанию: -
onShownChangedOnShownChange

Вызывается при каждом изменении видимости всплывающего элемента, но после завершении анимации.

По умолчанию: -
placementPlacementWithAuto

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

По умолчанию: -
restoreFocusRestoreFocusType

Нужно ли после закрытия всплывающего элемента возвращать фокус на предыдущий активный элемент.

По умолчанию: -
sameWidthboolean

Выставлять ширину равной target элементу.

По умолчанию: -
shownboolean

Если передан, то всплывающий элемент будет показано/скрыто в зависимости от значения свойства.

По умолчанию: -
strategyStrategy

Стратегия позиционирования всплывающего элемента.

  • "fixed" - позиционируется, используя position: fixed. Является значением по умолчанию
  • "absolute" - позиционируется, используя position: absolute, относительно ближайшего элемента с position: relative
По умолчанию: -
triggerTriggerType

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

  • "click" – показывается/скрывается только при нажатии.
  • "hover" – будет показываться/скрывается при наведении/отведении мыши.
  • "focus" – будет показываться/скрывается при фокусе/потере фокуса мыши.
  • "manual" – будет показываться/скрывается только через свойство shown. onShownChange будет вызываться при нажатии за пределы целевого и всплывающего элементов, а также по кнопке ESC.

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

По умолчанию: -
usePortalboolean | HTMLElement | RefObject<HTMLElement>

По умолчанию используется document.body.

По умолчанию: -
zIndexstring | number

Перебивает zIndex заданный по умолчанию.

По умолчанию: -

usePopover

СвойствоОписание
arrowboolean

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

По умолчанию: -
arrowHeightnumber

Высота стрелки. Складывается с mainAxis, чтобы стрелка не залезала на якорный элемент.

По умолчанию: 8
ArrowIconComponentType<SVGAttributes<SVGSVGElement>>

Пользовательская SVG иконка.

Требования:

  1. Иконка по умолчанию должна быть направлена вверх (a.k.a IconUp).
  2. Чтобы избежать проблемы с пространством между стрелкой и контентом на некоторых экранах, растяните кривую по высоте на 1px и увеличьте на этот размер height и viewBox SVG. (смотри https://github.com/VKCOM/VKUI/pull/4496 ↗).
  3. Передайте высоту иконки в параметр arrowHeight. В значении высоты можно исключить хак с 1px из п.2.
  4. Убедитесь, что компонент принимает все валидные для SVG параметры.
  5. Убедитесь, что SVG и её элементы наследует цвет через fill="currentColor".
По умолчанию: (props: React.SVGAttributes<SVGSVGElement>): React.ReactNode => { return ( <svg width={DEFAULT_ARROW_WIDTH} height={ARROW_HEIGHT_WITH_WHITE_SPACE} viewBox={`0 0 ${DEFAULT_ARROW_WIDTH} ${ARROW_HEIGHT_WITH_WHITE_SPACE}`} xmlns="http://www.w3.org/2000/svg" {...props} > <path d="M10 0c3 0 6 8 10 8v1H0V8c3.975 0 7-8 10-8Z" fill="currentColor" /> </svg> ); }
arrowPaddingnumber

Безопасная зона вокруг стрелки, чтобы та не выходила за края контента.

По умолчанию: 10
arrowPropsPopoverArrowProps

Позволяет набросить на стрелку пользовательские атрибуты.

По умолчанию: -
autoFocusboolean | "root"

Управление автоматическим фокусом при открытии всплывающего элемента.

По умолчанию: true
closeAfterClickboolean

При trigger="hover" закрывает всплывающий элемент при нажатии на целевой элемент.

По умолчанию: -
contentReactNode | 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 (необходимо мемоизировать).

По умолчанию: -
defaultShownboolean

Начальное состояние всплывающего элемента.

По умолчанию: false
disableCloseOnClickOutsideboolean

Отключает закрытие нажатием на область вне целевого и всплывающего элемента.

По умолчанию: -
disableCloseOnEscKeyboolean

Отключает закрытие нажатием на кнопку ESC.

По умолчанию: -
disabledboolean

Блокирует изменение состояния.

По умолчанию: -
disableFlipMiddlewareboolean

Указанное значение placement форсируется, даже если для выпадающего элемента недостаточно места. Не оказывает влияния при placement значениях - 'auto' | 'auto-start' | 'auto-end'

По умолчанию: false
disableFocusTrapboolean

Позволяет отключить захват фокуса.

По умолчанию: -
disableInteractiveboolean

Отключает взаимодействие со всплывающим элементом.

По умолчанию: -
disableShiftMiddlewareboolean

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

По умолчанию: false
getRootRefRef<HTMLDivElement>
По умолчанию: -
hideWhenReferenceHiddenboolean

Принудительно скрывает компонент если целевой элемент вышел за область видимости.

По умолчанию: -
hoverDelaynumber | [number, number]

Количество миллисекунд, после которых произойдёт показ/скрытие всплывающего элемента при наведении.

По умолчанию: 150
keepMountedboolean

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

По умолчанию: false
noStylingboolean

Отключает у всплывающего элемента стилизацию по умолчанию.

У content:

  • background
  • border-radius
  • box-shadow.

У arrow:

  • color.

Используется в случае, если необходимо стилизовать по своему. Для arrow color можно определить через в arrowProps.iconClassName или arrowProps.iconStyle.

По умолчанию: false
offsetByCrossAxisnumber

Отступ по вспомогательной оси.

По умолчанию: 0
offsetByMainAxisnumber

Отступ по главной оси.

По умолчанию: 8
onPlacementChangeOnPlacementChange

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

По умолчанию: -
onReferenceHiddenChange((hidden: boolean) => void)

Событие скрытия / раскрытия компонента при использовании свойства hideWhenReferenceHidden.

По умолчанию: -
onShownChangeOnShownChange

Вызывается при каждом изменении видимости всплывающего элемента.

По умолчанию: -
onShownChangedOnShownChange

Вызывается при каждом изменении видимости всплывающего элемента, но после завершении анимации.

По умолчанию: -
placementPlacementWithAuto

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

По умолчанию: bottom-start
restoreFocusRestoreFocusType

Нужно ли после закрытия всплывающего элемента возвращать фокус на предыдущий активный элемент.

По умолчанию: true
sameWidthboolean

Выставлять ширину равной target элементу.

По умолчанию: -
shownboolean

Если передан, то всплывающий элемент будет показано/скрыто в зависимости от значения свойства.

По умолчанию: -
strategyStrategy

Стратегия позиционирования всплывающего элемента.

  • "fixed" - позиционируется, используя position: fixed. Является значением по умолчанию
  • "absolute" - позиционируется, используя position: absolute, относительно ближайшего элемента с position: relative
По умолчанию: -
triggerTriggerType

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

  • "click" – показывается/скрывается только при нажатии.
  • "hover" – будет показываться/скрывается при наведении/отведении мыши.
  • "focus" – будет показываться/скрывается при фокусе/потере фокуса мыши.
  • "manual" – будет показываться/скрывается только через свойство shown. onShownChange будет вызываться при нажатии за пределы целевого и всплывающего элементов, а также по кнопке ESC.

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

По умолчанию: click
usePortalboolean | HTMLElement | RefObject<HTMLElement>

По умолчанию используется document.body.

По умолчанию: true
zIndexstring | number

Перебивает zIndex заданный по умолчанию.

По умолчанию: var(--vkui--z_index_popout)
Предыдущая
ModalPageHeader
Следующая
Popper