14 | I have noticed that many of the hooks I have created and shared across projects involve callbacks, references, events, and dealing with the 15 | component lifecycle.
16 | Therefore, I have created `beautiful-react-hooks`, a collection of useful [React hooks](https://beta.reactjs.org/reference/react) that may 17 | help other developers speed up their development process.
18 | Moreover, I have strived to create a concise and practical API that emphasizes code readability, while keeping the learning curve as low as 19 | possible, making it suitable for larger teams to use and share 20 | 21 | ## ☕️ Features 22 | 23 | * Concise API 24 | * Small and lightweight 25 | * Easy to learn 26 | 27 | ## Basic usage 28 | 29 | importing a hooks is as easy as the following straightforward line: 30 | 31 | ```ts static 32 | import useSomeHook from 'beautiful-react-hooks/useSomeHook' 33 | ``` 34 | 35 | ## Peer dependencies 36 | 37 | Some hooks are built using third-party libraries (such as rxjs, react-router-dom, redux). As a result, you will see these libraries listed 38 | as peer dependencies.\ 39 | Unless you are using these hooks directly, you need not install these dependencies. 40 | -------------------------------------------------------------------------------- /docs/useDarkMode.md: -------------------------------------------------------------------------------- 1 | # useDarkMode 2 | 3 | A hook that manages all the necessary operations to incorporate a toggle switch for dark and light modes on your website 4 | 5 | ### 💡 Why? 6 | 7 | - Keep information about dark/light mode consistent and in sync across sessions using localStorage 8 | - Return the methods that allows you to change into dark/light mode 9 | - Safely read information about the dark/light mode from user's operating system using `prefers-color-scheme` 10 | 11 | ### Basic Usage: 12 | 13 | ```jsx harmony 14 | import { Typography, Tag, Button } from 'antd'; 15 | 16 | import useDarkMode from 'beautiful-react-hooks/useDarkMode'; 17 | 18 | const UseDarkModeExample = () => { 19 | const { toggle, enable, disable, isDarkMode } = useDarkMode(); 20 | 21 | const Actions = [ 22 | , 25 | , 28 | 31 | ] 32 | 33 | return ( 34 |
4 | It is intended as a shortcut to [useSwipe](./useSwipe.md). 5 | -------------------------------------------------------------------------------- /docs/useIsFirstRender.md: -------------------------------------------------------------------------------- 1 | # useIsFirstRender 2 | 3 | A hook that returns a boolean value indicating whether it's the first render or not. 4 | 5 | This hook can be used to conditionally execute logic or render components based on whether it's the first time the component is being 6 | rendered or if it's being re-rendered due to a state or prop change. 7 | 8 | ### 💡 Why? 9 | 10 | - A useful tool for managing component rendering behavior and enables you to write more efficient and flexible code 11 | 12 | ### Basic Usage: 13 | 14 | ```jsx harmony 15 | import { useState, useCallback } from 'react'; 16 | import { Button, Typography } from 'antd'; 17 | import useIsFirstRender from 'beautiful-react-hooks/useIsFirstRender'; 18 | 19 | const UseIsFirstRenderExample = () => { 20 | const [data, setData] = useState(0) 21 | const isFirstRender = useIsFirstRender(); 22 | 23 | const setNewDate = useCallback(() => setData(Date.now()), []); 24 | 25 | return ( 26 |
51 | * It also monitor the document changes to detect when it matches or stops matching the media query.
52 | * Returns the validity state of the given media query. 53 | * 54 | */ 55 | declare const useMediaQuery: (mediaQuery: string) => boolean; 56 | export default useMediaQuery; 57 | 58 | ``` 59 | -------------------------------------------------------------------------------- /docs/useMutableState.md: -------------------------------------------------------------------------------- 1 | # useMutableState 2 | 3 | This hook provides mutable states that trigger the component to re-render. It offers similar functionality to Svelte's reactivity, enabling 4 | developers to write more efficient and concise code. 5 | 6 | ### Why? 💡 7 | 8 | - Improves code streamlining by providing a reactive state that can be used to trigger a rerender 9 | 10 | ### Basic Usage: 11 | 12 | ```jsx harmony 13 | import { Typography, Space, Button, Tag } from 'antd'; 14 | import useMutableState from 'beautiful-react-hooks/useMutableState'; 15 | 16 | const TestComponent = () => { 17 | const counter = useMutableState({ value: 0 }); 18 | 19 | return ( 20 |
35 |
50 |
47 | Resize me
48 |
49 | {JSON.stringify(state, null, '\t')}
45 | -
34 | {voices.map(({ name, lang }) =>
Current value of 'foo' param is '{params.get('foo')}'
36 |Change the value of the foo param to see how this hook works
37 |4 | It is intended as a shortcut to [useSwipe](./useSwipe.md). 5 | -------------------------------------------------------------------------------- /docs/useViewportState.md: -------------------------------------------------------------------------------- 1 | # useViewportState 2 | 3 | A hook that returns relevant information on the current viewport state. 4 | 5 | It's built on top of [useWindowResize](./useWindowResize.md) and [useWindowScroll](./useWindowScroll.md). 6 | 7 | ### Why? 💡 8 | 9 | - takes care of adding the listener for the window resize event. 10 | - takes care of removing the listener when the component will unmount 11 | 12 | ### Basic Usage: 13 | 14 | ```jsx harmony 15 | import { useState } from 'react'; 16 | import { Typography, Tag } from 'antd'; 17 | import useViewportState from 'beautiful-react-hooks/useViewportState'; 18 | 19 | const WindowSizeReporter = () => { 20 | const { width, height, scrollX, scrollY } = useViewportState(); 21 | 22 | return ( 23 |
17 | 
18 |
19 | )
20 |
21 | LogoRenderer.propTypes = {
22 | classes: PropTypes.object.isRequired,
23 | children: PropTypes.node
24 | }
25 |
26 | export default Styled(styles)(LogoRenderer)
27 |
--------------------------------------------------------------------------------
/docs/utils/_EmptyComponent.js:
--------------------------------------------------------------------------------
1 | export default () => null;
2 |
--------------------------------------------------------------------------------
/docs/utils/_custom.css:
--------------------------------------------------------------------------------
1 | @import url('https://fonts.googleapis.com/css?family=Ubuntu:300,300i,400,400i,500,500i,700,700i&display=swap');
2 | @import '~antd/dist/reset.css';
3 |
4 | body {
5 | font-family: 'Ubuntu', sans-serif;
6 | }
7 |
--------------------------------------------------------------------------------
/docs/utils/_doc-logo.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/antonioru/beautiful-react-hooks/21399d635bd75679aac7d53821dd3e54c93d635c/docs/utils/_doc-logo.png
--------------------------------------------------------------------------------
/docs/utils/_setup.js:
--------------------------------------------------------------------------------
1 | const React = require('react')
2 | const { Card } = require('antd')
3 |
4 | const DisplayDemo = window.DisplayDemo = (props) => (
5 | React.createElement(Card, { bordered: true, hoverable: true, ...props }, props.children)
6 | )
7 |
--------------------------------------------------------------------------------
/docs/utils/_styleguidist.theme.js:
--------------------------------------------------------------------------------
1 | module.exports = {
2 | // https://github.com/styleguidist/react-styleguidist/blob/master/src/client/styles/theme.ts
3 | theme: {
4 | color: {
5 | base: '#2D3142',
6 | text: '#2D3142',
7 | link: '#1D6C8B',
8 | linkHover: '#317995'
9 | },
10 | baseColor: '#2D3142',
11 | fontFamily: {
12 | base: '"Ubuntu", "sans-serif", light',
13 | },
14 | },
15 | styles: {
16 | SectionHeading: {
17 | wrapper: {
18 | display: 'none',
19 | },
20 | },
21 | Code: {
22 | code: {
23 | fontFamily: '\'Ubuntu Mono\', sans-serif',
24 | backgroundColor: '#CF7A95',
25 | color: '#fff',
26 | fontWeight: '400',
27 | padding: '0 5px',
28 | },
29 | },
30 | Para: {
31 | para: {
32 | fontFamily: '\'Ubuntu\', sans-serif',
33 | },
34 | },
35 | StyleGuide: {
36 | sidebar: {
37 | border: 0,
38 | width: '16rem',
39 | background: 'white',
40 | boxShadow: '0 0 20px 0 rgba(20, 20, 20, 0.1)',
41 | },
42 | content: {
43 | maxWidth: '960px',
44 | },
45 | root: {
46 | background: '#FBFAF9',
47 | },
48 | hasSidebar: {
49 | paddingLeft: '16rem',
50 | }
51 | },
52 | Playground: {
53 | preview: {
54 | padding: 0,
55 | border: 'none',
56 | background: 'transparent',
57 | //borderRadius: '6px',
58 | // boxShadow: '0 0px 10px 0 rgba(93, 100, 148, 0.05)',
59 | },
60 | },
61 | },
62 | }
63 |
--------------------------------------------------------------------------------
/logo.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/antonioru/beautiful-react-hooks/21399d635bd75679aac7d53821dd3e54c93d635c/logo.png
--------------------------------------------------------------------------------
/scripts/commit-version.sh:
--------------------------------------------------------------------------------
1 | #!/bin/bash
2 |
3 | cd ..
4 | git add package.json
5 | git commit -m "chore(release): Updates package.json version to $1 [skip ci]"
6 | git push origin master
7 |
--------------------------------------------------------------------------------
/scripts/generate-doc-append-types.js:
--------------------------------------------------------------------------------
1 | const fs = require('fs/promises')
2 | const path = require('path')
3 | const { globSync } = require('glob')
4 |
5 | const docsPath = path.join(__dirname, '..', 'docs')
6 | const distPath = path.join(__dirname, '..', 'dist')
7 | const docFiles = globSync(`${docsPath}/*.md`)
8 | .map((file) => file.replace(`${docsPath}/`, '').replace('.md', ''))
9 | .filter((file) => file.startsWith('use'))
10 |
11 | docFiles.forEach(async (hook) => {
12 | const docPath = path.join(docsPath, `${hook}.md`)
13 | const typeFile = path.join(distPath, `${hook}.d.ts`)
14 |
15 | const declarations = await fs.readFile(typeFile, { encoding: 'utf8' })
16 | const document = await fs.readFile(docPath, { encoding: 'utf8' })
17 |
18 | if (document.match(//g)) {
19 | const cleared = emptyOldTypes(document).trim()
20 | const nextDocument = cleared.replace('', template(declarations)).trim()
21 |
22 | fs.writeFile(docPath, nextDocument, { encoding: 'utf8' }).then(() => {
23 | console.log(`Updated "${hook}" types`)
24 | })
25 | }
26 | })
27 |
28 | const template = (content) => `
29 | ### Types
30 |
31 | \`\`\`typescript static
32 | ${content}
33 | \`\`\`
34 |
35 | `
36 |
37 | const emptyOldTypes = (content) => {
38 | const regex = /[\s\S]*/g
39 |
40 | return `${content.replace(regex, '\n').replace(//g, '').trim()}
41 |
42 |
43 | `
44 | }
45 |
--------------------------------------------------------------------------------
/scripts/generate-exports.js:
--------------------------------------------------------------------------------
1 | 'use strict'
2 |
3 | const fs = require('fs')
4 | const path = require('path')
5 | const { globSync } = require('glob')
6 |
7 | const srcPath = path.join(__dirname, '..', 'src')
8 | const pkgPath = path.join(__dirname, '..', 'package.json')
9 |
10 | const srcFiles = globSync(`${srcPath}/*.ts`)
11 | .map((file) => file.replace(`${srcPath}/`, '').replace('.ts', ''))
12 | .filter((file) => file !== 'index')
13 |
14 | const exportsObj = srcFiles.reduce((acc, file) => ({
15 | ...acc,
16 | [`./${file}`]: {
17 | import: `./esm/${file}.js`,
18 | require: `./${file}.js`,
19 | types: `./${file}.d.ts`
20 | }
21 | }), {})
22 |
23 | const packageJsonText = fs.readFileSync(pkgPath)
24 | const packageJson = JSON.parse(packageJsonText)
25 |
26 | const nextPackageJson = { ...packageJson, exports: exportsObj }
27 |
28 | console.log('\nUPDATING EXPORTS: ', Object.keys(exportsObj))
29 |
30 | fs.writeFileSync(pkgPath, JSON.stringify(nextPackageJson, null, 2))
31 |
--------------------------------------------------------------------------------
/scripts/update-version.js:
--------------------------------------------------------------------------------
1 | 'use strict'
2 |
3 | const fs = require('fs')
4 | const path = require('path')
5 |
6 | const nextVersion = process.argv[2]
7 | const pkgPath = path.join(__dirname, '..', 'package.json')
8 |
9 | const packageJsonText = fs.readFileSync(pkgPath)
10 | const packageJson = JSON.parse(packageJsonText)
11 |
12 | const nextPackageJson = { ...packageJson, version: nextVersion }
13 |
14 | console.log('\nUPDATING PACKAGE JSON VERSION TO: ', nextVersion)
15 |
16 | fs.writeFileSync(pkgPath, JSON.stringify(nextPackageJson, null, 2))
17 |
--------------------------------------------------------------------------------
/src/factory/createHandlerSetter.ts:
--------------------------------------------------------------------------------
1 | import { type RefObject, useRef } from 'react'
2 | import { type CallbackSetter, type SomeCallback } from '../shared/types'
3 |
4 | /**
5 | * Returns an array where the first item is the [ref](https://reactjs.org/docs/hooks-reference.html#useref) to a
6 | * callback function and the second one is a reference to a function for can change the first ref.
7 | *
8 | * Although it looks quite similar to [useState](https://reactjs.org/docs/hooks-reference.html#usestate),
9 | * in this case the setter just makes sure the given callback is indeed a new function.
10 | * **Setting a callback ref does not force your component to re-render.**
11 | *
12 | * `createHandlerSetter` is meant to be used internally to abstracting other hooks.
13 | * Don't use this function to abstract hooks outside this library as it changes quite often
14 | */
15 | const createHandlerSetter = 14 | * So far, the supported methods are: `onChange`, invoked when the position changes and `onError`, invoked when 15 | * an error occur while retrieving the position.
16 | * The returned object also contains the `isSupported` boolean flag reporting whether the geolocation API is supported. 17 | */ 18 | const useGeolocationEvents = (options: PositionOptions = geoStandardOptions) => { 19 | const watchId = useRef
13 | * It also monitor the document changes to detect when it matches or stops matching the media query.
14 | * Returns the validity state of the given media query. 15 | * 16 | */ 17 | const useMediaQuery = (mediaQuery: string) => { 18 | if (!isClient || !isAPISupported('matchMedia')) { 19 | warnOnce(errorMessage) 20 | return false 21 | } 22 | 23 | const [isVerified, setIsVerified] = useState(!!window.matchMedia(mediaQuery).matches) 24 | 25 | useEffect(() => { 26 | const mediaQueryList = window.matchMedia(mediaQuery) 27 | const documentChangeHandler = () => { setIsVerified(!!mediaQueryList.matches) } 28 | 29 | try { 30 | mediaQueryList.addEventListener('change', documentChangeHandler) 31 | } catch (e) { 32 | // Safari isn't supporting mediaQueryList.addEventListener 33 | mediaQueryList.addListener(documentChangeHandler) 34 | } 35 | 36 | documentChangeHandler() 37 | return () => { 38 | try { 39 | mediaQueryList.removeEventListener('change', documentChangeHandler) 40 | } catch (e) { 41 | // Safari isn't supporting mediaQueryList.removeEventListener 42 | mediaQueryList.removeListener(documentChangeHandler) 43 | } 44 | } 45 | }, [mediaQuery]) 46 | 47 | return isVerified 48 | } 49 | 50 | export default useMediaQuery 51 | -------------------------------------------------------------------------------- /src/useMouse.ts: -------------------------------------------------------------------------------- 1 | import { type RefObject } from 'react' 2 | import useMouseEvents from './useMouseEvents' 3 | import useMouseState from './useMouseState' 4 | 5 | /** 6 | * Returns an array where the first item is the mouse state from the `useMouseState` hook and the second item 7 | * is the object of callback setters from the `useMouseEvents` hook. 8 | * It is intended as a shortcut to those hooks. 9 | */ 10 | const useMouse =
6 | * It accepts a DOM ref representing the events target.
7 | * If a target is not provided the events will be globally attached to the document object. 8 | *
9 | * ### Shall the `useMouseEvents` callbacks replace the standard mouse handler props? 10 | * 11 | * **They shall not!**
12 | * **useMouseEvents is meant to be used to abstract more complex hooks that need to control mouse**, for instance: 13 | * a drag n drop hook.
14 | * Using useMouseEvents handlers instead of the classic props approach it's just as bad as it sounds since you'll 15 | * lose the React SyntheticEvent performance boost.
16 | * If you were doing something like the following: 17 | */ 18 | const useMouseEvents =
7 | * It accepts a DOM ref representing the events target.
8 | * If a target is not provided the events will be globally attached to the document object. 9 | *
10 | * ### Shall the `useTouchEvents` callbacks replace the standard mouse handler props? 11 | * 12 | * **They shall not!**
13 | * **useTouchEvents is meant to be used to abstract more complex hooks that need to control mouse**, for instance: 14 | * a drag n drop hook.
15 | * Using useTouchEvents handlers instead of the classic props approach it's just as bad as it sounds since you'll 16 | * lose the React SyntheticEvent performance boost.
17 | * If you were doing something like the following: 18 | * 19 | */ 20 | const useTouchEvents =
{isSupported}
60 | }
61 |
62 | render(val: {state.value}
31 | }
32 |
33 | render({prev}
30 | } 31 | 32 | const { container, rerender } = render(