﻿---
description: Низкоуровневый компонент для отрисовки выпадающего блока.
tags: overlay
---

# Popper \[tag:component]

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

```jsx
const buttonRef = React.useRef(null);

return (
  <React.Fragment>
    <Button getRootRef={buttonRef}>
      Закрыть
    </Button>
    <Popper usePortal={false} targetRef={buttonRef} disableFlipMiddleware>
      Привет
    </Popper>
  </React.Fragment>
);
```

```jsx
const [shown, setShown] = React.useState(false);
const buttonRef = React.useRef(null);

return (
  <React.Fragment>
    <Button getRootRef={buttonRef} onClick={() => setShown(!shown)}>
      {shown ? 'Закрыть' : 'Открыть'}
    </Button>
    {shown && (
      <Popper usePortal={false} targetRef={buttonRef}>
        Привет
      </Popper>
    )}
  </React.Fragment>
);
```

## Виртуальный элемент

Помимо ссылки на DOM элемент, `Popper` можем принимать координаты виртуального элемента.
Виртуальный элемент представляет из себя объект со свойством `getBoundingClientRect()`.

> Чтобы не задавать все свойства координат вручную,
> можно использовать [DOMRect.fromRect](https://developer.mozilla.org/en-US/docs/Web/API/DOMRect/fromRect_static)

```jsx
const [virtualElement, setVirtualElement] = React.useState(() =>
  DOMRect.fromRect({
    x: -200,
    y: -200,
    width: 10,
    height: 10,
  }),
);

const handleClick = (event) => {
  setVirtualElement(({ width, height }) =>
    DOMRect.fromRect({
      x: event.clientX,
      y: event.clientY,
      width,
      height,
    }),
  );
};

return (
  <>
    <Box padding="system" onClick={handleClick}>Нажми в любое место этого текста</Box>
    <Popper
      arrow
      arrowProps={{ iconStyle: { color: 'green' } }}
      placement="bottom"
      usePortal={false}
      style={{ padding: '9px 12px', backgroundColor: 'green', color: '#fff' }}
      targetRef={{
        getBoundingClientRect() {
          return virtualElement;
        },
      }}
    >
      Привет
    </Popper>
  </>
);
```

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

| Свойство      | Тип                                           | По умолчанию                                                         | Описание                                                                                 |
| ------------- | --------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `arrow`       | `boolean`                                     | `-`                                                                  | Отображать ли стрелку, указывающую на якорный элемент.                                   |
| `arrowHeight` | `number`                                      | `8`                                                                  | Высота стрелки. Складывается с `mainAxis`, чтобы стрелка не залезала на якорный элемент. |
| `ArrowIcon`   | `ComponentType<SVGAttributes<SVGSVGElement>>` | \`(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>
```

);
}`| Пользовательская 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"`. | | `arrowPadding`|`number`|`10`| Безопасная зона вокруг стрелки, чтобы та не выходила за края контента. |
|`arrowProps`|`FloatingArrowProps`|`-`| Позволяет набросить на стрелку пользовательские атрибуты. |
|`arrowRef`|`Element | MutableRefObject\<Element | null> | null`|`-`|  |
|`autoUpdateOnAnimationFrame`|`boolean`|`false`| Пытаться обновлять позицию всплывающего элемента каждый фрейм. |
|`autoUpdateOnTargetResize`|`boolean`|`false`| Подписывается на изменение геометрии`targetRef`, чтобы пересчитать свою позицию. | | `customMiddlewares`|`\{ name: string; options?: any; fn: (state: \{ x: number; y: number; placement: Placement; platform: \{ detectOverflow: (state: MiddlewareState, options?: DetectOverflowOptions | Derivable\<...>) => Promise\<...>; } & Platform; ... 4 more ...; elements: Elements; }) => Promisable\<...>; }\[] | undefined`|`-`| Позволяет задать или переопределить модификаторы библиотеки **Floating UI** (подробнее в документации про [middleware](https://floating-ui.com/docs/middleware)). |
|`defaultShown`|`boolean`|`-`| Начальное состояние всплывающего элемента. |
|`disableFlipMiddleware`|`boolean`|`false`| Указанное значение`placement`форсируется, даже если для выпадающего элемента недостаточно места. Не оказывает влияния при`placement`значениях -`'auto' | 'auto-start' | 'auto-end'`|
|`disableShiftMiddleware`|`boolean`|`false`| Позволяет отключить смещение по главной оси, которое не даёт всплывающему элементу выходить за границы видимой области. |
|`flipMiddlewareFallbackAxisSideDirection`|`"start" | "none" | "end"`|`-`| Задаёт резервный вариант размещения по перпендикулярной оси. |
|`getRootRef`|`Ref<HTMLDivElement>`|`-`|  |
|`hideWhenReferenceHidden`|`boolean`|`-`| Принудительно скрывает компонент если целевой элемент вышел за область видимости. |
|`hoverDelay`|`number | \[number, number]`|`-`| Количество миллисекунд, после которых произойдёт показ/скрытие всплывающего элемента при наведении.  > Чтобы задать разное время на показ и скрытие, передайте массив типа`\[\<показ>, \<скрытие>]`.  > Используется только для `trigger="hover"`. | | `offsetByCrossAxis`|`number`|`0`| Отступ по вспомогательной оси. |
|`offsetByMainAxis`|`number`|`8`| Отступ по главной оси. |
|`onPlacementChange`|`OnPlacementChange`|`-`| В зависимости от области видимости, позиция может смениться на более оптимальную, чтобы всплывающий элемент вместился в эту область видимости. |
|`onReferenceHiddenChange`|`((hidden: boolean) => void)`|`-`| Событие скрытия / раскрытия компонента при использовании свойства`hideWhenReferenceHidden`.  > Стоит иметь ввиду, что событие также будет вызвано и при новом рендере компонента | | `onShownChange`|`OnShownChange`|`-`| Вызывается при каждом изменении видимости всплывающего элемента. |
|`overflowPadding`|`Padding`|`-`| Отступ для смещения. |
|`placement`|`PlacementWithAuto`|`bottom-start`| По умолчанию компонент выберет наилучшее расположение сам, но приоритетное можно задать с помощью этого свойства. |
|`ref`|`Ref<HTMLDivElement>`|`-`|  |
|`sameWidth`|`boolean`|`-`| Выставлять ширину равной target элементу. |
|`shown`|`boolean`|`-`| Если передан, то всплывающий элемент будет показано/скрыто в зависимости от значения свойства. |
|`strategy`|`Strategy`|`-`| Стратегия позиционирования всплывающего элемента.  -`"fixed"`- позиционируется, используя`position: fixed`. Является значением по умолчанию - `"absolute"`- позиционируется, используя`position: absolute`, относительно ближайшего элемента с `position: relative` >`strategy="absolute"`Рекомендуется использовать с`usePortal=\{false}`. И нужно не забыть обернуть в элемент с `position: relative`|
|`**targetRef** \*`|`RefObject\<HTMLElement | null> | VirtualElement`|`-`| Ref на якорный элемент. |
|`usePortal`|`boolean | HTMLElement | RefObject\<HTMLElement | null>`|`true`| По умолчанию используется document.body. |
|`zIndex`|`string | number`|`-\` | Перебивает zIndex заданный по умолчанию. |
