npmpackage.info

react-cool-onclickoutside

😎 🖱 React hook to listen for clicks outside of the component(s).

1.7.0

547

MIT

TypeScript

984.00 B

10,159,194 3.2

Installations

npm install react-cool-onclickoutside

Developer Guide

BETA

Typescript

Yes

Module System

CommonJS

Node Version

14.16.1

NPM Version

6.14.12 Score

95.7

Supply Chain

99.5

Quality

76.1

Maintenance

100

Vulnerability

100

License

Pull Requests

Open

28

Total

958

Closed

356

Merged

574

Issues

Open

2

Total

13

Closed

11

Releases

v1.7.0

Updated on Oct 06, 2021

v1.6.2

Updated on May 18, 2021

v1.6.1

Updated on Mar 08, 2021

v1.6.0

Updated on Feb 09, 2021

v1.5.9

Updated on Dec 09, 2020

v1.5.8

Updated on Oct 27, 2020

View All 19 releases

Contributors

Unable to fetch Contributors

View All 4 Contributors

Languages

TypeScript

SCSS

HTML

JavaScript

Shell

TypeScript (67.59%)

SCSS (11.84%)

HTML (11.39%)

JavaScript (8.68%)

Shell (0.49%)

Love this project? Help keep it running — sponsor us today! 🚀

Developer

wellyshen

Download Statistics

Total Downloads

10,159,194

Last Day

9,862

Last Week

49,674

Last Month

222,603

Last Year

2,747,951

GitHub Statistics

MIT License

547 Stars

1,512 Commits

13 Forks

5 Watchers

30 Branches

4 Contributors

Updated on Feb 11, 2025

Bundle Size

2.07 kB

Minified

984.00 B

Minified + Gzipped

Bundlephobia

Maintainers

Package Meta Information

Latest Version

1.7.0

Package Id

react-cool-onclickoutside@1.7.0

Size

8.07 kB

NPM Version

6.14.12

Node Version

14.16.1

Published on

Oct 06, 2021

Total Downloads

Cumulative downloads

Total Downloads

10,159,194

Last Day

0.6%

9,862

Compared to previous day

Last Week

-2.2%

49,674

Compared to previous week

Last Month

20.5%

222,603

Compared to previous month

Last Year

-3.2%

2,747,951

Compared to previous year

Daily Downloads

Weekly Downloads

Monthly Downloads

Yearly Downloads

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.app

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

Features

???? Listens for clicks outside based on React hook.
????‍♀️ Supports 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.
???? Ignores certain elements during the event loop.
???? Enables you to stop listening for outside clicks when needed.
???? Detects iframe clicks for better DX.
???? Supports custom refs for some reasons.
???? Supports TypeScript type definition.
????️ Server-side rendering compatibility.
???? 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.

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

Usage

Common use case.

1import { useState } from "react";
2import useOnclickOutside from "react-cool-onclickoutside";
3
4const Dropdown = () => {
5  const [openMenu, setOpenMenu] = useState(false);
6  const ref = useOnclickOutside(() => {
7    setOpenMenu(false);
8  });
9
10  const handleClickBtn = () => {
11    setOpenMenu(!openMenu);
12  };
13
14  return (
15    <div>
16      <button onClick={handleClickBtn}>Button</button>
17      {openMenu && <div ref={ref}>Menu</div>}
18    </div>
19  );
20};

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

1import { useState } from "react";
2import useOnclickOutside from "react-cool-onclickoutside";
3
4const App = () => {
5  const [showTips, setShowTips] = useState(true);
6  const ref = useOnclickOutside(() => {
7    setShowTips(false);
8  });
9
10  return (
11    <div>
12      {showTips && (
13        <>
14          <div ref={ref}>Tooltip 1</div>
15          <div ref={ref}>Tooltip 2</div>
16        </>
17      )}
18    </div>
19  );
20};

Ignore Elements by CSS Class Name

You can tell react-cool-onclickoutside to ignore certain elements during the event loop by the ignore-onclickoutside CSS class name. If you want explicit control over the class name, use the ignoreClass option.

1import { useState } from "react";
2import useOnclickOutside from "react-cool-onclickoutside";
3
4// Use the default CSS class name
5const App = () => {
6  const ref = useOnclickOutside(() => {
7    // Do something...
8  });
9
10  return (
11    <div>
12      <div ref={ref}>I'm a ????</div>
13      <div>Click me will trigger the event's callback</div>
14      <div className="ignore-onclickoutside">
15        Click me won't trigger the event's callback
16      </div>
17    </div>
18  );
19};
20
21// Use your own CSS class name
22const App = () => {
23  const ref = useOnclickOutside(
24    () => {
25      // Do something...
26    },
27    {
28      ignoreClass: "my-ignore-class", // Or ["class-1", "class-2"]
29    }
30  );
31
32  return (
33    <div>
34      <div ref={ref}>I'm a ????</div>
35      <div>Click me will trigger the event's callback</div>
36      <div className="my-ignore-class">
37        Click me won't trigger the event's callback
38      </div>
39    </div>
40  );
41};

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 to true, the callback won’t be triggered.

1import { useState } from "react";
2import useOnclickOutside from "react-cool-onclickoutside";
3
4const App = () => {
5  const [disabled, setDisabled] = useState(false);
6  const ref = useOnclickOutside(
7    () => {
8      // Do something...
9    },
10    { disabled }
11  );
12
13  const handleBtnClick = () => {
14    setDisabled(true);
15  };
16
17  return (
18    <div>
19      <button onClick={handleBtnClick}>
20        Stop listening for outside clicks
21      </button>
22      <div ref={ref}>I'm a ????</div>
23    </div>
24  );
25};

Use Your Own `ref`

In case of you had a ref already or you want to share a ref for other purposes. You can pass in the ref instead of using the one provided by this hook.

1const ref = useRef();
2
3useOnclickOutside(
4  () => {
5    // Do something...
6  },
7  { refs: [ref] }
8);

Detecting Iframe Clicks

Clicks on an <iframe> element won't trigger document.documentElement listeners, because it's literally different page with different security domain. However, when clicking on an iframe moves focus to its content's window that triggers the main window.blur event. react-cool-onclickoutside in conjunction the blur event with document.activeElement to detect if an iframe is clicked, and execute the provided callback.

The above-mentioned workaround has its caveats:

Clicks on an iframe will only trigger the provided callback once. Subsequent clicks on iframe will not trigger the callback until focus has been moved back to main window.
Move focus to iframe via keyboard navigation also triggers the provided callback.

For our convenience, this feature is enabled by default. You can optionally disable it by setting the detectIFrame to false if you find it conflicting with your use-case.

API

1const ref = useOnclickOutside(callback: (event: Event) => void, options?: object);

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

1const callback = (event) => {
2  console.log("Event: ", event);
3};

The options object contains the following keys.

Key	Type	Default	Description
`refs`	Array		For some reasons, you can pass in your own `ref(s)` instead of using the built-in.
`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.
`ignoreClass`	string \| string[]	`ignore-onclickoutside`	To ignore certain elements during the event loop by the CSS class name that you defined.
`detectIFrame`	boolean	`true`	To disable the feature of detecting iframe clicks.

Articles / Blog Posts

???? If you have written any blog post or article about react-cool-onclickoutside, please open a PR to add it here.

Featured on React Status #172.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

_Welly
???? ???? ????

_{DmitryScaletta}
????

_vardani
????

_{Alexey Cherepanov}
????

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

No vulnerabilities found.

10

Dangerous-Workflow

Determines if the project's GitHub Action workflows avoid dangerous patterns.

10

Binary-Artifacts

Determines if the project has generated executable (binary) artifacts in the source repository.

10

License

Determines if the project has defined a license.

7

SAST

Determines if the project uses static code analysis.

4

Security-Policy

Determines if the project has published a security policy.

0

Maintained

Determines if the project is "actively maintained".

0

Code-Review

Determines if the project requires human code review before pull requests (aka merge requests) are merged.

0

Token-Permissions

Determines if the project's workflows follow the principle of least privilege.

0

Pinned-Dependencies

Determines if the project has declared and pinned the dependencies of its build process.

Reason

dependency not pinned by hash detected -- score normalized to 0

Details

Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/wellyshen/react-cool-onclickoutside/ci.yml/master?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:24: update your workflow using https://app.stepsecurity.io/secureworkflow/wellyshen/react-cool-onclickoutside/ci.yml/master?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:31: update your workflow using https://app.stepsecurity.io/secureworkflow/wellyshen/react-cool-onclickoutside/ci.yml/master?enable=pin
Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:48: update your workflow using https://app.stepsecurity.io/secureworkflow/wellyshen/react-cool-onclickoutside/ci.yml/master?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:58: update your workflow using https://app.stepsecurity.io/secureworkflow/wellyshen/react-cool-onclickoutside/ci.yml/master?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:63: update your workflow using https://app.stepsecurity.io/secureworkflow/wellyshen/react-cool-onclickoutside/ci.yml/master?enable=pin
Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:76: update your workflow using https://app.stepsecurity.io/secureworkflow/wellyshen/react-cool-onclickoutside/ci.yml/master?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:35: update your workflow using https://app.stepsecurity.io/secureworkflow/wellyshen/react-cool-onclickoutside/codeql-analysis.yml/master?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:39: update your workflow using https://app.stepsecurity.io/secureworkflow/wellyshen/react-cool-onclickoutside/codeql-analysis.yml/master?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:47: update your workflow using https://app.stepsecurity.io/secureworkflow/wellyshen/react-cool-onclickoutside/codeql-analysis.yml/master?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:61: update your workflow using https://app.stepsecurity.io/secureworkflow/wellyshen/react-cool-onclickoutside/codeql-analysis.yml/master?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/size.yml:10: update your workflow using https://app.stepsecurity.io/secureworkflow/wellyshen/react-cool-onclickoutside/size.yml/master?enable=pin
Warn: third-party GitHubAction not pinned by hash: .github/workflows/size.yml:11: update your workflow using https://app.stepsecurity.io/secureworkflow/wellyshen/react-cool-onclickoutside/size.yml/master?enable=pin
Info: 0 out of 10 GitHub-owned GitHubAction dependencies pinned
Info: 0 out of 3 third-party GitHubAction dependencies pinned

0

CII-Best-Practices

Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.

0

Fuzzing

Determines if the project uses fuzzing.

0

Branch-Protection

Determines if the default and release branches are protected with GitHub's branch protection settings.

0

Vulnerabilities

Determines if the project has open, known unfixed vulnerabilities.

Reason

52 existing vulnerabilities detected

Details

Warn: Project is vulnerable to: GHSA-67hx-6x53-jw92
Warn: Project is vulnerable to: GHSA-qwcr-r2fm-qrc7
Warn: Project is vulnerable to: GHSA-grv7-fg5c-xmjg
Warn: Project is vulnerable to: GHSA-pxg6-pf52-xh8x
Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275
Warn: Project is vulnerable to: GHSA-ghr5-ch3p-vcr6
Warn: Project is vulnerable to: GHSA-rv95-896h-c2vc
Warn: Project is vulnerable to: GHSA-qw6h-vgh9-j6wx
Warn: Project is vulnerable to: GHSA-jchw-25xp-jwwc
Warn: Project is vulnerable to: GHSA-cxjh-pqwp-8mfp
Warn: Project is vulnerable to: GHSA-c7qv-q95q-8v27
Warn: Project is vulnerable to: GHSA-9c47-m6qq-7p4h
Warn: Project is vulnerable to: GHSA-76p3-8jx3-jpfq
Warn: Project is vulnerable to: GHSA-3rfm-jhwj-7488
Warn: Project is vulnerable to: GHSA-hhq3-ff78-jv3g
Warn: Project is vulnerable to: GHSA-952p-6rrq-rcjv
Warn: Project is vulnerable to: GHSA-f8q6-p94x-37v3
Warn: Project is vulnerable to: GHSA-mwcw-c2x4-8c55
Warn: Project is vulnerable to: GHSA-rp65-9cf3-cjxr
Warn: Project is vulnerable to: GHSA-9wv6-86v2-598j
Warn: Project is vulnerable to: GHSA-rhx6-c78j-4q9w
Warn: Project is vulnerable to: GHSA-7fh5-64p2-3v2j
Warn: Project is vulnerable to: GHSA-gcx4-mw62-g8wm
Warn: Project is vulnerable to: GHSA-c2qf-rxjj-qqgw
Warn: Project is vulnerable to: GHSA-m6fv-jmcg-4jfg
Warn: Project is vulnerable to: GHSA-cm22-4g7w-348p
Warn: Project is vulnerable to: GHSA-4wf5-vphf-c2xc
Warn: Project is vulnerable to: GHSA-72xf-g2v4-qvf3
Warn: Project is vulnerable to: GHSA-hc6q-2mpp-qw7j
Warn: Project is vulnerable to: GHSA-4vvj-4cpr-p986
Warn: Project is vulnerable to: GHSA-wr3j-pwj9-hqq6
Warn: Project is vulnerable to: GHSA-j8xg-fqg3-53r7
Warn: Project is vulnerable to: GHSA-3h5v-q93c-6h6q
Warn: Project is vulnerable to: GHSA-93q8-gq69-wqmw
Warn: Project is vulnerable to: GHSA-x9w5-v3q2-3rhw
Warn: Project is vulnerable to: GHSA-w8qv-6jwh-64r5
Warn: Project is vulnerable to: GHSA-w573-4hg7-7wgq
Warn: Project is vulnerable to: GHSA-434g-2637-qmqr
Warn: Project is vulnerable to: GHSA-49q7-c7j4-3p7m
Warn: Project is vulnerable to: GHSA-977x-g7h5-7qgw
Warn: Project is vulnerable to: GHSA-f7q4-pwc6-w24p
Warn: Project is vulnerable to: GHSA-fc9h-whq2-v747
Warn: Project is vulnerable to: GHSA-ww39-953v-wcq6
Warn: Project is vulnerable to: GHSA-43f8-2h32-f4cj
Warn: Project is vulnerable to: GHSA-896r-f27r-55mw
Warn: Project is vulnerable to: GHSA-xvch-5gv4-984h
Warn: Project is vulnerable to: GHSA-hj48-42vr-x3v9
Warn: Project is vulnerable to: GHSA-hrpp-h998-j3pp
Warn: Project is vulnerable to: GHSA-p8p7-x288-28g6
Warn: Project is vulnerable to: GHSA-g4rg-993r-mgx7
Warn: Project is vulnerable to: GHSA-jgrx-mgxx-jf9v
Warn: Project is vulnerable to: GHSA-6fc8-4gx4-v693

Score

3.2

/10

Last Scanned on 2025-02-03

The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.

Learn More

react-cool-onclickoutside

Installations

Developer Guide

Yes

CommonJS

14.16.1

6.14.12

Score

Pull Requests

28

958

356

574

Issues

2

13

11

Releases

Contributors

Unable to fetch Contributors

Languages

Developer

Download Statistics

GitHub Statistics

Bundle Size

2.07 kB

984.00 B

Maintainers

Package Meta Information

Total Downloads

10,159,194

Daily Downloads

Weekly Downloads

Monthly Downloads

Yearly Downloads

Peer Dependencies

Dev Dependencies

REACT COOL ONCLICKOUTSIDE

Features

Requirement

Installation

Usage

Ignore Elements by CSS Class Name

Disabling the Event Listener

Use Your Own ref

Detecting Iframe Clicks

API

Articles / Blog Posts

Contributors ✨

10

10

10

7

4

0

0

0

0

0

0

0

0

3.2

/10

Use Your Own `ref`