diff --git a/README.md b/README.md index cae4872a..4bec1318 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ See the [upgrade notes](https://github.com/greena13/react-hotkeys/releases/tag/v - Supports [browser key names](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) and [Mousetrap syntax](https://github.com/ccampbell/mousetrap) - Allows you to define [global](#GlobalHotKeys-component) and [in-focus](#HotKeys-component) hot keys - Allows you to easily [display a list of available hot keys to the user](#Displaying-a-list-of-available-hot-keys) -- Works with React's Synthetic KeyboardEvents and event delegation and provides [predictable and expected behaviour](#Interaction-with-React) to anyone familiar with React +- Works with React's Synthetic KeyboardEvents and event delegation and provides [predictable and expected behaviour](#Interaction-with-React) to anyone familiar with React - It is optimized by default, but allows you to turn off different optimisation measures in a granular fashion - It's customizable through a simple [configuration API](#Configuration) - [Optimized for larger applications](#Optimizations), with many hot keys active at once @@ -35,26 +35,24 @@ See the [upgrade notes](https://github.com/greena13/react-hotkeys/releases/tag/v #### Define a key map ```javascript -import {HotKeys} from 'react-hotkeys'; -import MyNode from './MyNode'; +import { HotKeys } from "react-hotkeys"; +import MyNode from "./MyNode"; const keyMap = { - SNAP_LEFT: 'command+left', - DELETE_NODE: ['del', 'backspace'] + SNAP_LEFT: "command+left", + DELETE_NODE: ["del", "backspace"] }; -const App = React.createClass({ - render() { - return ( - -
- - -
-
- ); - } -}); +const App = () => { + return ( + +
+ + +
+
+ ); +}; export default App; ``` @@ -62,21 +60,15 @@ export default App; #### Define handlers ```javascript -import {HotKeys} from 'react-hotkeys'; +import { HotKeys } from "react-hotkeys"; -const MyNode = React.createClass({ - render() { - const handlers = { - DELETE_NODE: this.deleteNode - }; +const MyNode = () => { + const handlers = { + DELETE_NODE: this.deleteNode + }; - return ( - - Node contents - - ); - } -}); + return Node contents; +}; export default MyNode; ``` @@ -157,14 +149,14 @@ The Bower version of the package will **not** be supported going forward (includ `react-hotkeys` uses key maps to decouple defining keyboard shortcuts from the functions they call. This allows hot keys and handler functions to be defined and maintained independent of one another. -> When a user presses the corresponding combination or sequence of keys, it is said they *match* the hot keys, which causes an action to be *triggered*. `react-hotkeys` may then resolve an appropriate handler function to *handle* the action. +> When a user presses the corresponding combination or sequence of keys, it is said they _match_ the hot keys, which causes an action to be _triggered_. `react-hotkeys` may then resolve an appropriate handler function to _handle_ the action. Key maps are Plain Old JavaScript Objects, where the keys are the action names and the values are usually a [Mousetrap-supported](https://craig.is/killing/mice) or [Browser Key Values](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) sequence string (but can also be an [array](#Alternative-Hotkeys) or an [object](#Key-Combination-vs-Sequences)) that must be matched in order to trigger the action. ```javascript const keyMap = { - 'deleteNode': 'del', - 'moveUp': 'up' + deleteNode: "del", + moveUp: "up" }; ``` @@ -192,14 +184,15 @@ Please refer to [Mousetrap's documentation](https://craig.is/killing/mice) or [B #### Alternative Hotkeys -You can specify multiple *alternative* key sequences (they will trigger the same action) using arrays: +You can specify multiple _alternative_ key sequences (they will trigger the same action) using arrays: ```javascript const keyMap = { - DELETE_NODE: ['del', 'backspace'], - MOVE_UP: ['up', 'w'] + DELETE_NODE: ["del", "backspace"], + MOVE_UP: ["up", "w"] }; ``` + #### Specifying key events (keydown, keypress, keyup) By default, `react-hotkeys` will match hotkey sequences on the `keydown` event (or, more precisely: on the `keydown` event of the last key to complete the last combination in a sequence). @@ -208,8 +201,8 @@ If you want to trigger a single action on a different key event, you can use the ```javascript const keyMap = { - CONTRACT: 'alt+down', - COMMAND_DOWN: {sequence: 'command', action: 'keydown'}, + CONTRACT: "alt+down", + COMMAND_DOWN: { sequence: "command", action: "keydown" } }; ``` @@ -221,10 +214,10 @@ The full list of valid key events is: `keypress`, `keydown`, and `keyup`. As a general rule, you should use the syntax that is the most brief, but still allows you to express the configuration you want. -| Question | Yes | No | -| :--- | :--- | :--- | -| **Need to define alternative key sequences to trigger the same action?** | Use an array of strings or objects. | Use a string or object. | -| **Need to explicitly define the key event to bind to (or some other additional option)?** | Use an object. | Use a string. | +| Question | Yes | No | +| :---------------------------------------------------------------------------------------- | :---------------------------------- | :---------------------- | +| **Need to define alternative key sequences to trigger the same action?** | Use an array of strings or objects. | Use a string or object. | +| **Need to explicitly define the key event to bind to (or some other additional option)?** | Use an object. | Use a string. | ## Defining Handlers @@ -233,46 +226,46 @@ Key maps trigger actions when they match a key sequence. Handlers are the functi Handlers may be defined in the same `` component as the key map: ```javascript -import {HotKeys} from 'react-hotkeys'; +import { HotKeys } from "react-hotkeys"; const keyMap = { - MOVE_UP: 'up', -} + MOVE_UP: "up" +}; const handlers = { - MOVE_UP: (event) => console.log('Move up hotkey called!') + MOVE_UP: event => console.log("Move up hotkey called!") }; - +; ``` -Or they may be defined in any *descendant* of the `` component that defines the key map: +Or they may be defined in any _descendant_ of the `` component that defines the key map: - ```javascript - import {HotKeys} from 'react-hotkeys'; +```javascript +import { HotKeys } from "react-hotkeys"; - const keyMap = { - MOVE_UP: 'up', - } +const keyMap = { + MOVE_UP: "up" +}; - const handlers = { - MOVE_UP: (event) => console.log('Move up hotkey called!') - }; +const handlers = { + MOVE_UP: event => console.log("Move up hotkey called!") +}; - -
+ +
-
+
-
+
-
- - ``` +
+
; +``` #### DEPRECATED: Hard Sequence Handlers @@ -290,7 +283,7 @@ To use hard sequence handlers, you must first enable them using the `enableHardS */ const handlers = { - 'up': (event) => console.log('up key called') + up: event => console.log("up key called") }; ``` @@ -329,14 +322,13 @@ HTML5 allows any element with a `tabindex` attribute to receive focus. If you wish to support HTML4 you are limited to the following focusable elements: -* `` -* `` -* `