@cloud-ru/ds-popover-private

中文文档

1.1.4发布于 2026/11/11Apache-2.0TypeScriptESM + CJS近 30 天下载 2万

Низкоуровневый popover на @floating-ui — позиционирование, стрелка, триггеры. Используется как фундамент для Tooltip, Popover, Dropdown.

文档目录6 节

Когда использовать
Установка
Props
PopoverPrivate
Arrow
Смотри также

PopoverPrivate

@cloud-ru/ds-popover-private — Низкоуровневый popover на @floating-ui — позиционирование, стрелка, триггеры. Используется как фундамент для Tooltip, Popover, Dropdown.

@cloud-ru/ds-popover-private — внутренний строительный блок: бесстилевая обёртка над @floating-ui/react с поддержкой placement, offset, авто-flip, стрелки и нескольких триггеров (click, hover, focus, controlled open). Поверх него собраны публичные @cloud-ru/ds-tooltip, @cloud-ru/ds-popover, @cloud-ru/ds-dropdown. В продуктовом коде используйте их.

Когда использовать

Реализация нового публичного компонента, которому нужно всплывающее окно (например, контекстное меню новой формы).
Очень специфический сценарий, который не покрыт Tooltip/Popover/Dropdown.

В обычной разработке — берите публичный компонент.

Установка

pnpm add @cloud-ru/ds-popover-private

import { PopoverPrivate, Arrow } from '@cloud-ru/ds-popover-private'

Props

PopoverPrivate

PopoverPrivateProps

Prop	Type	Default	Description
`arrowContainerClassName`	`string`	—	CSS-класс контейнера стрелки поповера
`arrowElementClassName`	`string`	—	CSS-класс стрелки поповера
`children`	`ChildrenFunction`	—	Триггер поповера (подробнее читайте ниже)
`className`	`string`	—
`closeOnEscapeKey`	`boolean`	`true`	Закрывать ли по нажатию на кнопку `Esc`
`closeOnPopstate`	`boolean`	—	Закрывать ли поповер при переходе по истории браузера
`container`	`RefObject<HTMLElement \| null>`	—	Контейнер портала (ref). Переопределяет `PortalContext` для этого инстанса — по аналогии с `container` у Modal/Drawer. По умолчанию берётся из `PortalContextProvider`.
`data-test-id`	`string`	—
`disableSpanWrapper`	`boolean`	—	Отключает для `isValidElement` внешнюю обертку триггера Пригодится для элементов с `position: absolute` Работает для триггеров, которые умеют отдать свою DOM-ноду: нативные элементы, `forwardRef`-компоненты и компоненты, помеченные `withInnerRefSupport` из `@cloud-ru/ds-utils`. Остальные всё равно получают `<span>` — без ноды поповеру не от чего считать позицию; в dev-режиме об этом печатается предупреждение.
`escapeKeyBubbles`	`boolean`	`false`	Пропускать ли `Esc` дальше после закрытия поповера. Без этого открытый поповер гасит всплытие `Esc`, и внешний поповер (например, дроплист, чей триггер несёт тултип) не закроется.
`fallbackPlacements`	`Placement`	—	Цепочка расположений которая будет применяться к поповеру от первого к последнему если при текущем он не влезает.
`hasArrow`	`boolean`	—	Параметр наличия стрелки у поповера. В размеры стрелки встроен отступ. Дополнительный отступ может быть задан параметром `offset`. У элемента стрелки нет цвета, необходимо задавать его через параметр `arrowClassName`.
`heightStrategy`	`"auto"` \| `"eq"` \| `"lte"`	`auto`	Стратегия управления высотой контейнера поповера - `auto` - соответствует высоте контента, - `lte` - Less Than or Equal, равен высоте таргета или меньше ее, если контент в поповере меньше, - `eq` - Equal, строго равен высоте таргета.
`hoverDelayClose`	`number`	—	Задержка закрытия по ховеру
`hoverDelayOpen`	`number`	—	Задержка открытия по ховеру
`offset`	`number`	`0`	Отступ поповера от его триггер-элемента (в пикселях).
`onOpenChange`	`((isOpen: boolean) => void)`	—	Колбек отображения компонента. Срабатывает при изменении состояния open.
`open`	`boolean`	—	Управляет состоянием показан/не показан.
`outsideClick`	`OutsideClickHandler`	—	Закрывать ли при клике вне поповера
`placement`	`"bottom"` \| `"bottom-end"` \| `"bottom-start"` \| `"left"` \| `"left-end"` \| `"left-start"` \| `"right"` \| `"right-end"` \| `"right-start"` \| `"top"` \| `"top-end"` \| `"top-start"`	`top`	Положение поповера относительно своего триггера (children).
`popoverContent`	`ReactNode \| ReactNode[]`	—	Контент поповера
`stopPropagation`	`StopPropagationHandlers`	`{ onClick: true, onMouseDown: true, onMouseUp: true, onTouchStart: true, onTouchEnd: true, onTouchMove: true }`	Гасить всплытие pointer/touch-событий с floating-контейнера (`stopPropagation`). По умолчанию все хендлеры включены. Для drag&drop внутри поповера отключите `onMouseUp` / `onTouchEnd`, чтобы они дошли до `document`.
`trigger`	`"click"` \| `"clickAndFocusVisible"` \| `"focus"` \| `"focusVisible"` \| `"hover"` \| `"hoverAndFocus"` \| `"hoverAndFocusVisible"`	—	Условие отображения поповера: - `click` - открывать по клику - `hover` - открывать по ховеру - `focusVisible` - открывать по focus-visible - `focus` - открывать по фокусу - `hoverAndFocusVisible` - открывать по ховеру и focus-visible - `hoverAndFocus` - открывать по ховеру и фокусу - `clickAndFocusVisible` - открывать по клику и focus-visible
`triggerClassName`	`string`	—	CSS-класс триггера
`triggerClickByKeys`	`boolean`	`true`	Вызывается ли попоповер по нажатию клавиш Enter/Space (при trigger = `click`)
`triggerRef`	`ForwardedRef<HTMLElement \| ReferenceType \| null>`	—	Ref ссылка на триггер
`widthStrategy`	`"auto"` \| `"eq"` \| `"gte"`	`auto`	Стратегия управления шириной контейнера поповера - `auto` - соответствует ширине контента, - `gte` - Great Than or Equal, равен ширине таргета или больше ее, если контент в поповере шире, - `eq` - Equal, строго равен ширине таргета.

ChildrenFunction = (params: { getReferenceProps: GetReferencePropsFunc; ref: (node: ReferenceType | null) => void; }) => ReactNode
OutsideClickHandler = (event: MouseEvent) => boolean
Placement = "bottom" | "bottom-end" | "bottom-start" | "left" | "left-end" | "left-start" | "right" | "right-end" | "right-start" | "top" | "top-end" | "top-start"
PopoverHeightStrategy = "auto" | "eq" | "lte"
PopoverWidthStrategy = "auto" | "eq" | "gte"

StopPropagationHandlers

Prop	Type	Default
`onClick`	`boolean \| undefined`	—
`onMouseDown`	`boolean \| undefined`	—
`onMouseUp`	`boolean \| undefined`	—
`onTouchEnd`	`boolean \| undefined`	—
`onTouchMove`	`boolean \| undefined`	—
`onTouchStart`	`boolean \| undefined`	—

Trigger = "click" | "clickAndFocusVisible" | "focus" | "focusVisible" | "hover" | "hoverAndFocus" | "hoverAndFocusVisible"

Arrow

Prop	Type	Default
`arrowContainerClassName`	`string`	—
`arrowElementClassName`	`string`	—
`arrowRef`	`RefObject<HTMLDivElement \| null>`	—
`placement`	`"bottom"` \| `"bottom-end"` \| `"bottom-start"` \| `"left"` \| `"left-end"` \| `"left-start"` \| `"right"` \| `"right-end"` \| `"right-start"` \| `"top"` \| `"top-end"` \| `"top-start"`	—
`x`	`number`	—
`y`	`number`	—

Смотри также

Tooltip, Popover, Dropdown — публичные потребители.

版本与发布记录

@cloud-ru/ds-popover-private 共发布 30 个版本，首次发布于 2026/08/18；过去 12 个月发布了 30 个版本。

版本	发布日期	距今
`1.1.4`latest	2026/11/11	今天
`1.1.4-preview-e8fe6b56.0`preview	2026/11/11	今天
`1.1.4-preview-c0e895ed.0`	2026/11/11	今天
`1.1.4-preview-90b10112.0`	2026/11/11	今天
`1.1.4-preview-fd7dd437.0`	2026/11/10	1 天前
`1.1.4-preview-9a75a2a9.0`	2026/11/10	1 天前

关于 @cloud-ru/ds-popover-private 的常见问题