# useHover
Opens the floating element while hovering over the reference
element, like CSS `:hover`.
```js
import {useHover} from '@floating-ui/react';
```
## Usage
This hook is an interaction hook that returns event handler
props.
To use it, pass it the `context{:.const}` object returned from
`useFloating(){:js}`, and then feed its result into the
`useInteractions(){:js}` array. The returned prop getters are
then spread onto the elements for rendering.
```js {9-13} /context/
function App() {
const [isOpen, setIsOpen] = useState(false);
const {refs, floatingStyles, context} = useFloating({
open: isOpen,
onOpenChange: setIsOpen,
});
const hover = useHover(context);
const {getReferenceProps, getFloatingProps} = useInteractions([
hover,
]);
return (
<>
Reference element
{isOpen && (
Floating element
)}
);
}
```
## Examples
- [Default hover](https://codesandbox.io/s/late-https-lu3833?file=/src/App.tsx)
## Props
```ts
interface Props {
enabled?: boolean;
mouseOnly?: boolean;
delay?: number | Partial<{open: number; close: number}>;
restMs?: number;
move?: boolean;
handleClose?: null | HandleCloseFn;
}
```
### enabled
default: `true{:js}`
Conditionally enable/disable the hook.
```js
useHover(context, {
enabled: false,
});
```
### mouseOnly
default: `false{:js}`
Whether the logic only runs for mouse input, ignoring both touch
and pen pointer inputs.
```js
useHover(context, {
mouseOnly: true,
});
```
### delay
default: `0{:js}`
Waits for the specified time when the event listener runs before
changing the `open{:.const}` state.
```js
useHover(context, {
// both open and close in ms
delay: 500,
// configure them individually
delay: {
open: 500,
close: 0,
},
});
```
### restMs
default: `0{:js}` (off)
Waits until the user's cursor is at "rest" over the reference
element before changing the open state.
```js
useHover(context, {
// waits 150 ms once the user's cursor is at rest
restMs: 150,
});
```
You can also use a fallback delay if the user's cursor never
rests, to ensure the floating element will eventually open:
```js
useHover(context, {
restMs: 150,
// if their cursor never rests, open it after 1000 ms (fallback)
delay: {open: 1000},
});
```
### move
default: `true{:js}`
Whether moving the cursor over the floating element will open it,
without a regular hover event required.
For example, if it was resting over the reference element when it
closed. Uses the `'mousemove'{:js}` event.
```js
useHover(context, {
move: false,
});
```
### handleClose
default: `null{:js}`
Instead of closing the floating element when the cursor leaves
its reference, we can leave it open until a certain condition is
satisfied.
The package exports a `safePolygon(){:js}` handler which will
only close the floating element if the pointer is outside a
dynamically computed polygon area.
This allows the user to move the cursor off the reference element
and towards the floating element without it closing (e.g. it has
interactive content inside).
```js
import {useHover, safePolygon} from '@floating-ui/react';
// ...
useHover(context, {
handleClose: safePolygon(),
});
```
This handler runs on `mousemove{:.string}`.
For a simpler alternative, depending on the type of floating
element, you can use a short close delay instead.
## safePolygon
A "safe" polygon is one that a pointer is safe to traverse as it
moves off the reference element and toward the floating element
after hovering it. If the pointer moves outside of this safe
area, the floating element closes.
It is a dynamic polygon (either a rect or a triangle) originating
from the cursor once it leaves a reference element. The triangle
looks like this:
This function takes options.
### requireIntent
default: `true{:js}`
Determines whether intent is required for the triangle polygon to
be generated (that is, the cursor is moving quickly enough toward
the floating element). `false{:js}` will keep the triangle active
no matter the intent.
```js
useHover(context, {
handleClose: safePolygon({
requireIntent: false,
}),
});
```
When reference elements are placed near each other and they each
have a hoverable floating element attached, `true{:js}` ensures
that hover events for the other nearby references aren't too
aggressively blocked.
### buffer
default: `0.5{:js}`
Determines the amount of buffer (in pixels) there is around the
polygon.
While the default value should handle the vast majority of cases
correctly, if you find your floating element is closing
unexpectedly as the pointer tries to move toward the floating
element, try increasing this value.
```js
useHover(context, {
handleClose: safePolygon({
buffer: 1,
}),
});
```
#### Ignoring the triangle
If you only want the offset portion (rectangle bridge) between
the reference and floating elements to be considered, you can set
the value to `-Infinity{:js}`.
```js
useHover(context, {
handleClose: safePolygon({
// Don't generate a triangle polygon, only consider the
// rectangular bridge between the elements.
buffer: -Infinity,
}),
});
```
### blockPointerEvents
default: `false{:js}`
Whether CSS `pointer-events` behind the polygon, reference, and
floating elements are blocked. This ensures the user does not
fire hover events over other elements unintentionally while they
traverse the polygon.
```js
useHover(context, {
handleClose: safePolygon({
blockPointerEvents: true,
}),
});
```
This can cause container elements that listen for `mouseleave`
events to fire. In older versions of Chrome (<114), scrolling
containers can't be scrolled while the pointer is over the
floating element (the main window remains unaffected).
A `[data-floating-ui-safe-polygon]{:.keyword}` selector is
available as a parent, so scrolling containers can negate the
`pointer-events{:.function}` style:
```css
[data-floating-ui-safe-polygon] .scroll {
pointer-events: auto;
}
[data-floating-ui-safe-polygon] .scroll > div {
pointer-events: none;
}
```
```js
Content inside here will remain blocked without affecting the
scrolling parent.