# react-locky

> Lock Loki

Latest version **1.5.7** (published 2019-04-15) · MIT license · 0 weekly downloads

## Install

```sh
npm install react-locky
pnpm add react-locky
yarn add react-locky
bun add react-locky
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.5.7 |
| Published | 2019-04-15 |
| First published | 2018-04-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 1 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | theKashey |
| Maintainers | kashey |
| Keywords | react, lock, event, isolation |

## Links

- npm: https://www.npmjs.com/package/react-locky
- Repository: https://github.com/theKashey/react-locky
- Homepage: https://github.com/theKashey/react-locky#readme
- Issues: https://github.com/theKashey/react-locky/issues
- npm.io page: https://npm.io/package/react-locky

## Dependencies (2)

- [prop-types](https://npm.io/package/prop-types.md) ^15.6.2
- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.1.5

## Alternatives

- [async-exit-hook](https://npm.io/package/async-exit-hook.md) — 3.7M weekly downloads
- [evnty](https://npm.io/package/evnty.md) — 7.2K weekly downloads
- [eleventy-plugin-asciidoc](https://npm.io/package/eleventy-plugin-asciidoc.md) — 3.5K weekly downloads
- [@jswork/next-get2get](https://npm.io/package/@jswork/next-get2get.md) — 945 weekly downloads
- [@dashersw/axon](https://npm.io/package/@dashersw/axon.md) — 934 weekly downloads

## Recent versions

- 1.5.7 (latest) — 2019-04-15
- 1.5.6 — 2019-03-28
- 1.5.5 — 2019-02-06
- 1.5.4 — 2019-01-29
- 1.5.3 — 2019-01-02
- 1.5.2 — 2018-12-30
- 1.5.1 — 2018-11-09
- 1.5.0 — 2018-11-09
- 1.4.5 — 2018-09-28
- 1.4.4 — 2018-08-23
- 1.4.3 — 2018-08-13
- 1.4.2 — 2018-08-13
- 1.4.1 — 2018-07-18
- 1.4.0 — 2018-07-18
- 1.3.0 — 2018-07-16
- … 10 more at https://npm.io/package/react-locky/versions

## README

# react-locky 
[![CircleCI status](https://img.shields.io/circleci/project/github/theKashey/react-locky/master.svg?style=flat-square)](https://circleci.com/gh/theKashey/react-locky/tree/master)
[![Greenkeeper badge](https://badges.greenkeeper.io/theKashey/react-locky.svg)](https://greenkeeper.io/)

----

[![NPM](https://nodei.co/npm/react-locky.png?downloads=true&stars=true)](https://nodei.co/npm/react-locky/) 

Loki  - is God of Mischief, Madness and Evil!

Locky - is God of Locks, Event capturing and Stealing. Small and very slender brother - just __1.7kb__.

Locky will never let event escape the target node, will prevent scrolls outside, will do the HTML5 `inert` job.
Locky will completely disable any user iterations outside of nested children.

```js
import Locky from 'react-locky';

 <div>
     <Button>You will be unable to press</Button>
     <Scrollable>You will be unable to scroll</Scrollable
     
     <Locky>
        <Button>You will be ABLE to press</Button>
        <Scrollable>You will be able to scroll</Scrollable
     </Locky>
     
     // you can tune behavior
     <Locky events={{keydown: false}}>
       // Locky got everything, except keydown        
     </Locky>
 </div>
```

In case you need to lock only scroll

```js
 <Locky noDefault events={{scroll: true}}> .... </Locky>
```

# API
 Locky accepts a few props.
 - enabled[=true], controls Locky behavior. 
 - onEscape, will be triggered when someone will try "escape" the lock. See "report" events below
 - noDefault[=false], disables all "default" events
 - events[=defaultEvents], DOM events to manage
 - group[=null], focus group id. Locks with the same group will not block each other. You may setup groups manually by adding
 `data-locky-group={name}` attribute anywhere.
 - component[=div], allows to replace HTML tag.
 - className[=null], Locky will forward className to component.
 - headless[=false], Locky will not create `component`, but will use the first node inside it (groups will probably not work).
 - leaded[=false], Locky will work only with "group" leader - mounted last instance for the provided group.
 
# Default events
 - click: 'report' (will call `onEscape`)
 - mousemove: true,
 - mousedown: 'report' (will call `onEscape`)
 - touchmove: true,
 - touchstart: 'report' (will call `onEscape`)
 - keydown: true,
 - focus: false, (focus is unblockable)
 - change: false,
 - scroll: true, (scroll is handled separately)
 - wheel: true, 
 
# Example
 - https://codesandbox.io/s/0ok0pz7vml - "Scroll" locky
 - https://codesandbox.io/s/l7nrkv1rnq - simple Locky
 - https://codesandbox.io/s/k55641yx6o - a bit more complex 
 
# Tip

Probably you __don't need to hook a keyboard__. It will also block page refresh events.
```js
<Locky events={{keydown:false}} />
```

__important__ tip for __Mobile Safary__ - while normal "touch move" will
scroll "scrollable" container, touch+move started on inputs will start
__drag-n-drop__ and cause whole layer(modal/page) scroll. 
(it will just scroll as a 💩, or not scroll at all).

To disable this behavior - apply ` -webkit-overflow-scrolling: touch;` on the page.
 
Locky in non-headless mode will produce a div. That div could be something you dont want to have.
Feel free to set a `className` prop, with class holding `display:inline` - as a result parasite div will
shrink to 1 pixel. 
 
# Other usages

Just track clicks outside your element
```js
<Locky noDefault events={{click:'report-only'}} onEscape={onOuterElementClick}>
  ...your content
</Locky>
``` 

# More tools
Locky also exposes `LockyTransparent` component, which makes everything inside invisible to Locky
```js
import {LockyTransparent} from 'react-locky';

<LockyTransparent>this content will be "locky"-free</LockyTransparent>
```

# ScrollBars
Locks will __not hide your scroll bars__! And there is no way to prevent scrolling using the scroll bars.
You have to use [react-scrolllock](https://github.com/jossmac/react-scrolllock) to complitely disable scroll, or _Strollable_ from [react-stroller](https://github.com/theKashey/React-stroller) to hide scroll bars.

# Article
 - [How to train your scroll](https://hackernoon.com/how-to-train-a-your-scroll-c9edcf28dbfa) - a medium article.
 
# Related
 - [react-focus-lock](react-focus-lock) - to scope focus
  
 Locky __could not__ manage focus itself, as long there is no way to "preventDefault" it.
 Once you will "tab-out", you will not be able to "tab-in", as long key events are blocked. 
 
 - [dom-locky](https://github.com/thearnica/dom-locky) - Vanilla DOM API implimentation of Locky.
 
 - [react-stroller](https://github.com/theKashey/react-stroller) - React scrollbar manager. To hide or replace.
 
 - [react-scroll-locky](https://github.com/theKashey/react-scroll-locky) - to scope scroll(via locky) and remove scroll bars.
 
 `<Locky noDefault events={{scroll:true}} />` will do almost the same, but differently.
 As long `react-scroll-captor` manage "scroll" for `children`, locky could manage scroll for any `target` inside.
 Ie - if you have scrollable, inside scrollable, or scrollable is not a top-most node - react-scroll-captor will __not__ 
 work, while Locky will. 
 

# Licence
 MIT

---
_Source: https://npm.io/package/react-locky · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._