@gilbarbara/hooks

Useful React hooks.

Setup

npm i @gilbarbara/hooks

Hooks

| Name | Description | | ------------------------------------------------------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | useClickOutside | Handle clicks outside a specific DOM element. | | useEffectOnce | Run an effect only once. | | useElementSize | Get element dimensions using the ResizeObserver API. | | useFetch | Make a request with fetch. | | useIntersectionObserver | Detects the visibility of an element on the viewport using the IntersectionObserver API. | | useIsFirstRun | Detect if it is the first execution. | | useIsMounted | Check if the component is still mounted before changing the state. | | useIsomorphicLayoutEffect | Returns useLayoutEffect in the client or useEffect on the server. | | useLatest | Get a ref with the most recent value. | | useMediaQuery | Detect media query changes. | | useMergeRefs | Merge multiple refs into one. | | useMount | Run a function after the component is mounted. | | useRenderCount | Log how many times the component was rendered. | | useResizeObserver | Detect changes in an Element dimensions using the ResizeObserver API. | | useResponsive | Get responsive breakpoints. | | useScript | Create a script tag and append it to the document.body. | | useSingleton | Run the code just once before the render. | | useThrottle | Return a throttled function that only invokes fn once per every ms. | | useThrottleValue | Return a throttled value that only changes once per every ms. | | useUnmount | Run a function when the component unmounts. | | useWhyDidYouUpdate | Get which prop changes are causing a component to re-render. | | useWindowSize | Get the window dimensions. Updates on resize. |

API

useClickOutside

Handle clicks outside a specific DOM element.

import React from 'react';
import { useClickOutside } from '@gilbarbara/hooks';

function Component() {
  const ref = React.useRef<HTMLDivElement>(null);
  useClickOutside(ref, () => {
    console.log('clicked outside');
  });

  return (
    <div ref={ref}>
      <button type="submit">Send</button>
      <button type="button">Reset</button>
    </div>
  );
}

Reference

useClickOutside(ref: RefObject<HTMLElement>, callback: () => void): void

useEffectOnce

Run an effect only once.

import React from 'react';
import { useEffectOnce } from '@gilbarbara/hooks';

function Component() {
  const [value, setValue] = React.useState(0);

  useEffectOnce(() => {
    setValue(1);
  });

  return <div data-testid="main">{value}</div>;
}

Reference

useEffectOnce(effect: EffectCallback): void

useElementSize

Get element dimensions using the ResizeObserver API.
Returns an ElementSize object.

import React from 'react';
import { useElementSize } from '@gilbarbara/hooks';

function Component() {
  const ref = React.useRef<HTMLDivElement>(null);
  const dimensions = useElementSize(ref);

  return (
    <div ref={ref}>
      {JSON.stringify(dimensions, undefined, 2)}
    </div>
  );
}

Reference

interface ElementSize {
  height: number;
  innerHeight: number;
  innerWidth: number;
  width: number;
}

useElementSize<T extends Element>(
  target: RefObject<T> | T | null | string,
  debounce = 0,
): ElementSize;

This hook uses a ResizeObserver, so if you want to support legacy browsers, install the resize-observer-polyfill in your app.

useFetch

Make a request with fetch.
Returns an object with data, error, and status.

import React from 'react';
import { useFetch } from '@gilbarbara/hooks';

function Component() {
  const { data, error, status } = useFetch(
    'https://api.github.com/search/repositories?q=react&sort=stars',
    true // you can delay the request until something finishes
  );

  return (
    <div>
      {status === 'failure' && <p>{error?.toString()}</p>}
      {status === 'success' && <p>{data}</p>}
      {status === 'running' && <p>Loading</p>}
    </div>
  );
}

Reference

type FetchStatus = 'idle' | 'running' | 'success' | 'failure';

interface UseFetchOptions {
  headers?: PlainObject;
  method?: string;
  mode?: 'cors' | 'navigate' | 'no-cors' | 'same-origin';
  body?: BodyInit;
  type?: 'json' | 'urlencoded';
  url: string;
}

interface UseFetchResponse<T> {
  data?: T;
  error?: ResponseError;
  status: FetchStatus;
}

useFetch<T = unknown>(urlOrOptions: string | UseFetchOptions, wait = false): UseFetchResponse<T>;

useIntersectionObserver

Detects the visibility of an element on the viewport using the IntersectionObserver API.
Returns an IntersectionObserverEntry.

import React from 'react';
import { useIntersectionObserver } from '@gilbarbara/hooks';

function Component() {
  const ref = React.useRef<HTMLElement>(null);
  const { isIntersecting } = useIntersectionObserver(ref);

  return (
    <div>
      Some content...
      <div ref={ref}>{isIntersecting ? 'Visible' : 'Hidden'}
    </div>
  );
}

Reference

interface UseIntersectionObserverOptions extends IntersectionObserverInit {
  /**
   * Trigger the observer only once.
   */
  once?: boolean;
}

useIntersectionObserver<T extends Element>(
  target: RefObject<T> | T | null | string,
  options?: UseIntersectionObserverOptions,
): IntersectionObserverEntry

useIsFirstRun

Detect if it is the first execution.
Returns a boolean.

import React from 'react';
import { useIsFirstRun } from '@gilbarbara/hooks';

function Component() {
  const isFirstRun = useIsFirstRun();

  return <div>Is first render: {isFirstRun ? 'yes' : 'no'}</div>;
}

Reference

useIsFirstRun(): boolean;

useIsMounted

Check if the component is still mounted before changing the state.
Returns a () => boolean.

import React from 'react';
import { useIsMounted } from '@gilbarbara/hooks';

function Component() {
  const [data, setData] = React.useState('loading...');
  const isMounted = useIsMounted();

  React.useEffect(() => {
    asyncFn(`...`).then(() => {
      if (isMounted()) {
        setData('ready');
      }
    });
  }, [isMounted]);

  return <div>{data}</div>;
}

Reference

useIsMounted(): () => boolean;

useIsomorphicLayoutEffect

Returns useLayoutEffect in the client or useEffect on the server.

import React from 'react';
import { useIsomorphicLayoutEffect } from '@gilbarbara/hooks';

function Component() {
  useIsomorphicLayoutEffect(() => {
    // effect code
  }, []);

  return (
    <div>Something, something...</div>
  );
}

Reference

useIsomorphicLayoutEffect = canUseDOM ? useLayoutEffect : useEffect;

useLatest

Get a ref with the most recent value.
Returns a React.MutableRefObject with the same type as the input.

import React from 'react';
import { useLatest } from '@gilbarbara/hooks';

function Component({
  callback,
  element,
  name,
}: {
  callback: (e: Event) => void;
  element: HTMLElement;
  name: string;
}) {
  const callbackRef = useLatest(callback);
  const elementRef = useLatest(element);

  React.useEffect(() => {
    const currentElement = elementRef.current;
    const listen = (e: Event) => callbackRef.current(e);

    currentElement.addEventListener(name, listen);

    return () => currentElement.removeEventListener(name, listen);
  }, [name]);
  // The ESLint "react-hooks/exhaustive-deps" will warn about the refs
  // being required in dependencies, but the refs are stable, so they
  // won't trigger an update.

  return <div>Something, something...</div>;
}

Reference

useLatest<T>(value: T): React.MutableRefObject<T>;

useMediaQuery

Detect media query changes.
Returns a boolean.

import React from 'react';
import { useMediaQuery } from '@gilbarbara/hooks';

function Component() {
  const isLargeMobile = useMediaQuery('(min-width: 768px)');

  return (
    <div>
      {isLargeMobile ? 'Large' : 'Nope'}
    </div>
  );
}

Reference

useMediaQuery(query: string): boolean;

useMergeRefs

Merge multiple refs into one.
Returns a React.RefCallback.

import React from 'react';
import { useElementSize, useMergeRefs, useResizeObserver } from '@gilbarbara/hooks';

function Component() {
  const observerRef = React.useRef<HTMLDivElement>(null);
  const sizeRef = React.useRef<HTMLDivElement>(null);
  const ref = useMergeRefs(observerRef, sizeRef);
  const dimensions = useElementSize(sizeRef, 200);

  useResizeObserver(observerRef, entry => console.log(entry), 200);

  return (
    <div ref={ref}>
      <pre>{JSON.stringify(dimensions, null, 2)}</pre>
    </div>
  );
}

Reference

useMergeRefs<T>(...refs: Ref<T>[]): RefCallback<T>

useMount

Run a function after the component is mounted.

import React from 'react';
import { useMount } from '@gilbarbara/hooks';

function Component() {
  useMount(() => {
    pageView('Home');
  });

  return <div>Some content...</div>;
}

Reference

useMount(fn: () => void): void;

useRenderCount

Log how many times the component was rendered.
Useful to debug optimizations.

import React from 'react';
import { useRenderCount } from '@gilbarbara/hooks';

function Component() {
  useRenderCount()

  return (
    <div>Something</div>
  );
}

Reference

useRenderCount(name?: string);

useResizeObserver

Detect changes in an Element dimensions using the ResizeObserver API.
Returns a ResizeObserverEntry.

import React from 'react';
import { useResizeObserver } from '@gilbarbara/hooks';

function Component() {
  const ref = React.useRef<HTMLDivElement>(null);
  const entry = useResizeObserver(ref);

  console.log(entry?.contentRect.width);

  return <div ref={ref}>Some content...</div>;
}

Reference

useResizeObserver<T extends Element>(
  target: RefObject<T> | T | null | string,
  debounce: number = 0,
): ResizeObserverEntry

This hook uses a ResizeObserver, so if you want to support legacy browsers, install the resize-observer-polyfill in your app.

useResponsive

Get responsive breakpoints.
Returns a Responsive<T> object.

import React from 'react';
import { useResponsive } from '@gilbarbara/hooks';

function Component() {
  const { between, min, max, orientation, size } = useResponsive();

  return (
    <div>
      {max('sm', 'landscape') && <h1>Extra Small</h1>}
      {between('sm', 'lg') && <h1>Between small and large</h1>}
      <p>Extra Small {min('xs') ? '✔' : '✖️'}</p>
      <p>Small {min('sm') ? '✔' : '✖️'}</p>
      <p>Medium {min('md') ? '✔' : '✖️'}</p>
      <p>Large {min('lg') ? '✔' : '✖️'}</p>
      <p>Extra Large {min('xl') ? '✔' : '✖️'}</p>
      <footer>
        {size} - {orientation}
      </footer>
    </div>
  );
}

Reference

const defaultBreakpoints = { xs: 0, sm: 400, md: 768, lg: 1024, xl: 1280 };

interface Responsive<T> {
  between(min: keyof T, max: keyof T, andOrientation?: Orientation): boolean;
  min(breakpoint: keyof T, andOrientation?: Orientation): boolean;
  max(breakpoint: keyof T, andOrientation?: Orientation): boolean;
  orientation: Orientation;
  size: keyof T;
}

useResponsive<T extends Record<string, number> | typeof defaultBreakpoints>(
  breakpoints?: T,
  initialWidth = Infinity,
  initialHeight = Infinity
): Responsive<T>;

useScript

Create a script tag and append it to the document.body.
Returns an array with loaded and error properties.

import React from 'react';
import { useScript } from '@gilbarbara/hooks';

function Component() {
  const [loaded, error] = useScript(
    'https://maps.googleapis.com/maps/api/js?key=Ab2S23Bd&callback=initMap',
    'google-maps'
  );

  return (
    <div>
      {loaded && <div id="maps"/>}
      {error && <span>error</span>}
    </div>
  );
}

Reference

interface UseScriptOptions {
  async?: boolean;
  defer?: boolean;
  id?: string;
  type?: string;
}

useScript(src: string, idOrOptions: string | UseScriptOptions = {});

useSingleton

Run the code just once before the render.
Similar to constructors in classes.

import React from 'react';
import ReactDOM from 'react-dom';
import { useSingleton } from '@gilbarbara/hooks';

function Component() {
  const node = React.useRef<HTMLElement | null>(null);

  useSingleton(() => {
    // this code will only be executed once.
    node.current = document.createElement('div');
    node.current.id = 'MyPortal';

    document.body.appendChild(node.current);
  });

  return node.current ? ReactDOM.createPortal(<div>Portal</div>, node.current) : null;
}

Reference

useSingleton(cb: () => void);

useThrottle

Return a throttled function that only invokes fn once per every ms.
Unless you set the trailing option that will call it again when the timer runs out.

import React from 'react';
import { useThrottle } from '@gilbarbara/hooks';

function Component() {
  const updater = () => console.log('updated');
 	const throttledUpdater = useThrottle(updater, 500);

  return (
    <button type="button" onClick={throttledUpdater}>
      Update
    </button>
  );
}

Reference

interface UseThrottleOptions {
  leading?: boolean; // default: true
  trailing?: boolean; // default: false
}

useThrottle(fn: () => void, ms = 500, options?: UseThrottleOptions):

useThrottleValue

Return a throttled value that only changes once per every ms.
Unless you set the trailing option that will call it again when the timer runs out.

import React, { useCallback, useEffect, useState } from 'react';
import { useThrottleValue } from '@gilbarbara/hooks';

function Component() {
  const [text, setText] = useState('');
  const throttledText = useThrottleValue(text, 500, options);

  const updater = (value) => console.log(value);
  
  useEffect(() => {
    throttledText && updater(throttledText);
  }, [throttledText]);

  return (
    <div>
      <input type="text" onChange={e => setText(e.target.value)} />
      <p>Actual value: {text}</p>
      <p>Throttle value: {throttledText}</p>
    </div>
  );
}

Reference

interface UseThrottleOptions {
  leading?: boolean; // default: true
  trailing?: boolean; // default: false
}

useThrottleValue(value: string, ms = 500, options?: UseThrottleOptions):

useUnmount

Run a function when the component unmounts.

import React from 'react';
import { useUnmount } from '@gilbarbara/hooks';

function Component() {
  useUnmount(() => {
    // cleanup the listener
  });

  return <div>Some content...</div>;
}

Reference

useUnmount(fn: () => void): void;

useWhyDidYouUpdate

Get which prop changes are causing a component to re-render.

function Component(props: any) {
  const changes = useWhyDidYouUpdate(props, { skipLog: true });
  // Or just log the changes
  // useWhyDidYouUpdate(props, 'Component');

  return <div>{!!changes && JSON.stringify(changes, null, 2)}</div>;
}

Reference

type PlainObject<T = unknown> = Record<string | number | symbol, T>;

interface UseWhyDidYouUpdateOptions {
  name?: string;
  skipLog?: boolean;
}

useWhyDidYouUpdate<T extends PlainObject>(
  props: T,
  nameOrOptions: string | UseWhyDidYouUpdateOptions = {},
);

useWindowSize

Get the window dimensions. Updates on resize.
Returns a WindowSize object.

import React from 'react';
import { useWindowSize } from '@gilbarbara/hooks';

function Component() {
  const { width } = useWindowSize();

  return <div>{width >= 1024 ? 'Large Screen' : 'Small Screen'}</div>;
}

Reference

interface WindowSize {
  height: number;
  width: number;
}

useWindowSize(debounce?: number): WindowSize;

License

MIT