React-Hooks#

A collection of React Hooks.

tl;dr#

• Install by executing npm install @wojtekmaj/react-hooks or yarn add @wojtekmaj/react-hooks.
• Import by adding import { useTick } from '@wojtekmaj/react-hooks'.
• Do stuff with it!

  const tick = useTick();
  

Server-side rendering#

All hooks from this package support SSR. Some hooks use browser-only APIs, e.g. useCurrentPosition. Such hooks, if they are supposed to return a value, will return null instead.

User guide#

Table of contents#

Browser state and capabilities#

• useCurrentPosition
• useDeviceOrientation
• useDocumentVisibility
• useOnLine
• usePermissionState

Events and observers#

• useEventListener
• useIntersectionObserver
• useMutationObserver
• useResizeObserver

Media queries and preferences#

• useForcedColors
• useMatchMedia
• usePrefersColorScheme
• usePrefersColorSchemeDark
• usePrefersColorSchemeLight
• usePrefersContrast
• usePrefersReducedMotion
• usePrefersReducedTransparency

Scrolling and viewport#

• useScrollLeft
• useScrollLeftDirection
• useScrollLeftPercent
• useScrollTop
• useScrollTopDirection
• useScrollTopPercent
• useWindowHeight
• useWindowSize
• useWindowWidth

State and storage#

• useDebouncedState
• useDebouncedValue
• useLocalStorage
• useSessionStorage
• useToggle

Timing and effects#

• useDebouncedEffect
• useSetInterval
• useSetTimeout
• useTick

Browser state and capabilities#

useCurrentPosition#

Returns current position from Geolocation API.

Sample usage#

import { useCurrentPosition } from '@wojtekmaj/react-hooks';

useCurrentPosition(); // { latitude: 0, longitude: 0 }

useDeviceOrientation#

Returns the device's current physical orientation.

On iOS and iPadOS, permission to access device orientation must be requested from a user interaction before orientation events are emitted. If DeviceOrientationEvent.requestPermission() is available, call it from a click or tap handler.

Sample usage#

import { useDeviceOrientation } from '@wojtekmaj/react-hooks';

const orientation = useDeviceOrientation(); // { absolute: false, alpha: 0, beta: 0, gamma: 0 }

useDocumentVisibility#

Returns the document's current visibility state.

Sample usage#

import { useDocumentVisibility } from '@wojtekmaj/react-hooks';

const visibilityState = useDocumentVisibility(); // 'visible' / 'hidden'

useOnLine#

Returns the online status of the browser.

Sample usage#

import { useOnLine } from '@wojtekmaj/react-hooks';

const onLine = useOnLine(); // true

usePermissionState#

Returns permission state given permission name.

Sample usage#

import { usePermissionState } from '@wojtekmaj/react-hooks';

const state = usePermissionState({ name: 'geolocation' }); // 'granted'

Events and observers#

useEventListener#

Adds event listener to a given element.

Sample usage#

import { useEventListener } from '@wojtekmaj/react-hooks';

useEventListener(element, 'click', onClick);

useIntersectionObserver#

Observes a given element using IntersectionObserver.

Sample usage#

import { useIntersectionObserver } from '@wojtekmaj/react-hooks';

useIntersectionObserver(element, config, onIntersectionChange);

useMutationObserver#

Observes a given element using MutationObserver.

Sample usage#

import { useMutationObserver } from '@wojtekmaj/react-hooks';

useMutationObserver(element, config, onMutation);

useResizeObserver#

Observes a given element using ResizeObserver.

Sample usage#

import { useResizeObserver } from '@wojtekmaj/react-hooks';

useResizeObserver(element, config, onResize);

Media queries and preferences#

useForcedColors#

Returns a flag indicating whether the forced-colors media feature is active.

Sample usage#

import { useForcedColors } from '@wojtekmaj/react-hooks';

const forcedColors = useForcedColors(); // true

useMatchMedia#

Returns a flag which determines if the document matches the given media query string.

Sample usage#

import { useMatchMedia } from '@wojtekmaj/react-hooks';

const isDesktop = useMatchMedia('screen and (min-width: 1024px)'); // true / false

usePrefersColorScheme#

Returns the color scheme preference indicated by the prefers-color-scheme media feature.

Sample usage#

import { usePrefersColorScheme } from '@wojtekmaj/react-hooks';

const prefersColorScheme = usePrefersColorScheme(); // 'dark' / 'light'

usePrefersColorSchemeDark#

Returns a flag indicating whether the prefers-color-scheme media feature is dark.

Sample usage#

import { usePrefersColorSchemeDark } from '@wojtekmaj/react-hooks';

const prefersColorSchemeDark = usePrefersColorSchemeDark(); // true

usePrefersColorSchemeLight#

Returns a flag indicating whether the prefers-color-scheme media feature is light.

Sample usage#

import { usePrefersColorSchemeLight } from '@wojtekmaj/react-hooks';

const prefersColorSchemeLight = usePrefersColorSchemeLight(); // true

usePrefersContrast#

Returns the contrast preference indicated by the prefers-contrast media feature.

Sample usage#

import { usePrefersContrast } from '@wojtekmaj/react-hooks';

const prefersContrast = usePrefersContrast(); // 'more' / 'less' / 'custom' / 'no-preference'

usePrefersReducedMotion#

Returns a flag indicating whether the prefers-reduced-motion media feature is reduce.

Sample usage#

import { usePrefersReducedMotion } from '@wojtekmaj/react-hooks';

const prefersReducedMotion = usePrefersReducedMotion(); // true

usePrefersReducedTransparency#

Returns a flag indicating whether the prefers-reduced-transparency media feature is reduce.

Sample usage#

import { usePrefersReducedTransparency } from '@wojtekmaj/react-hooks';

const prefersReducedTransparency = usePrefersReducedTransparency(); // true

Scrolling and viewport#

useScrollLeft#

Returns current scroll left position in pixels.

Sample usage#

import { useScrollLeft } from '@wojtekmaj/react-hooks';

const scrollLeft = useScrollLeft(); // 0

useScrollLeftDirection#

Returns current scroll left direction.

Sample usage#

import { useScrollLeftDirection } from '@wojtekmaj/react-hooks';

const scrollLeftDirection = useScrollLeftDirection(); // 'still' / 'left' / 'right'

useScrollLeftPercent#

Returns current scroll left position in percentage.

Sample usage#

import { useScrollLeftPercent } from '@wojtekmaj/react-hooks';

const scrollLeftPercent = useScrollLeftPercent(); // 0.5

useScrollTop#

Returns current scroll top position in pixels.

Sample usage#

import { useScrollTop } from '@wojtekmaj/react-hooks';

const scrollTop = useScrollTop(); // 0

useScrollTopDirection#

Returns current scroll top direction.

Sample usage#

import { useScrollTopDirection } from '@wojtekmaj/react-hooks';

const scrollTopDirection = useScrollTopDirection(); // 'still' / 'up' / 'down'

useScrollTopPercent#

Returns current scroll top position in percentage.

Sample usage#

import { useScrollTopPercent } from '@wojtekmaj/react-hooks';

const scrollTopPercent = useScrollTopPercent(); // 0.5

useWindowHeight#

Returns the interior height of the window in pixels.

Sample usage#

import { useWindowHeight } from '@wojtekmaj/react-hooks';

const windowWidth = useWindowHeight(); // 900

useWindowSize#

Returns the interior width and height of the window in pixels.

Sample usage#

import { useWindowSize } from '@wojtekmaj/react-hooks';

const windowSize = useWindowSize(); // { width: 1440, height: 900 }

useWindowWidth#

Returns the interior width of the window in pixels.

Sample usage#

import { useWindowWidth } from '@wojtekmaj/react-hooks';

const windowWidth = useWindowWidth(); // 1440

State and storage#

useDebouncedState#

Returns a debounced state and a function to update it.

Sample usage#

import { useDebouncedState } from '@wojtekmaj/react-hooks';

const [value, setValue] = useDebouncedState('initialState', 1000); // ['initialState', Function]

useDebouncedValue#

Returns a debounced value.

Sample usage#

import { useDebouncedValue } from '@wojtekmaj/react-hooks';

const debouncedValue = useDebouncedValue(value, 1000); // This value will be updated after 1 second of value not changing.

useLocalStorage#

Returns a stateful value synchronized with localStorage, and a function to update it.

Sample usage#

import { useLocalStorage } from '@wojtekmaj/react-hooks';

const [value, setValue] = useLocalStorage('myKey', 'initialState'); // ['initialState', Function]

useSessionStorage#

Returns a stateful value synchronized with sessionStorage, and a function to update it.

Sample usage#

import { useSessionStorage } from '@wojtekmaj/react-hooks';

const [value, setValue] = useSessionStorage('myKey', 'initialState'); // ['initialState', Function]

useToggle#

Returns a flag and a function to toggle it.

Sample usage#

import { useToggle } from '@wojtekmaj/react-hooks';

const [value, toggleValue] = useToggle(); // [false, Function]

Timing and effects#

useDebouncedEffect#

Runs a given effect after a given delay.

Sample usage#

import { useDebouncedEffect } from '@wojtekmaj/react-hooks';

useDebouncedEffect(
  () => {
    // This will run after 1 second of value not changing.
  },
  [value],
  1000,
);

useSetInterval#

Runs a given function every n milliseconds.

Sample usage#

import { useSetInterval } from '@wojtekmaj/react-hooks';

useSetInterval(fn, 1000);

useSetTimeout#

Runs a given function after n milliseconds.

Sample usage#

import { useSetTimeout } from '@wojtekmaj/react-hooks';

useSetTimeout(fn, 1000);

useTick#

Counts from 0, increasing the number returned every n milliseconds.

Sample usage#

import { useTick } from '@wojtekmaj/react-hooks';

const tick = useTick(1000); // 0 … 🕐 … 1 … 🕑 … 2 …

License#

The MIT License.

Author#

Wojciech Maj