FezVrasta/popper.js

<PageCard>

# Misc

Information, tips, and guidelines to help you use Floating UI.

</PageCard>

## Browser support

The following browsers are supported (defined by `browserslist`):

- Chrome >= 73
- Firefox >= 78
- Edge >= 79
- Safari >= 12.0
- iOS >= 12.0
- Opera >= 53

## Keeping Floating UI up to date

Floating UI uses internal first-party dependencies (under the
`@floating-ui` org) that may be out of date, but contain bug
fixes you may need. You may also be using Floating UI itself as a
transitive package of a different library.

Only certain packages are kept to the latest versions to avoid
bumping dependant packages too frequently and to ensure wider
version support.

To upgrade Floating UI as a transitive package, install the
necessary packages directly, which will update your lockfile,
then uninstall them again so they aren't in your
`package.json#dependencies`.

For all packages, `@floating-ui/core` should be updated manually:

```bash
npm install @floating-ui/core@latest
npm uninstall @floating-ui/core
```

For `@floating-ui/react`, `@floating-ui/react-dom`, or
`@floating-ui/vue`, `@floating-ui/dom` should also be updated
manually:

```bash
npm install @floating-ui/dom@latest
npm uninstall @floating-ui/dom
```

If you're using a different library which wraps Floating UI, you
can also do the same for the relevant package it is depending on.

## Subpixel and accelerated positioning

Instead of `top{:.key}` and `left{:.key}` as shown throughout the
docs, you can use transform styles instead to position the
floating element for increased performance.

```js
function roundByDPR(value) {
  const dpr = window.devicePixelRatio || 1;
  return Math.round(value * dpr) / dpr;
}

Object.assign(floatingEl.style, {
  top: '0',
  left: '0',
  transform: `translate(${roundByDPR(x)}px,${roundByDPR(y)}px)`,
});
```

`x` and `y` can contain fractional numbers (decimal), so there
will be blurring unless we place it evenly on the device's pixel
grid. The rounding method above ensures the floating element is
positioned optimally for the screen.

### 3D transforms

You can also promote the floating element to its own layer:

{/* prettier-ignore */}
```js
Object.assign(floatingEl.style, {
  top: '0',
  left: '0',
  transform: `translate3d(${roundByDPR(x)}px,${roundByDPR(y)}px,0)`,
});
```

If you're animating the location of the floating element, using
`transform{:.key}` will offer smoother animations.

<Notice type="warning">
  3D transforms can sometimes result in blurry text on some
  Windows devices with scaling. You may only want to use 3D
  transforms on high PPI displays, and 2D transforms on low PPI
  displays.
</Notice>

## z-index stacking

Floating UI does not have opinions about how your elements stack
on the z-axis. This means your element may be occluded beneath
another positioned element if it has a higher `z-index`.

Due to the complexity of this, it is up to you to handle the z
indices of various floating elements in your application.

In the future, Floating UI may
[enable you to specify elements to avoid](https://github.com/floating-ui/floating-ui/issues/1440),
so multiple floating elements can avoid colliding with each other
intelligently without worrying about their `z-index`.

## Clipping

Your floating element may get clipped by an ancestor if it has
`position: relative{:sass}` and `overflow: hidden{:sass}` CSS
styles, and small enough that the floating element cannot be
positioned in view properly.

Two solutions include:

- **Portalling**: The floating element can be appended to a
  container outside of the clipping ancestor.
- **Use fixed strategy**: Using the `'fixed'{:js}` strategy will
  "break" the floating element out of its parent clipping context
  in the majority of cases. This allows you to keep the floating
  element's DOM context in tact. This is not 100% guaranteed
  though — portalling is the only 100% reliable method.

## Handling large content

When your floating element's width exceeds the viewport's, it can
result in unexpected behavior.

You can limit the width of the floating element using the
following CSS:

```css
.floating {
  max-width: calc(100vw - 10px);
}
```

This will always make it 10 pixels less than the width of the
viewport.

The constant `10{:js}` shown in the example should be double the
`padding{:.key}` given to the `shift(){:js}` middleware if it's
in use.

Alternatively, you may experiment with the [`size`](/docs/size)
middleware depending on the axis overflow is occurring.

## Relative units

Floating UI works entirely with pixel units as it is a JavaScript
library that works with `getBoundingClientRect(){:js}` and other
measurement properties that return pixels. Further, it is
cross-platform, and pixels are the most commonly supported unit.

If your CSS uses relative units like `rem`, it is recommended you
convert the values into pixels before passing them to Floating
UI.

```js
computePosition(reference, floating, {
  // 1rem => 16px
  middleware: [offset(remToPx(1))],
});
```