From 32aa170e4899b3713290bbfcde677650b39be378 Mon Sep 17 00:00:00 2001 From: Eric Lambrecht Date: Sat, 3 Aug 2024 15:13:41 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20=F0=9F=93=9D=20Update=20documentation?= =?UTF-8?q?=20structure=20and=20layout?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 30 +++++------ docs/animation-api/index.md | 15 ------ docs/callbacks/index.md | 20 ++++++++ .../useAnimationFrame.md | 8 +-- .../useDebounce.md | 9 ++-- .../useIdleCallback.md | 3 +- .../useThrottle.md | 9 ++-- .../{timeouts-api => callbacks}/useTimeout.md | 4 +- docs/{idle-callback-api => effects}/index.md | 6 +-- .../useIdleCallbackEffect.md | 2 +- .../useTimeoutEffect.md | 2 +- docs/index.md | 51 ++++++++++++------- docs/intervals-api/index.md | 22 -------- docs/list-of-all-hooks/index.md | 34 +++++++++---- docs/loops-and-intervals/index.md | 22 ++++++++ .../useAnimationFrameLoop.md | 11 ++-- .../useClock.md | 4 +- .../useCountdown.md | 13 +++-- .../useCounter.md | 14 +++-- .../useInterval.md | 18 ++++--- .../useTimer.md | 14 +++-- docs/migrations/index.md | 2 +- docs/{general-utility => state}/index.md | 8 +-- .../useThrottledState.md | 13 +++-- docs/timeouts-api/index.md | 19 ------- 25 files changed, 202 insertions(+), 151 deletions(-) delete mode 100644 docs/animation-api/index.md create mode 100644 docs/callbacks/index.md rename docs/{animation-api => callbacks}/useAnimationFrame.md (89%) rename docs/{timeouts-api => callbacks}/useDebounce.md (91%) rename docs/{idle-callback-api => callbacks}/useIdleCallback.md (96%) rename docs/{timeouts-api => callbacks}/useThrottle.md (89%) rename docs/{timeouts-api => callbacks}/useTimeout.md (97%) rename docs/{idle-callback-api => effects}/index.md (88%) rename docs/{idle-callback-api => effects}/useIdleCallbackEffect.md (98%) rename docs/{timeouts-api => effects}/useTimeoutEffect.md (99%) delete mode 100644 docs/intervals-api/index.md create mode 100644 docs/loops-and-intervals/index.md rename docs/{animation-api => loops-and-intervals}/useAnimationFrameLoop.md (91%) rename docs/{intervals-api => loops-and-intervals}/useClock.md (98%) rename docs/{intervals-api => loops-and-intervals}/useCountdown.md (87%) rename docs/{intervals-api => loops-and-intervals}/useCounter.md (89%) rename docs/{intervals-api => loops-and-intervals}/useInterval.md (89%) rename docs/{intervals-api => loops-and-intervals}/useTimer.md (72%) rename docs/{general-utility => state}/index.md (55%) rename docs/{general-utility => state}/useThrottledState.md (81%) delete mode 100644 docs/timeouts-api/index.md diff --git a/README.md b/README.md index 71f661c..22609e0 100644 --- a/README.md +++ b/README.md @@ -8,29 +8,29 @@ ## What's this?! -This is a very little package with **React hooks wrapping time-related Vanilla JS functions**, +This is a very little package with **React hooks wrapping time-related vanilla Javascript functions**, so you can use them with minimal effort in your React apps without having to worry about manual clean up, or writing boilerplate to pause/resume intervals etc. ### Feature Overview -* Several React hooks **wrapping Vanilla JS functions** like: - * setInterval() – [All Hooks][interval-api] | [MDN][interval-mdn] - * setTimeout() – [All Hooks][timeout-api] | [MDN][timeout-mdn] - * window.requestAnimationFrame() – [All Hooks][raf-api] | [MDN][raf-mdn] - * window.requestIdleCallback() – [All Hooks][idle-cb-api] | [MDN][idle-cb-mdn] -* …and **additional [utility hooks][all-hooks]** for things like - * rate-limiting: `useThrottledState()`, `useDebounce()`, `useThrottle()` - * rendering: `useAnimationFrameLoop()` - * counters: `useCounter()`, `useCountdown()`, `useTimer()` +* Hooks for all timing-related **vanilla JS functions** like: + * setInterval() –> [useInterval()][interval-api] | [MDN][interval-mdn] + * setTimeout() –> [useTimeout()][timeout-api] | [MDN][timeout-mdn] + * requestAnimationFrame() –> [useAnimationFrame()][raf-api] | [MDN][raf-mdn] + * requestIdleCallback() –> [useIdleCallback()][idle-cb-api] | [MDN][idle-cb-mdn] +* …and **additional [utility hooks][all-hooks]** for common tasks like + * throttling: `useThrottledState()`, `useThrottle()`, `useDebounce()` + * GFX/animation/rendering: `useAnimationFrameLoop()` + * reactive counters: `useCounter()`, `useCountdown()`, `useTimer()` * time: `useClock()` - * effects: `useTimeoutEffect()`, `useIdleCallbackEffect()` -* Ability to **pause, resume, start or stop intervals** + * async effects: `useTimeoutEffect()`, `useIdleCallbackEffect()` +* **Reactive intervals**: intervals can be controlled via **pause, resume, start or stop** * A **versatile API**: customizable settings, many hook "flavors" depending on the use-case. -* **Automatic clean-ups** of pending timers, intervals etc. +* **Automatic clean-ups** of pending timers, intervals etc. on unmount * Callbacks are **automatically memoized** * Full **Typescript** support -* **[Lightweight](https://bundlephobia.com/result?p=react-timing-hooks)** (less than 2KB minzipped, no transitive dependencies!) +* Very **[lightweight](https://bundlephobia.com/result?p=react-timing-hooks)** (no transitive dependencies!) * **Tree-shakable** — You only bundle what you use! @@ -52,7 +52,7 @@ yarn add react-timing-hooks https://ericlambrecht.github.io/react-timing-hooks/migrations/ -## Examples +## Some Examples #### A "status logger" with `useInterval()` ```jsx harmony diff --git a/docs/animation-api/index.md b/docs/animation-api/index.md deleted file mode 100644 index 1233602..0000000 --- a/docs/animation-api/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -layout: default -title: Animation -nav_order: 4 -has_children: true ---- - -# Animation - -React hooks that wrap [window.requestAnimationFrame()][raf-mdn]. -{: .fs-6 .fw-300 } - -All of these hooks will automatically take care of cancelling any pending animation frame callbacks that you started if the component unmounts for example. - -[raf-mdn]: https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame diff --git a/docs/callbacks/index.md b/docs/callbacks/index.md new file mode 100644 index 0000000..5321bb2 --- /dev/null +++ b/docs/callbacks/index.md @@ -0,0 +1,20 @@ +--- +layout: default +title: Callbacks / Functions +nav_order: 3 +has_children: true +--- + +# Timeouts + +React hooks that return some form of timed callback. +{: .fs-6 .fw-300 } + +Most of these callbacks are based on [setTimeout()][timeout-mdn]. + +For *rate-limiting* use `useThrottle()` or `useDebounce()`. For *pure timeouts* use `useTimeout()` or `useTimeoutEffect()`. + +{: .note } +All of these hooks are memoized and will automatically take care of clearing any pending timeouts on unmount. + +[timeout-mdn]: https://developer.mozilla.org/en-US/docs/Web/API/setTimeout diff --git a/docs/animation-api/useAnimationFrame.md b/docs/callbacks/useAnimationFrame.md similarity index 89% rename from docs/animation-api/useAnimationFrame.md rename to docs/callbacks/useAnimationFrame.md index a820415..06885aa 100644 --- a/docs/animation-api/useAnimationFrame.md +++ b/docs/callbacks/useAnimationFrame.md @@ -1,6 +1,6 @@ --- title: useAnimationFrame -parent: Animation +parent: Callbacks / Functions nav_order: 2 --- @@ -8,8 +8,10 @@ nav_order: 2 Use this hook to create a callback that executes the provided function via [`window.requestAnimationFrame()`][raf-mdn]. -_This hook is quite low level._ -You might want to use `useAnimationFrameLoop()` or `useIdleCallback()` instead. +{: .highlight-title } +> Note +> +> _This hook is quite low level._ You might want to use `useAnimationFrameLoop()` or `useIdleCallback()` instead. ## Example diff --git a/docs/timeouts-api/useDebounce.md b/docs/callbacks/useDebounce.md similarity index 91% rename from docs/timeouts-api/useDebounce.md rename to docs/callbacks/useDebounce.md index ef9fa5a..c66e736 100644 --- a/docs/timeouts-api/useDebounce.md +++ b/docs/callbacks/useDebounce.md @@ -1,6 +1,6 @@ --- title: useDebounce -parent: Timeouts +parent: Callbacks / Functions nav_order: 4 --- @@ -12,8 +12,11 @@ Debounces a callback. Use this hook if you want a function that "blocks" consecutive calls until a specified time has passed since the last invocation. This is called **debouncing**. -If you want a callback that [doesn't debounce but throttles][thr-vs-deb], take a look at `useThrottle()`. - +{: .note-title } +> Throttle vs. Debounce +> +> If you want a callback that [doesn't debounce but throttles][thr-vs-deb], take a look at `useThrottle()`. + If you want a non-debouncing and non-throttling version, take a look at `useTimeout()`. Pending timeouts will also be cleared in case the component unmounts. diff --git a/docs/idle-callback-api/useIdleCallback.md b/docs/callbacks/useIdleCallback.md similarity index 96% rename from docs/idle-callback-api/useIdleCallback.md rename to docs/callbacks/useIdleCallback.md index 8b8d43f..2e986e2 100644 --- a/docs/idle-callback-api/useIdleCallback.md +++ b/docs/callbacks/useIdleCallback.md @@ -6,10 +6,11 @@ nav_order: 1 # useIdleCallback -Use this hook if you want to delay the execution of a function to a time when the browser is idle. +Use this hook if you want to delay the execution of a function to a time **when the browser is idle**. A good use-case for this might be _user tracking_, for instance. +{: .important } See [requestIdleCallback()](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback) to learn more about the concept of "idle callbacks". diff --git a/docs/timeouts-api/useThrottle.md b/docs/callbacks/useThrottle.md similarity index 89% rename from docs/timeouts-api/useThrottle.md rename to docs/callbacks/useThrottle.md index 1ccf873..26673aa 100644 --- a/docs/timeouts-api/useThrottle.md +++ b/docs/callbacks/useThrottle.md @@ -1,6 +1,6 @@ --- title: useThrottle -parent: Timeouts +parent: Callbacks / Functions nav_order: 3 --- @@ -12,8 +12,11 @@ Throttles a callback. Can be used for **rate-limiting** – the callback will only be invoked every X milliseconds (X being the set timeout), even if it was called more frequently. -Similar, [but different(!)][thr-vs-deb], is the `useDebounce()` hook, which blocks the invocation entirely until the function was -stopped being called for X milliseconds. +{: .note-title } +> Throttle vs. Debounce +> +> Similar, [but different(!)][thr-vs-deb], is the `useDebounce()` hook, which blocks the invocation entirely until the function was +> stopped being called for X milliseconds. By default, the throttled function will always be called immediately (`options.leading` is true by default) and then (`options.trailing` is true by default) also after every X milliseconds for consecutive calls. diff --git a/docs/timeouts-api/useTimeout.md b/docs/callbacks/useTimeout.md similarity index 97% rename from docs/timeouts-api/useTimeout.md rename to docs/callbacks/useTimeout.md index 1734eab..1b7b5a0 100644 --- a/docs/timeouts-api/useTimeout.md +++ b/docs/callbacks/useTimeout.md @@ -1,6 +1,6 @@ --- title: useTimeout -parent: Timeouts +parent: Callbacks / Functions nav_order: 2 --- @@ -17,6 +17,8 @@ If you want a throttling version, see `useThrottle()`. Pending timeouts will only(!) be cleared in case the component unmounts. +#### Alternatives + If you want to execute a timeout every time a certain value changes, `useTimeoutEffect` might be better suited. ## Example diff --git a/docs/idle-callback-api/index.md b/docs/effects/index.md similarity index 88% rename from docs/idle-callback-api/index.md rename to docs/effects/index.md index bcef61f..2ffa9ab 100644 --- a/docs/idle-callback-api/index.md +++ b/docs/effects/index.md @@ -1,11 +1,11 @@ --- layout: default -title: Idle Callbacks -nav_order: 5 +title: Effects +nav_order: 4 has_children: true --- -# Idle Callbacks +# Effects React hooks that wrap [window.requestIdleCallback()][idle-cb-mdn]. {: .fs-6 .fw-300 } diff --git a/docs/idle-callback-api/useIdleCallbackEffect.md b/docs/effects/useIdleCallbackEffect.md similarity index 98% rename from docs/idle-callback-api/useIdleCallbackEffect.md rename to docs/effects/useIdleCallbackEffect.md index 80ae2d6..de85b36 100644 --- a/docs/idle-callback-api/useIdleCallbackEffect.md +++ b/docs/effects/useIdleCallbackEffect.md @@ -1,6 +1,6 @@ --- title: useIdleCallbackEffect -parent: Idle Callbacks +parent: Effects nav_order: 2 --- diff --git a/docs/timeouts-api/useTimeoutEffect.md b/docs/effects/useTimeoutEffect.md similarity index 99% rename from docs/timeouts-api/useTimeoutEffect.md rename to docs/effects/useTimeoutEffect.md index 9b8643f..9031544 100644 --- a/docs/timeouts-api/useTimeoutEffect.md +++ b/docs/effects/useTimeoutEffect.md @@ -1,6 +1,6 @@ --- title: useTimeoutEffect -parent: Timeouts +parent: Effects nav_order: 1 --- diff --git a/docs/index.md b/docs/index.md index f797889..a36567c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -19,37 +19,48 @@ npm i react-timing-hooks yarn add react-timing-hooks ``` -**Note:** You have to install React `^16.8.0`, `^17.0.0` or `^18.0.0`, too, in order to use this package. +{: .note } +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. + +## Getting started + +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/). + +{: .important-title } +> Typescript +> +> This package is developed in Typescript, so **everything is typed out of the box**. You don't need to install types seperately. -## Overview +## Background In general all of these hooks are more or less wrappers for standard javascript functions. But since they can be quite a pain to handle in React components (leaks upon unmount etc.), I wrote this little package. There are currently hooks available for: -* setTimeout (useTimeout, useTimeoutEffect) -* setInterval (useInterval, useTimer, useClock) -* requestAnimationFrame (useAnimationFrame, useAnimationFrameLoop) -* requestIdleCallback (useIdleCallback, useIdleCallbackEffect) +* [setTimeout][timeout-mdn] (useTimeout, useTimeoutEffect, useThrottledState, ...) +* [setInterval][interval-mdn] (useInterval, useTimer, useClock, ...) +* [requestAnimationFrame][raf-mdn] (useAnimationFrame, useAnimationFrameLoop) +* [requestIdleCallback][idle-cb-mdn] (useIdleCallback, useIdleCallbackEffect) -The APIs of all hooks are documented on this page (see sidebar). They should be pretty straight forward, but feel free +**All hooks are documented on this page** (see sidebar). They should be pretty straight forward to use, but feel free to add an issue on GitHub if you have any ideas for improvement. -### Typescript +{: .note-title } +> Package size / Treeshaking +> +> This package is extremely small already (see [here](https://bundlephobia.com/result?p=react-timing-hooks)), but your bundle +> size will be even less affected by this package, because it's completely **tree-shakable**, i.e. only hooks you actually use +> will be bundled into your app js. -This package is developed in Typescript, so everything is typed out of the box. You don't need to install types seperately. - -### Package size / Treeshaking +### Preventing leaks on unmount -This package is extremely small already (see [here](https://bundlephobia.com/result?p=react-timing-hooks)), but your bundle -size will be even less affected by this package, because it's completely **tree-shakable**, i.e. only hooks you actually use -will be bundled into your app js. +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. -### Preventing leaks on unmount +What you what normally do is to write clean-up code to manually clear pending timeouts/intervals in your React components. +**With React Timing Hooks you don't have to do that.** -Normally, timeouts, intervals etc. would have to be cleaned up manually if used inside a React component. -With React Timing Hooks you don't have to do that. +#### Example For example: You might have a timeout that runs under a certain condition. In this case a cleanup has to be done in a separate `useEffect` call that cleans everything up (but only on unmount). @@ -108,7 +119,7 @@ In this case `react-timing-hooks` automatically took care of cleaning up the tim ### Memoization -You **don't have to worry about memoization** of your callbacks (by using `useCallback`) for example. React Timing Hooks is taking care of that for you. So even if you pass a simple inline arrow function to one of these hooks, the return value (if there is one) will not change on every render but instead stay the same (i.e. it will be memoized). +Memoization is important if you depend on callbacks in your hook dependency arrays. You **don't have to worry about memoization** of your callbacks (by wrapping stuff in `useCallback` for example). React Timing Hooks is taking care of that for you. So even if you pass a simple inline arrow function to one of these hooks, the return value (if there is one) will not change on every render but instead stay the same (i.e. it will be memoized). This means something like this is safe to do: @@ -122,3 +133,7 @@ useEffect(() => { }, [foo, onFooChange]) ``` +[interval-mdn]: https://developer.mozilla.org/en-US/docs/Web/API/setInterval +[timeout-mdn]: https://developer.mozilla.org/en-US/docs/Web/API/setTimeout +[idle-cb-mdn]: https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback +[raf-mdn]: https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame \ No newline at end of file diff --git a/docs/intervals-api/index.md b/docs/intervals-api/index.md deleted file mode 100644 index a0266d9..0000000 --- a/docs/intervals-api/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -layout: default -title: Intervals -nav_order: 3 -has_children: true ---- - -# Intervals - -React hooks that wrap [setInterval()][interval-mdn] or build on top of it. -{: .fs-6 .fw-300 } - -The intervals that these hooks create can be **paused, resumed, stopped and re-started**. -Additionally, they will automatically take care of clearing any intervals that you set if -the component unmounts for example. - -Please note that most of these hooks do not start immediately start on mount, but rather have to be -started manually via the returned `start()` function. You can opt-in to starting on mount, though, by -using the option `startOnMount = true`. - -[interval-mdn]: https://developer.mozilla.org/en-US/docs/Web/API/setInterval - diff --git a/docs/list-of-all-hooks/index.md b/docs/list-of-all-hooks/index.md index c1b3b47..e2a337a 100644 --- a/docs/list-of-all-hooks/index.md +++ b/docs/list-of-all-hooks/index.md @@ -1,41 +1,55 @@ --- layout: default title: List of all hooks -nav_order: 7 +nav_order: 6 has_children: false --- -# List of all hooks +# A list of all hooks In case you wonder where to find them. {: .fs-6 .fw-300 } -## Base Vanilla JS wrappers +## By Javascript function + +#### Set Timeout | [MDN][timeout-mdn] - [useTimeout](/react-timing-hooks/timeouts-api/useTimeout.html) - [useTimeoutEffect](/react-timing-hooks/timeouts-api/useTimeoutEffect.html) + +#### Set Interval | [MDN][interval-mdn] - [useInterval](/react-timing-hooks/intervals-api/useInterval.html) -- [useIdleCallback](/react-timing-hooks/idle-callback-api/useIdleCallback.html) + +#### Request Idle Callback | [MDN][idle-cb-mdn] +- [useIdleCallback](/react-timing-hooks/idle-callback-api/useIdleCallback.html). - [useIdleCallbackEffect](/react-timing-hooks/idle-callback-api/useIdleCallbackEffect.html) + +#### Request Animation Frame | [MDN][raf-mdn] - [useAnimationFrame](/react-timing-hooks/animation-api/useAnimationFrame.html) - [useAnimationFrameLoop](/react-timing-hooks/animation-api/useAnimationFrameLoop.html) -## By Use Case +## By use case -### Rate Limiting, Throttling, Debouncing +#### Rate limiting / throttling / debouncing - [useThrottledState](/react-timing-hooks/general-utility/useThrottledState.html) - tame rapid firing state updates, reducing the number of React updates - [useThrottle](/react-timing-hooks/timeouts-api/useThrottle.html) - [useDebounce](/react-timing-hooks/timeouts-api/useDebounce.html) -### Counting +#### Reactive counters & timers - [useCounter](/react-timing-hooks/intervals-api/useCounter.html) - a reactive, customizable counter - [useTimer](/react-timing-hooks/intervals-api/useTimer.html) - a timer - [useCountdown](/react-timing-hooks/intervals-api/useCountdown.html) - a countdown (ends automatically) -### Rendering +#### GFX / animation / rendering - [useAnimationFrameLoop](/react-timing-hooks/animation-api/useAnimationFrameLoop.html) - for animations, rendering etc. -### Time +#### Time - [useClock](/react-timing-hooks/intervals-api/useClock.html) - displays a real-time digital clock -### Tracking +#### Tracking - [useIdleCallback](/react-timing-hooks/idle-callback-api/useIdleCallback.html)** + + +[interval-mdn]: https://developer.mozilla.org/en-US/docs/Web/API/setInterval +[timeout-mdn]: https://developer.mozilla.org/en-US/docs/Web/API/setTimeout +[idle-cb-mdn]: https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback +[raf-mdn]: https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame \ No newline at end of file diff --git a/docs/loops-and-intervals/index.md b/docs/loops-and-intervals/index.md new file mode 100644 index 0000000..bfb4381 --- /dev/null +++ b/docs/loops-and-intervals/index.md @@ -0,0 +1,22 @@ +--- +layout: default +title: Loops & Intervals +nav_order: 2 +has_children: true +--- + +# Loops and Intervals + +React hooks for calling functions at a regular interval. +{: .fs-6 .fw-300 } + +Many of these hooks are built upon [setInterval()][interval-mdn]. + +The intervals that these hooks create can be **paused, resumed, stopped and re-started**. Counters can also be **reset**. +Additionally, these hooks will automatically take care of clearing any pending intervals if a component unmounts too early for example. + +{: .note } +Most of these hooks **do not automatically start** on mount, but rather have to be started manually via the returned `start()` function. However, you can start automatically by setting `options.startOnMount = true`. + +[interval-mdn]: https://developer.mozilla.org/en-US/docs/Web/API/setInterval + diff --git a/docs/animation-api/useAnimationFrameLoop.md b/docs/loops-and-intervals/useAnimationFrameLoop.md similarity index 91% rename from docs/animation-api/useAnimationFrameLoop.md rename to docs/loops-and-intervals/useAnimationFrameLoop.md index 98f959f..41e1ad1 100644 --- a/docs/animation-api/useAnimationFrameLoop.md +++ b/docs/loops-and-intervals/useAnimationFrameLoop.md @@ -1,7 +1,7 @@ --- title: useAnimationFrameLoop -parent: Animation -nav_order: 1 +parent: Loops & Intervals +nav_order: 3 --- # useAnimationFrameLoop @@ -14,15 +14,18 @@ Pausing will make the hook still running on an animation frame loop, but without Stopping will completely halt it and cancel any open animation frame requests, just as if you would unmount it. If **performance** is important to you, you should stop the loop instead of pausing it whenever possible. -**Note**: By default, the loop is _stopped_ on mount and has to be started manually. If you want the loop to start immediately on mount, use `options.startOnMount`. +{: .note } +By default, the loop is _stopped_ on mount and has to be started manually. If you want the loop to start immediately on mount, use `options.startOnMount`. The browser will call your function approximately 60 times a second (60 FPS) if the performance of your app allows it. + +{: .important } See [window.requestAnimationFrame()](https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame) to learn more about the inner workings of "animation frames". ## Example -```typescript jsx +```javascript import { useRef } from 'react' import { useAnimationFrameLoop } from 'react-timing-hooks' diff --git a/docs/intervals-api/useClock.md b/docs/loops-and-intervals/useClock.md similarity index 98% rename from docs/intervals-api/useClock.md rename to docs/loops-and-intervals/useClock.md index 1f37d23..cb1bae7 100644 --- a/docs/intervals-api/useClock.md +++ b/docs/loops-and-intervals/useClock.md @@ -1,7 +1,7 @@ --- title: useClock -parent: Intervals -nav_order: 5 +parent: Loops & Intervals +nav_order: 6 --- # useClock diff --git a/docs/intervals-api/useCountdown.md b/docs/loops-and-intervals/useCountdown.md similarity index 87% rename from docs/intervals-api/useCountdown.md rename to docs/loops-and-intervals/useCountdown.md index 98a89a3..4856ad9 100644 --- a/docs/intervals-api/useCountdown.md +++ b/docs/loops-and-intervals/useCountdown.md @@ -1,7 +1,7 @@ --- title: useCountdown -parent: Intervals -nav_order: 3 +parent: Loops & Intervals +nav_order: 5 --- # useCountdown @@ -14,12 +14,15 @@ The hook will stop its interval automatically when it reaches the end. The event callback `options.onEnd()` will be called as soon as the end value is reached. -**Note**: By default, the countdown is _stopped_ on mount and has to be started manually. -If you want the countdown to start immediately on mount, use `options.startOnMount`. +{: .note } +By default, the countdown is _stopped_ on mount and has to be started manually. +If you want the countdown to start automatically on mount, use `options.startOnMount`. -This hook is similar to [useTimer()](/react-timing-hooks/intervals-api/useTimer.html) which counts _up_ every second and does not have an end value. +This hook is similar to [useTimer()](/react-timing-hooks/intervals-api/useTimer.html) which counts _up_ every second, but does not have an end value. If you need a countdown that count's upwards, you can use `options.stepSize` and change it to `1` or higher. +#### Alternatives + For a more freedom/versatility, you can use [useCounter()](/react-timing-hooks/intervals-api/useCounter.html). ## Example diff --git a/docs/intervals-api/useCounter.md b/docs/loops-and-intervals/useCounter.md similarity index 89% rename from docs/intervals-api/useCounter.md rename to docs/loops-and-intervals/useCounter.md index 3660758..5359241 100644 --- a/docs/intervals-api/useCounter.md +++ b/docs/loops-and-intervals/useCounter.md @@ -1,6 +1,6 @@ --- title: useCounter -parent: Intervals +parent: Loops & Intervals nav_order: 2 --- @@ -10,11 +10,15 @@ Use this hook if you want to have a **customizable counter** that changes a valu certain amount (`settings.stepSize`) every x milliseconds (`settings.interval`). A start value (`settings.start`) can also be defined. -**Note**: By default, the counter is _stopped_ on mount and has to be started manually. -If you want the counter to start immediately on mount, use `settings.startOnMount`. +{: .note } +By default, the counter is _stopped_ on mount and has to be started manually. +If you want the counter to start automatically on mount, use `settings.startOnMount`. -Stopping the counter will also reset the timer value to it's initial value per default. -However, this can be changed via `settings.resetOnStop`. +Stopping the counter will also **reset the counter** to it's initial start-value per default. +However, this can be changed via `settings.resetOnStop`. You can manually reset it via the returned +`reset()` control-function. + +#### Alternatives If you want a counter that counts up by 1 every second, you can use the [useTimer()](/react-timing-hooks/intervals-api/useTimer.html) hook. diff --git a/docs/intervals-api/useInterval.md b/docs/loops-and-intervals/useInterval.md similarity index 89% rename from docs/intervals-api/useInterval.md rename to docs/loops-and-intervals/useInterval.md index c6ef84f..2c603df 100644 --- a/docs/intervals-api/useInterval.md +++ b/docs/loops-and-intervals/useInterval.md @@ -1,6 +1,6 @@ --- title: useInterval -parent: Intervals +parent: Loops & Intervals nav_order: 1 --- @@ -9,14 +9,20 @@ nav_order: 1 A react wrapper for [setInterval](https://developer.mozilla.org/en-US/docs/Web/API/setInterval) – no leaks on unmount! {: .fs-6 .fw-300 } -This hook allows you to do certain actions at a regular interval, i.e. **loops**. -It is a react-wrapper for the native javascript function `setInterval`. +This hook allows you to do certain actions at a regular interval, a.k.a. *loops*. +It is a React-wrapper for the native Javascript function [`setInterval`](https://developer.mozilla.org/en-US/docs/Web/API/setInterval). In addition to the standard Javascript API, the returned callbacks allow you to **pause, resume, stop and start** the interval, too. -**Note**: By default, the interval is _stopped_ on mount and has to be started manually. If you want the interval to start immediately on mount, use `options.startOnMount`. +{: .note } +By default, the interval is _stopped_ on mount and has to be started manually. If you want the interval to start automatically on mount, use `options.startOnMount`. -You can also stop the interval or start the interval in a stopped state by setting a delay value of `null`. +{: .important-title } +> Good to know +> +> Intervals also stop if you set the `delay` argument to `null`. + +#### Alternatives If you want to loop very fast – maybe because you want to animate something – you might want to use [useAnimationFrameLoop()](/react-timing-hooks/animation-api/useAnimationFrameLoop.html) instead which yields better performance in these cases. @@ -25,7 +31,7 @@ If you only want to increase or decrease a numeric value in a regular interval, take a look at [useCounter()](/react-timing-hooks/intervals-api/useCounter.html). -## Example +## Examples ### Simple interval that starts immediately on mount diff --git a/docs/intervals-api/useTimer.md b/docs/loops-and-intervals/useTimer.md similarity index 72% rename from docs/intervals-api/useTimer.md rename to docs/loops-and-intervals/useTimer.md index 95b5868..fde5d53 100644 --- a/docs/intervals-api/useTimer.md +++ b/docs/loops-and-intervals/useTimer.md @@ -1,6 +1,6 @@ --- title: useTimer -parent: Intervals +parent: Loops & Intervals nav_order: 4 --- @@ -8,12 +8,16 @@ nav_order: 4 Use this hook if you want to create a timer, i.e. a reactive number that is **incremented every second**. -**Note**: By default, the timer is _stopped_ on mount and has to be started manually. If you want the timer to start immediately on mount, use `settings.startOnMount`. +{: .note } +By default, the timer is _stopped_ on mount and has to be started manually. If you want the timer to start immediately on mount, use `settings.startOnMount`. -Stopping the timer will also reset the timer value to it's initial value per default. However, this can be changed via `settings.resetOnStop`. +Stopping the timer will also reset the timer to it's initial value per default. However, this can be changed via `settings.resetOnStop`. You can manually reset it via the returned `reset()` control-function. -For a more versatile hook, look at [useCounter()](/react-timing-hooks/intervals-api/useCounter.html). -For a "reverse timer", see [useCountdown()](/react-timing-hooks/intervals-api/useCountdown.html). + +#### Alternatives + +- For a more versatile hook, look at [useCounter()](/react-timing-hooks/intervals-api/useCounter.html). +- For a "reverse timer", see [useCountdown()](/react-timing-hooks/intervals-api/useCountdown.html). ## Example diff --git a/docs/migrations/index.md b/docs/migrations/index.md index 54b2ffd..36c5223 100644 --- a/docs/migrations/index.md +++ b/docs/migrations/index.md @@ -1,7 +1,7 @@ --- layout: default title: Migrations -nav_order: 8 +nav_order: 7 has_children: true --- diff --git a/docs/general-utility/index.md b/docs/state/index.md similarity index 55% rename from docs/general-utility/index.md rename to docs/state/index.md index ea3f7c6..cfc8e05 100644 --- a/docs/general-utility/index.md +++ b/docs/state/index.md @@ -1,13 +1,13 @@ --- layout: default -title: General Utility -nav_order: 6 +title: State +nav_order: 5 has_children: true --- -# General Utility +# State -React hooks that provide solutions for common tasks or improve quality-of-life. +React hooks that function similar to `useState()`. {: .fs-6 .fw-300 } These hooks are implemented using one or many of the low-level hooks included in `react-timing-hooks`. diff --git a/docs/general-utility/useThrottledState.md b/docs/state/useThrottledState.md similarity index 81% rename from docs/general-utility/useThrottledState.md rename to docs/state/useThrottledState.md index b0e3d4b..775d7e2 100644 --- a/docs/general-utility/useThrottledState.md +++ b/docs/state/useThrottledState.md @@ -9,15 +9,20 @@ nav_order: 1 Manage rapidly changing state in your application without producing too many updates/re-renders! {: .fs-6 .fw-300 } -This hook allows you to throttle state updates, which in turn can throttle re-rerenders and/or effect +This hook is based on a combination of `useThrottle()` && React's `useState()`. + +It allows you to throttle state updates, which in turn can reduce the amount of re-rerenders and/or effect updates. If you have a component, service, or interval that rapidly fires state updates, this hook allows you to do that without forcing an _actual_ update within React which would trigger a re-render. This is also helpful if you have a `useEffect()` hook that you don't want to run too often. -Keep in mind: This means that not every update is necessarily immediately reflected in the -state variable, it might only be _queued_ for an update. But do not worry: no updates will be lost. -Eventually the latest call to the `setState` method will always be processed and cause an actual update. +{: .note-title } +> Keep in mind +> +> This means that not every update is necessarily immediately reflected in the +> state variable, it might only be _queued_ for an update. But do not worry: no updates will be lost. +> Eventually the latest call to the `setState` method will always be processed and cause an actual update. ## Example diff --git a/docs/timeouts-api/index.md b/docs/timeouts-api/index.md deleted file mode 100644 index a11f945..0000000 --- a/docs/timeouts-api/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -layout: default -title: Timeouts -nav_order: 2 -has_children: true ---- - -# Timeouts - -React hooks that wrap [setTimeout()][timeout-mdn]. -{: .fs-6 .fw-300 } - -This is a collection of timeout based hooks. - -For rate-limiting use `useThrottle()` or `useDebounce()`. For pure timeouts use `useTimeout()` or `useTimeoutEffect()`. - -All of these hooks will automatically take care of clearing any pending timeouts that you set if the component unmounts for example. - -[timeout-mdn]: https://developer.mozilla.org/en-US/docs/Web/API/setTimeout