react-detect-click-outside

A lightweight React hook that detects clicks outside elements and triggers a callback. Can also detect keypresses.

📈  Over 7,600 weekly users (as of June 2022).

👍  Great for toggling dropdowns!

_Notice: This package is looking for maintainers! Due to my professional and personal commitments, I don't have a whole lot of time to devote to maintaining this library. Some users have pointed out a few issues in the Github repo - feel free to take a stab at them!_

Table of Contents

- Features
- Installation
- Usage
- Requirements

$3

- 🖱 💻  Detects clicks outside an element and/or keypresses.
- 🔨  Customizable: disable clicks, disable keypresses, or specify keys that will trigger the callback
- 🎣  Built with React hooks
- 🔥  Written in TypeScript

$3

Install with Yarn:

``sh
yarn add react-detect-click-outside
`

Or with NPM:

`sh
npm i react-detect-click-outside
`

Import into your component like so:

`javascript
import { useDetectClickOutside } from 'react-detect-click-outside';
`

Usage

Here's an example of how to use the hook.

This library was built with UI features like dropdowns in mind. Below is a quick and functioning example of how to include it in a dropdown component:

`javascript
const Dropdown = ({ closeDropdown }) => {
const ref = useDetectClickOutside({ onTriggered: closeDropdown });
return (



);
};
`

How to implement the hook inside a function component:

1. Assign the hook to a variable before the component's return statement (above we use ref). Pass an empty object into the hook as an argument.

`javascript
const ref = useDetectClickOutside({});
`

2. The object you just passed into the useDetectClickOutside hook requires a property called onTriggered. The value of onTriggered must be a function — by default, it'll be called anytime a user clicks outside the component or hits the Escape key.

In the example above, we used a function called closeToggle. This function is passed down from a parent component (let's call it Container) and controls a piece of state that determines whether the Dropdown component is visible.

Here's a quick, trimmed-down example:

`javascript
const Container = () => {
const [displayDropdown, setDisplayDropdown] = useState(false);

const closeDropdown = () => {
setDisplayDropdown(false);
}
return (
{ displayDropdown && }
)
}
`

Now, go ahead and pass your callback into the useDetectClickOutside hook!

`javascript
const ref = useDetectClickOutside({ onTriggered: closeDropdown });
`

3. Assign your ref constant (or whatever constant you assigned the useDetectClickOutside hook to) as a ref to the outermost element returned by your target component.

`javascript
return (



);
`

Here's what the whole component should look like now:

`javascript
const Dropdown = ({ closeDropdown }) => {
const ref = useDetectClickOutside({ onTriggered: closeDropdown });
return (



);
};
`

Congrats! Your useDetectClickOutside should now trigger anytime a user clicks outside your component or presses the Escape key.

Want to customize your hook? Check out some of the additional options below.

Options

The object passed into the useDetectClickOutside hook accepts the following properties. Note that only onTriggered is required.

$3

#### Type: () => void

A callback function, e.g. one that toggles the visibility of the component. By default, this function is triggered by a click outside the component, and by an Escape keyup event.

Example:

`javascript
const ref = useDetectClickOutside({ onTriggered: closeDropdown });
`

$3

#### Type: boolean

When passed to the hook, this option will prevent clicks from triggering the onTriggered callback when the component is in the DOM. This option is disabled by default.

Example:

`javascript
const ref = useDetectClickOutside({
onTriggered: closeDropdown,
disableClick: true,
});
`

$3

#### Type: boolean

When passed to the hook, this option will prevent touch events from triggering the onTriggered callback when the component is in the DOM. This option is disabled by default.

Example:

`javascript
const ref = useDetectClickOutside({
onTriggered: closeDropdown,
disableTouch: true,
});
`

$3

#### Type: boolean

This option will prevent keypresses from triggering the onTriggered callback when the component is in the DOM. This option is disabled by default.

Example:

`javascript
const ref = useDetectClickOutside({
onTriggered: closeDropdown,
disableKeys: true,
});
`

$3

#### Type: boolean

This option will let any keypress trigger the onTriggered callback when the component is in the DOM - not just the Escape key. This option is disabled by default.

Example:

`javascript
const ref = useDetectClickOutside({
onTriggered: closeDropdown,
allowAnyKey: true,
});
`

$3

#### Type: string[]

An array of key values that will trigger the onTriggered callback.

Example:

`javascript
const ref = useDetectClickOutside({
onTriggered: closeDropdown,
triggerKeys: ['Enter', 'Tab', 'x'],
});
`

_Note:_ This option overrides the default hook behavior of triggering the onTriggered callback with the Escape key. If you still wish to trigger the onTriggered function with Escape, you need to add it to the array (e.g. triggerKeys=['Escape', 'Enter']`).

Requirements

You must be using React 16.8.0 or later. In other words, your version of React must support hooks.