9 |
10 | # Quick Start
11 | This is the documentation of react-timing-hooks.
12 | {: .fs-6 .fw-300 }
13 |
14 | [List of hooks](/react-timing-hooks/list-of-all-hooks/){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 }
15 | [View it on GitHub][repo]{: .btn .fs-5 .mb-4 .mb-md-0 }
16 |
17 | ---
18 |
19 | ## Installation
20 |
21 | ```bash
22 | # via npm
23 | npm i react-timing-hooks
24 |
25 | # via yarn
26 | yarn add react-timing-hooks
27 | ```
28 |
29 | {: .note }
30 | Since this is a React package, you have to install React `^16.8.0`, `^17.0.0` or `^18.0.0`, too, in order to use this package.
31 |
32 | ## Getting started
33 |
34 | Simply import the hook you need and use it in your React app! Here is an overview of all hooks in this package: [list of all hooks](/react-timing-hooks/list-of-all-hooks/).
35 |
36 | {: .highlight-title }
37 | > Typescript
38 | >
39 | > This package is developed in Typescript, so **everything is typed out of the box**. You don't need to install types seperately.
40 |
41 | ## Background
42 |
43 | In general all of these hooks are more or less wrappers for standard javascript functions. But since they can be quite
44 | a pain to handle in React components (leaks upon unmount etc.), I wrote this little package.
45 |
46 | There are currently hooks available for:
47 |
48 | * [setTimeout][timeout-mdn] (useTimeout, useTimeoutEffect, useThrottledState, ...)
49 | * [setInterval][interval-mdn] (useInterval, useTimer, useClock, ...)
50 | * [requestAnimationFrame][raf-mdn] (useAnimationFrame, useAnimationFrameLoop)
51 | * [requestIdleCallback][idle-cb-mdn] (useIdleCallback, useIdleCallbackEffect)
52 |
53 | **All hooks are documented on this page** (see sidebar). They should be pretty straight forward to use, but feel free
54 | to add an issue on GitHub if you have any ideas for improvement.
55 |
56 | {: .highlight-title }
57 | > Package size / Treeshaking
58 | >
59 | > This package is extremely small already (see [here](https://bundlephobia.com/result?p=react-timing-hooks)), but your bundle
60 | > size will be even less affected by this package, because it's completely **tree-shakable**, i.e. only hooks you actually use
61 | > will be bundled into your app js.
62 |
63 | ### Preventing leaks on unmount
64 |
65 | One of the most cumbersome things when dealing with timeouts and intervals in React is the **boilerplate** you have to write in order to use them properly.
66 |
67 | What you what normally do is to write clean-up code to manually clear pending timeouts/intervals in your React components.
68 | **With React Timing Hooks you don't have to do that.**
69 |
70 | #### Example
71 |
72 | For example: You might have a timeout that runs under a certain condition. In this case a cleanup
73 | has to be done in a separate `useEffect` call that cleans everything up (but only on unmount).
74 |
75 | Your code could look like this:
76 |
77 | ```javascript
78 | import { useEffect } from 'react'
79 |
80 | const TimeoutRenderer = ({ depA, depB }) => {
81 | const [output, setOutput] = useState(null)
82 | const timeoutId = useRef(null)
83 |
84 | useEffect(() => {
85 | if (depA && depB) {
86 | timeoutId.current = setTimeout(() => setOutput('Hello World'), 1000)
87 | }
88 | }, [depA, depB])
89 |
90 | useEffect(() => {
91 | return function onUnmount() {
92 | if (timeoutId.current !== null) {
93 | clearTimeout(timeoutId.current)
94 | }
95 | }
96 | }, [timeoutId])
97 |
98 | return output ? (
99 | {output}
126 |{output}
151 |{output}
22 | 26 |{count}
32 | 33 |{count}
108 | 111 | 112 | ) 113 | } 114 | 115 | it('does not cause an infinite render loop when paused on startup', async () => { 116 | const renderMock = jest.fn() 117 | render({time}
15 | 16 | 17 |{output}
24 |{counter}
25 |{isPaused ? 'Yes' : 'No'}
26 |{isStopped ? 'Yes' : 'No'}
27 | 30 | 33 | 36 | 39 |{count}
19 | 22 |{output}
24 | 28 |{output}
27 | 31 |{count}
28 |{isPaused ? 'Yes' : 'No'}
29 |{isStopped ? 'Yes' : 'No'}
30 | 31 | 32 | 33 | 34 | 38 |{isOn ? 'ON' : 'OFF'}
19 |{count}
27 |{throttledCount}
28 | 32 |{count}
19 | 22 |{output}
30 |{output2}
31 | 35 |{timer}
15 |