# useDismiss

Closes the floating element when a dismissal is requested — by
default, when the user presses the `escape` key or outside of the
floating element.

```js
import {useDismiss} 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 dismiss = useDismiss(context);

  const {getReferenceProps, getFloatingProps} = useInteractions([
    dismiss,
  ]);

  return (
    <>
      <div ref={refs.setReference} {...getReferenceProps()}>
        Reference element
      </div>
      {isOpen && (
        <div
          ref={refs.setFloating}
          style={floatingStyles}
          {...getFloatingProps()}
        >
          Floating element
        </div>
      )}
    </>
  );
}
```

## Props

```ts
interface Props {
  enabled?: boolean;
  escapeKey?: boolean;
  referencePress?: boolean;
  referencePressEvent?: 'pointerdown' | 'mousedown' | 'click';
  outsidePress?: boolean | ((event: MouseEvent) => boolean);
  outsidePressEvent?: 'pointerdown' | 'mousedown' | 'click';
  ancestorScroll?: boolean;
  bubbles?:
    | boolean
    | {escapeKey?: boolean; outsidePress?: boolean};
}
```

### enabled

default: `true{:js}`

Conditionally enable/disable the hook.

```js
useDismiss(context, {
  enabled: false,
});
```

### escapeKey

default: `true{:js}`

Whether to dismiss the floating element upon pressing the `esc`
key.

```js
useDismiss(context, {
  escapeKey: false,
});
```

### referencePress

default: `false{:js}`

Whether to dismiss the floating element upon pressing the
reference element.

```js
useDismiss(context, {
  referencePress: true,
});
```

You likely want to ensure the `move{:.objectKey}` option in the
`useHover(){:js}` hook has been disabled when this is in use.

#### Keyboard press dismissal

If you'd like to ensure the floating element is also dismissed
upon "pressing" the reference element via the keyboard, you can
add in your own handler(s) for this.

```js
getReferenceProps({
  // for a native <button>
  onClick() {
    setOpen(false);
  },
});
```

### referencePressEvent

default: `'pointerdown'{:js}`

The type of event to use to determine a "press".

```js
useDismiss(context, {
  // eager on both mouse + touch input
  referencePressEvent: 'pointerdown',
  // eager on mouse input, lazy on touch input
  referencePressEvent: 'mousedown',
  // lazy on both mouse + touch input
  referencePressEvent: 'click',
});
```

### outsidePress

default: `true{:js}`

Whether to dismiss the floating element upon pressing outside of
both the floating and reference elements.

```js
useDismiss(context, {
  outsidePress: false,
});
```

If you have another element, like a toast, that is rendered
outside the floating element's React tree and don't want the
floating element to close when pressing it, you can guard the
check like so:

```js
useDismiss(context, {
  // Same as `true`, but with a custom guard check.
  outsidePress: (event) => !event.target.closest('.toast'),
});
```

```js
function App() {
  // The toast is not inside the Dialog's React tree, so we
  // need to add a guard to consider it a child of the Dialog
  // to prevent the Dialog's outside press from closing it.
  return (
    <>
      <Dialog />
      <Toast className="toast" />
    </>
  );
}
```

### outsidePressEvent

default: `'pointerdown'{:js}`

The type of event to use to determine a "press".

```js
useDismiss(context, {
  // eager on both mouse + touch input
  outsidePressEvent: 'pointerdown',
  // eager on mouse input, lazy on touch input
  outsidePressEvent: 'mousedown',
  // lazy on both mouse + touch input
  outsidePressEvent: 'click',
});
```

### ancestorScroll

default: `false{:js}`

Whether to dismiss the floating element upon scrolling an
overflow ancestor.

```js
useDismiss(context, {
  ancestorScroll: true,
});
```

### bubbles

default: `undefined{:js}`

When dealing with nested floating elements, this determines
whether the dismissal bubbles through the entire
`<FloatingTree />{:js}` or stops at the current node.

When `false{:js}`, the floating element must have focus inside
it.

Generally, nested modal dialogs (where focus cannot escape the
current node) will prefer no bubbling, while other nested
floating elements will prefer bubbling.

```js
useDismiss(context, {
  bubbles: false,
});
```

The boolean value of `bubbles` applies to both `escapeKey` and
`outsidePress` event bubbling. In case of a need to only disable
bubbling of one of those events, specify an object to the prop.
Any omitted events will use the default value.

```js
useDismiss(context, {
  bubbles: {
    escapeKey: true, // false by default
    outsidePress: false, // true by default
  },
});
```
