import inline from '../../assets/react.inline.jpg';

# React

This package provides React bindings for `@floating-ui/dom`, a
library that provides anchor positioning, and also interaction
primitives to build floating UI components.

<CircleImage name="react" inline={inline} />

With this package, you can create components such as tooltips,
popovers, dropdown menus, hover cards, modal dialogs, select
menus, comboboxes, and more.

## Goals

- **Provide building blocks**: pre-built floating components
  aren't exported, rather the primitives necessary to create
  different types of them. Think of it like a LEGO toolkit.
- **Flexible and low-level**: at the cost of more code to setup,
  you get high control and flexibility to create custom
  components that can suite a wide range of product needs.
- **Accessibility is prioritized**: first-class support is
  provided for creating accessible floating elements that work
  with assistive technology (keyboard usage and screen readers).

## Install

```bash
npm install @floating-ui/react
```

<Notice>

If you only need positioning, the following package is smaller in
size (the above one uses it as a dependency). This is useful if
you are controlling interactions yourself (e.g. a library).

```bash
npm install @floating-ui/react-dom
```

</Notice>

## Usage

There are two main parts to creating floating elements:

- [Positioning](/docs/react#positioning) — available for both
  packages
- [Interactions](/docs/react#interactions) — available for
  `@floating-ui/react{:.string}`

## Positioning

`useFloating(){:js}` is the main hook of each package.

```js
import {useFloating} from '@floating-ui/react';

function App() {
  const {refs, floatingStyles} = useFloating();

  return (
    <>
      <button ref={refs.setReference}>Button</button>
      <div ref={refs.setFloating} style={floatingStyles}>
        Tooltip
      </div>
    </>
  );
}
```

This will position the floating `Tooltip` element at the **bottom
center** of the `Button` element by default.

- `refs.setReference{:js}` is the reference (or anchor) element
  that is being referred to for positioning.
- `refs.setFloating{:js}` is the floating element that is being
  positioned relative to the reference element.
- `floatingStyles{:js}` is an object of positioning styles to
  apply to the floating element's `style{:.keyword}` prop.

The refs are functions to make them **reactive** — this ensures
changes to the reference or floating elements, such as with
conditional rendering, are handled correctly by updating the
position.

## Anchoring

To ensure the floating element remains anchored to the reference
element, such as when scrolling or resizing, pass
[`autoUpdate`](/docs/autoUpdate) to the
`whileElementsMounted{:.objectKey}` option:

```js
import {useFloating, autoUpdate} from '@floating-ui/react';

const {refs, floatingStyles} = useFloating({
  whileElementsMounted: autoUpdate,
});
```

<Notice type="warning">
  Only use this option if your floating element is _conditionally
  rendered_, not hidden with CSS. Use an effect to call and clean
  up `autoUpdate` in the latter scenario.
</Notice>

## API docs

Visit the full [`useFloating` API docs](/docs/useFloating) for
detailed information about customizing the positioning of
floating elements.

- [Externally pass elements](/docs/useFloating#elements)
- [Options](/docs/useFloating#options)
- [Return value](/docs/useFloating#return-value)

## Arrow

The `arrow` module exported from this package allows refs in
addition to elements:

```js
import {arrow} from '@floating-ui/react';

// Inside your component
const arrowRef = useRef(null);
useFloating({
  middleware: [
    arrow({
      element: arrowRef,
    }),
  ],
});
```

If you need your arrow to be _reactive_ to updates (e.g. showing
or hiding the arrow with conditional rendering while the floating
element is open), you should use state instead. Alternatively,
you can use `visibility: hidden{:sass}` CSS to hide it and keep
using a plain ref.

For details on creating an arrow element, see the
[`arrow` middleware](/docs/arrow) page.

## Testing

When testing your components, ensure you flush microtasks
immediately after the floating element renders. This will avoid
the `act` warning.

```js
import {act} from '@testing-library/react';

test('something', async () => {
  render(<Tooltip open />);
  await act(async () => {}); // Flush microtasks.
  // Position state is ready by this line.
});
```

You may use this a lot, so you can create a custom function:

```js
const waitForPosition = () => act(async () => {});

test('something', async () => {
  render(<Tooltip open />);
  await waitForPosition();
  expect(screen.queryByRole('tooltip')).toBeInTheDocument();
});
```

## Narrow reference type

Because the `refs.setReference{:js}` callback ref accepts a
[virtual element](/docs/virtual-elements), you may need to narrow
the type when performing DOM operations on the ref:

```js
const {refs} = useFloating<HTMLButtonElement>();

// @floating-ui/react
// refs.domReference.current is now of type HTMLButtonElement

// @floating-ui/react-dom
// refs.reference.current is now of type HTMLButtonElement
```

In the full package, it is narrowed on `refs.domReference{:js}`,
as the
[position can be separated](/docs/react#changing-the-positioning-reference-while-retaining-events).

## Interactions

To add interactions, such as the ability to only show a floating
element while hovering over its reference element, the hook must
first accept the following two options:

- `open{:.objectKey}` — a
  <WordHighlight id="a">boolean</WordHighlight> that represents whether
  the floating element is currently rendered.
- `onOpenChange{:.objectKey}` — an <WordHighlight id="b">event
  callback</WordHighlight> invoked when the open boolean state
  should change.

```js /isOpen/#a /setIsOpen/#b
import {useFloating} from '@floating-ui/react';

function App() {
  const [isOpen, setIsOpen] = useState(false);

  const {refs, floatingStyles} = useFloating({
    open: isOpen,
    onOpenChange: setIsOpen,
  });

  return (
    <>
      <button ref={refs.setReference}>Button</button>
      {isOpen && (
        <div ref={refs.setFloating} style={floatingStyles}>
          Tooltip
        </div>
      )}
    </>
  );
}
```

Note that floating components do not always require "anchor
positioning", so `floatingStyles` can be ignored.

<Notice>
  Interactions are only supported by `@floating-ui/react`, not
  `@floating-ui/react-dom`.
</Notice>

## Interaction hooks

Interaction hooks allow the open state to change, among other
functionality. Each interaction hook accepts the
`context{:.const}` object which gets returned from
`useFloating(){:js}` as their first argument:

```js /context/
import {
  useFloating,
  useInteractions,
  useHover,
  useFocus,
} from '@floating-ui/react';

// Inside your component
const {refs, context} = useFloating({
  open: isOpen,
  onOpenChange: setIsOpen,
});

const hover = useHover(context);
const focus = useFocus(context);

const {getReferenceProps, getFloatingProps} = useInteractions([
  hover,
  focus,
]);
```

The `useHover(){:js}` and `useFocus(){:js}` hooks set up effects
and return event handler props to change the open state, the
latter of which get merged by `useInteractions(){:js}` for
rendering.

This API enables each of the hooks to be fully tree-shakeable and
opt-in. The navigation bar on the left explains them in detail.

### Prop getters

The prop getters are used to add event handlers returned from the
interaction hooks, among other functionality, to the reference
and floating elements. When called, they return an object of
props like `onFocus{:.keyword}`.

```js
<>
  <button ref={refs.setReference} {...getReferenceProps()}>
    My button
  </button>
  <div
    ref={refs.setFloating}
    style={floatingStyles}
    {...getFloatingProps()}
  >
    My tooltip
  </div>
</>
```

All custom event listener props, such as `onClick{:.keyword}`,
`onKeyDown{:.keyword}` and more you pass to the element should be
specified inside the prop getter. They perform merging of their
own internal event listeners and your own without overwriting
them.

```js
// ❌ Your `onClick` can be overwritten:
<div
  onClick={() => {
    // Potentially overwritten by the props below.
  }}
  {...getReferenceProps()}
/>
```

```js
// ✅ Merging works inside `getReferenceProps()`:
<div
  {...getReferenceProps({
    onClick() {
      // Will not be overwritten.
    },
  })}
/>
```

You may find passing all props through the prop getter helps you
remember to prevent overriding event handlers, but is not
currently required unless the value is a function event handler
that starts with `on`.

## Open event

The `onOpenChange{:.function}` event callback is invoked with an
(optional) event as a second parameter:

```js /event/1-2
useFloating({
  onOpenChange(isOpen, event) {
    setIsOpen(isOpen);
    if (event) {
      // The event can be determined. This callback may be invoked
      // in an effect, so the event is not available.
    }
  },
});
```

Note that `onOpenChange{:.function}` is _not_ called if you
manually changed the open state via the `setIsOpen(){:js}`
setter. You can derive the event yourself in this case anyway.

## Changing the positioning reference while retaining events

- `refs.setReference{:js}` element is **both** the events and
  position reference by default.
- `refs.setPositionReference{:js}` allows you to separate the
  position to another element (either real or virtual).

```js /refs.setPositionReference/
const {refs} = useFloating();

return (
  <>
    <button ref={refs.setReference} {...getReferenceProps()}>
      Event reference
    </button>
    <button ref={refs.setPositionReference}>
      Position reference
    </button>
  </>
);
```

[View on CodeSandbox](https://codesandbox.io/s/xenodochial-butterfly-1xtup0?file=/src/App.tsx)

## Multiple floating elements on a single reference element

```js
import {useMergeRefs} from '@floating-ui/react';
```

Refs can be merged with the
[`useMergeRefs`](/docs/react-utils#usemergerefs) hook, and props
can be merged by calling one of the getters inside of the other:

```js {9-12}
const {refs: tooltipRefs} = useFloating();
const {refs: menuRefs} = useFloating();

const {getReferenceProps: getTooltipReferenceProps} =
  useInteractions([]);
const {getReferenceProps: getMenuReferenceProps} =
  useInteractions([]);

const ref = useMergeRefs([
  tooltipRefs.setReference,
  menuRefs.setReference,
]);
const props = getTooltipReferenceProps(getMenuReferenceProps());

return (
  <button ref={ref} {...props}>
    Common reference
  </button>
);
```

[View on CodeSandbox](https://codesandbox.io/s/trusting-mendeleev-49qn11?file=/src/App.tsx)

## Disabled elements

Disabled elements don't fire events, so tooltips attached to
disabled buttons don't show. Avoid using the
`disabled{:.keyword}` prop, and make the button visually disabled
instead. This ensures you won't need any wrapper tags and makes
the tooltip accessible to all users.

[View on CodeSandbox](https://codesandbox.io/s/focused-feistel-0q6v43?file=/src/App.tsx)