Skip to content
πŸ˜ŽπŸ–± React hook to listen for clicks outside of the component(s).
TypeScript JavaScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github
__mocks__
demo
rollup
src
.all-contributorsrc
.editorconfig
.gitignore
.nvmrc
.travis.yml
CHANGELOG.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
LICENSE
README.md
package.json
tsconfig.json
yarn.lock

README.md

React Cool Onclickoutside

This is a React hook to trigger callback when user clicks outside of the target component(s) area. It's a useful logic for UI interaction design (IxD) like dismiss a dropdown menu, modal or tooltip etc. You can check the features section to learn more.

⚑️ Live demo: https://react-cool-onclickoutside.netlify.com

❀️ it? ⭐️ it on GitHub or Tweet about it.

build status coverage status npm version npm downloads npm downloads npm bundle size MIT licensed All Contributors PRs welcome Twitter URL

Features

  • 🎣 Listen for clicks outside based on React hook.
  • πŸ‘―β€β™€οΈ Support multiple refs to cover more use cases.
  • 🧻 Uses passive event listeners to improve scrolling performance.
  • β›” Scrollbar can be excluded from the callback of outside clicks.
  • πŸ‘‚πŸ» Enable you to stop listening for outside clicks when needed.
  • πŸ“œ Support TypeScript type definition.
  • πŸ—„οΈ Server-side rendering friendly.
  • 🦠 Tiny size (< 1KB gzipped). No external dependencies, aside for the react.

Requirement

To use react-cool-onclickoutside, you must use react@16.8.0 or greater which includes hooks.

Installation

This package is distributed via npm.

$ yarn add react-cool-onclickoutside
# or
$ npm install --save react-cool-onclickoutside

Usage

Common use case.

import React, { useState, useRef } from 'react';
import useOnclickOutside from 'react-cool-onclickoutside';

const Dropdown = () => {
  const [openMenu, setOpenMenu] = useState(false);
  const ref = useRef();

  useOnclickOutside(ref, () => {
    setOpenMenu(false);
  });

  const handleClickBtn = () => {
    setOpenMenu(!openMenu);
  };

  return (
    <div>
      <button onClick={handleClickBtn}>Button</button>
      {openMenu && <div ref={ref}>Menu</div>}
    </div>
  );
};

Edit useOnclickOutside demo

Support multiple refs. Callback only be triggered when user clicks outside of the registered components.

import React, { useState, useRef } from 'react';
import useOnclickOutside from 'react-cool-onclickoutside';

const App = () => {
  const [showTips, setShowTips] = useState(true);
  const t1Ref = useRef();
  const t2Ref = useRef();

  useOnclickOutside([t1Ref, t2Ref], () => {
    setShowTips(false);
  });

  return (
    <div>
      {showTips && (
        <>
          <div ref={t1Ref}>Tooltip 1</div>
          <div ref={t2Ref}>Tooltip 2</div>
        </>
      )}
    </div>
  );
};

Disabling the Event Listener

In case you want to disable the event listener for performance reasons or fulfill some use cases. We provide the disabled option for you. Once you set it as true, the callback won’t be triggered.

import React, { useState, useRef } from 'react';
import useOnclickOutside from 'react-cool-onclickoutside';

const App = () => {
  const [disabled, setDisabled] = useState(false);
  const ref = useRef();

  useOnclickOutside(
    ref,
    () => {
      // Do something...
    },
    { disabled }
  );

  const handleBtnClick = () => {
    setDisabled(true);
  };

  return (
    <div>
      <button onClick={handleBtnClick}>
        Stop listening for outside clicks
      </button>
      <div ref={ref}>I'm a πŸ“¦</div>
    </div>
  );
};

API

type Ref = HTMLElement;
type Callback = (event?: Event) => void;

useOnclickOutside(ref: Ref | Ref[], callback: Callback, options?: object);

Parameters

You must pass the ref and callback to use this hook and you can access the event object via the callback parameter, default will be MouseEvent or TouchEvent.

const callback = event => {
  console.log('Event: ', event);
};

The options object may contain the following keys.

Key Type Default Description
disabled boolean false Enable/disable the event listener.
eventTypes Array ['mousedown', 'touchstart'] Which events to listen for.
excludeScrollbar boolean false Whether or not to listen (ignore) to browser scrollbar clicks.

Inspiration

Contributors ✨

Thanks goes to these wonderful people (emoji key):


Welly

πŸ’» πŸ“– 🚧

This project follows the all-contributors specification. Contributions of any kind welcome!

You can’t perform that action at this time.