# @chakra-ui/popper

> A React component and hooks wrapper for popper.js

Latest version **3.1.0** (published 2023-07-18) · MIT license · 0 weekly downloads

## Install

```sh
npm install @chakra-ui/popper
pnpm add @chakra-ui/popper
yarn add @chakra-ui/popper
bun add @chakra-ui/popper
```

## Health

**Score 45/100 (D)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high maintenance score; popular repo.

Warnings: low downloads.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 3.1.0 |
| Published | 2023-07-18 |
| First published | 2020-06-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 140.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 40661 |
| Author | Segun Adebayo |
| Maintainers | segunadebayo, _codebender828 |
| Keywords | react, popper, popover, tooltips, popper.js, positioning, popperjs-modifier, ui, chakra ui, component |

## Links

- npm: https://www.npmjs.com/package/@chakra-ui/popper
- Repository: https://github.com/chakra-ui/chakra-ui
- Homepage: https://github.com/chakra-ui/chakra-ui#readme
- Issues: https://github.com/chakra-ui/chakra-ui/issues
- npm.io page: https://npm.io/package/@chakra-ui/popper

## Dependencies (3)

- [@popperjs/core](https://npm.io/package/@popperjs/core.md) ^2.9.3
- [@chakra-ui/react-types](https://npm.io/package/@chakra-ui/react-types.md) 2.0.7
- [@chakra-ui/react-use-merge-refs](https://npm.io/package/@chakra-ui/react-use-merge-refs.md) 2.1.0

## Alternatives

- [@progress/kendo-ooxml](https://npm.io/package/@progress/kendo-ooxml.md) — 152.1K weekly downloads
- [@progress/kendo-react-ripple](https://npm.io/package/@progress/kendo-react-ripple.md) — 8.0K weekly downloads
- [@progress/kendo-react-orgchart](https://npm.io/package/@progress/kendo-react-orgchart.md) — 4.3K weekly downloads
- [@praxisui/dynamic-fields](https://npm.io/package/@praxisui/dynamic-fields.md) — 2.4K weekly downloads
- [@mesalvo/react-ui](https://npm.io/package/@mesalvo/react-ui.md) — 1.7K weekly downloads

## Recent versions

- 3.1.0 (latest) — 2023-07-18
- 0.0.0-dev-20230718132637 (dev) — 2023-07-18
- 3.0.0-next.3 (next) — 2022-05-09
- 0.0.0-pr-202215132532 (pr) — 2022-02-05
- 1.0.0-next.0 (canary) — 2020-06-20
- 0.0.0-dev-20230718130742 — 2023-07-18
- 0.0.0-dev-20230718124717 — 2023-07-18
- 0.0.0-dev-20230718122336 — 2023-07-18
- 3.0.14 — 2023-05-03
- 0.0.0-dev-20230502211538 — 2023-05-02
- 0.0.0-dev-20230502164338 — 2023-05-02
- 3.0.13 — 2023-01-16
- 0.0.0-dev-20230116124502 — 2023-01-16
- 0.0.0-dev-20230116122157 — 2023-01-16
- 0.0.0-dev-20230116120206 — 2023-01-16
- … 145 more at https://npm.io/package/@chakra-ui/popper/versions

## README

# Popper

A React hooks wrapper for popper.js to dynamic positioning of containers around
a reference.

> This is an internal hook of Chakra-UI, and it's not covered by semver, and may
> cause unexpected or broken application behavior. Use them at your own risk.

## Installation

```sh
yarn add @chakra-ui/popper
```

## Basic usage

By default, the `usePopper` hook returns props for the popper, reference and
arrow.

```jsx
import { Box } from "@chakra-ui/layout"
import { Button } from "@chakra-ui/button"
import { useDisclosure } from "@chakra-ui/hooks"
import { usePopper } from "@chakra-ui/popper"

function Example() {
  const { isOpen, onToggle } = useDisclosure()
  const { popperRef, referenceRef, getArrowProps } = usePopper()
  return (
    <>
      <Button ref={referenceRef} onClick={onToggle} mb={2}>
        {isOpen ? "Click me to see less" : "Click me to see more"}
      </Button>
      {isOpen && (
        <Box ref={popperRef} bg="red">
          <div
            {...getArrowProps({
              style: {
                background: "red",
              },
            })}
          />
          This is a popover for the button!
        </Box>
      )}
    </>
  )
}
```

## Parameters

### Changing the placement

You can change the placement of the popper by passing the `placement` option to
`usePopper` and set it to the `popper.js` placement.

```jsx
const { popperRef, referenceRef } = usePopper({
  placement: "right-start",
})
```

### Match reference's width

In some cases, you might want to allow the popper take the width of the
reference. For example, autocomplete, select, etc.

To achieve this, pass the `matchWidth` option and set it to `true`

```jsx
const { popperRef, referenceRef } = usePopper({
  matchWidth: true,
})
```

### Place the popper next to the reference

You can place the popper next to the reference without margin or distance
between them. Useful to create an autocomplete or typeahead feature.

```jsx
const { popperRef, referenceRef } = usePopper({
  gutter: 0,
})
```

### Using inside a fixed container

If the reference element is inside a fixed container, you should use the `fixed`
strategy.

```jsx
const { popperRef, referenceRef } = usePopper({
  strategy: "fixed",
})
```

## Adding transition

When add transitions to a popper component, it is usually advised to apply
popper and transition to different elements.

```tsx
// 1. Import components
import { useDisclosure } from "@chakra-ui/hooks"
import { usePopper } from "@chakra-ui/popper"
import { motion, AnimatePresence, Variants } from "framer-motion"

export function Example() {
  // 2. Create toggle state
  const { isOpen, onToggle } = useDisclosure()

  // 3. Create motion variants
  const slide: Variants = {
    exit: {
      y: -2,
      opacity: 0,
    },
    enter: {
      y: 0,
      opacity: 1,
    },
  }

  // 4. Consume the `usePopper` hook
  const { getPopperProps, getReferenceProps, getArrowProps, transformOrigin } =
    usePopper({
      placement: "bottom-start",
    })

  return (
    <>
      <button {...getReferenceProps({ onClick: onToggle })}>Toggle</button>
      <div {...getPopperProps()}>
        <AnimatePresence>
          {isOpen && (
            <motion.div
              transition={{
                type: "spring",
                duration: 0.2,
              }}
              variants={slide}
              initial="exit"
              animate="enter"
              exit="exit"
              style={{
                background: "red",
                width: 200,
                transformOrigin,
                borderRadius: 4,
              }}
            >
              Testing
              <div
                {...getArrowProps({
                  style: {
                    background: "red",
                  },
                })}
              />
            </motion.div>
          )}
        </AnimatePresence>
      </div>
    </>
  )
}
```

> When not rendering the popper conditionally, we recommend using
> `visibility: hidden` instead of `hidden` or `display: none`

---
_Source: https://npm.io/package/@chakra-ui/popper · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._