npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

react-use-utils

v1.1.0

Published

Uma coleção de ganchos e utilitários React

Downloads

20

Readme

react-use-utils

Essa lib é um conjunto de hooks que facilitam o desenvolvimento de aplicações React. Ela foi criada para ser utilizada em conjunto com o create-react-app e o Typescript.

Instalação

npm install react-use-utils

Uso

import React from 'react';
import { useLocalStorage } from 'react-use-utils';

const App: React.FC = () => {
  const [name, setName] = useLocalStorage('name', 'John Doe');

  return (
    <div>
      <input
        type="text"
        value={name}
        onChange={(e) => setName(e.target.value)}
      />
    </div>
  );
};

Hooks

useOptimistic

useOptimistic<T = any, V = any>(
    state: T, 
    updateFn: (currentState: T, optimisticValue: V) => T
): [T, (value: V) => void]

Hook que permite atualizar o estado de forma otimista.

  • state: Estado atual.
  • updateFn: Função que atualiza o estado de forma otimista.
  • value: Valor otimista.
  • return: Retorna o estado atual e uma função para adicionar um valor otimista.
import React from 'react';
import { useOptimistic } from 'react-use-utils';

const App: React.FC = () => {
  const [messages, setMessages] = useState([]);

  const [optimisticMessages, addOptimisticMessage] = useOptimistic(messages, (currentState, optimisticValue) => {
    return [...currentState, {...optimisticValue, sending: true}];
  });

  const addMessage = (message) => {
    addOptimisticMessage(message);
    fetch('https://api.example.com/messages', {
      method: 'POST',
      body: JSON.stringify(message),
    }).then(() => {
      setMessages([...messages, message]);
    });
  };

  return (
    <div>
      {optimisticMessages.map((message) => (
        <div key={message.id}>{message.text}</div>
      ))}
      <button onClick={() => addMessage({ id: messages.length, text: 'Hello' })}>
        Add message
      </button>
    </div>
  );
};

useId

useId(idName?: string): string

Gancho para gerar um ID exclusivo.

  • idName: Nome do ID.
  • return: Retorna um ID exclusivo.
import React from 'react';
import { useId } from 'react-use-utils';

const App: React.FC = () => {
  const id = useId();

  return <div id={id}>Hello World</div>;
};

useProxy

useProxy<T extends object>(target: T, onChange?: (target: T) => void): T

Observa as alterações em um objeto e executa uma função de retorno quando ocorre uma mudança.

  • target: Objeto alvo.
  • onChange: Função de retorno.
  • return: Retorna um objeto proxy.
import React from 'react';
import { useProxy } from 'react-use-utils';

const App: React.FC = () => {
  const user = useProxy({ name: 'John Doe', age: 30 }, (newUser) => {
    console.log('User changed:', newUser);
  });

  return (
    <div>
      <input
        type="text"
        value={user.name}
        onChange={(e) => {
            user.name = e.target.value
        }}
      />
    </div>
  );
};

useDebounceCallbackEffect

useDebounceCallbackEffect(
    callback: () => void, 
    delay: number, 
    dependencies: any[]
): void

Hook que executa um callback após um determinado tempo de espera (delay), mas só executa uma vez, mesmo que as dependências mudem antes do fim do delay.

  • callback: Função de retorno.
  • delay: Tempo de espera.
  • dependencies: Dependências.
  • return: Retorna void.
import React, { useState } from 'react';
import { useDebounceCallbackEffect } from 'react-use-utils';

const App: React.FC = () => {
  const [value, setValue] = useState('');
  const [debouncedValue, setDebouncedValue] = useState('');

  useDebounceCallbackEffect(() => {
    setDebouncedValue(value);
  }, 500, [value]);

  return (
    <div>
      <input
        type="text"
        value={value}
        onChange={(e) => setValue(e.target.value)}
      />
      <p>Debounced value: {debouncedValue}</p>
    </div>
  );
};

useDebounce

useDebounce<T = any>(value: T, delay: number): T

Hook que retorna um valor após um determinado tempo de espera (delay).

  • value: Valor.
  • delay: Tempo de espera.
  • return: Retorna o valor após o tempo de espera.
import React, { useState } from 'react';
import { useDebounce } from 'react-use-utils';

const App: React.FC = () => {
  const [value, setValue] = useState('');
  const debouncedValue = useDebounce(value, 500);

  return (
    <div>
      <input
        type="text"
        value={value}
        onChange={(e) => setValue(e.target.value)}
      />
      <p>Debounced value: {debouncedValue}</p>
    </div>
  );
};

useWindowSize

useWindowSize(): { width: number; height: number }

Hook que retorna a largura e a altura da janela do navegador.

  • width: Largura da janela.
  • height: Altura da janela.
  • return: Retorna a largura e a altura da janela.
import React from 'react';
import { useWindowSize } from 'react-use-utils';

const App: React.FC = () => {
  const { width, height } = useWindowSize();

  return (
    <div>
      <p>Width: {width}</p>
      <p>Height: {height}</p>
    </div>
  );
};

useAsync

useAsync<T = any>(asyncFunction: (...props: any[]) => Promise<T>, immediate?: boolean): {
    execute: (...props: any[]) => Promise<void>;
    status: "idle" | "pending" | "success" | "error";
    value: T | null;
    error: any;
}

Hook que executa uma função assíncrona e retorna o status da execução, o valor retornado e o erro, caso ocorra.

  • asyncFunction: Função assíncrona.
  • immediate: Se true, a função é executada imediatamente.
  • execute: Função para executar a função assíncrona.
  • status: Status da execução.
  • value: Valor retornado.
  • error: Erro, caso ocorra.
  • return: Retorna um objeto com as propriedades execute, status, value e error.
import React from 'react';
import { useAsync } from 'react-use-utils';

const fetchData = async () => {
  const response = await fetch('https://jsonplaceholder.typicode.com/todos/1');
  return response.json();
};

const App: React.FC = () => {
  const { execute, status, value, error } = useAsync(fetchData, false);

  return (
    <div>
      {status === 'idle' && <div>Start your journey by clicking a button</div>}
      {status === 'pending' && <div>Loading...</div>}
      {status === 'success' && <div>{JSON.stringify(value)}</div>}
      {status === 'error' && <div>{error.message}</div>}
      <button onClick={execute} disabled={status === 'pending'}>
        {status !== 'pending' ? 'Click me' : 'Loading...'}
      </button>
    </div>
  );
};

useToggle

useToggle(initialValue: boolean): [boolean, () => void]

Hook que retorna um valor booleano e uma função para alternar entre true e false.

  • initialValue: Valor inicial.
  • return: Retorna um array com o valor booleano e a função para alternar.
  • value: Valor booleano.
  • toggle: Função para alternar.
  • return: Retorna um array com o valor booleano e a função para alternar.
import React from 'react';
import { useToggle } from 'react-use-utils';

const App: React.FC = () => {
  const [isOn, toggle] = useToggle(false);

  return (
    <div>
      <p>{isOn ? 'ON' : 'OFF'}</p>
      <button onClick={toggle}>Toggle</button>
    </div>
  );
};

useRouter

useRouter(path?: string | string[] | RegExp | RegExp[]): {
    go: (delta: number) => void;
    back: () => void;
    forward: () => void;
    push: (url: string, state?: any) => void;
    replace: (url: string, state?: any) => void;
    state: any;
    hash: string;
    pathname: string;
    query: any;
    search: string;
    length: number;
    currentIndex: number;
}

Hook que retorna informações sobre a rota atual e funções para navegar entre as rotas.

  • path: Caminho da rota de referência. Útil para ferificar se a rota atual corresponde a um caminho específico. Se for um array, verifica se a rota atual corresponde a qualquer um dos caminhos no array. Se for uma expressão regular, verifica se a rota atual corresponde à expressão regular. Se for um array de expressões regulares, verifica se a rota atual corresponde a qualquer uma das expressões regulares no array.
  • go: Navega para uma rota específica.
  • back: Navega para a rota anterior.
  • forward: Navega para a próxima rota.
  • push: Adiciona uma nova rota ao histórico.
  • replace: Substitui a rota atual.
  • state: Estado da rota.
  • hash: Hash da rota.
  • pathname: Caminho da rota.
  • query: Query string da rota.
    • exact: Se true, a rota atual corresponde exatamente ao caminho de referência.
    • params: Parâmetros da rota.
    • search: Parâmetros da query string.
    • query: Junção dos parâmetros da rota e da query string.
    • path: Caminho da rota de referência válida.
    • pathValid: Rota de referência válida.
    • ...: Parâmetros da rota e derivados.
  • search: Parâmetros da query string.
  • length: Número de rotas no histórico.
  • currentIndex: Índice da rota atual.
  • return: Retorna um objeto com as propriedades go, back, forward, push, replace, state, hash, pathname, query, search, length e currentIndex.
import React from 'react';
import { useRouter } from 'react-use-utils';

const App: React.FC = () => {
  const { pathname, query, push } = useRouter();

  return (
    <div>
      <p>Pathname: {pathname}</p>
      <p>Query: {JSON.stringify(query)}</p>
      <button onClick={() => push('/about')}>Go to About</button>
    </div>
  );
};

useEventListener

useEventListener<E extends HTMLElement, K extends keyof GlobalEventHandlersEventMap>(
    element: React.RefObject<E | null>, 
    eventName: K, 
    eventHandler: (event: GlobalEventHandlersEventMap[K]) => void, 
    wantsUntrusted?: boolean
): void

Hook que adiciona um ouvinte de eventos a um elemento.

  • element: Elemento.
  • eventName: Nome do evento.
  • eventHandler: Função de retorno.
  • wantsUntrusted: Se true, o ouvinte de eventos também recebe eventos não confiáveis.
  • return: Retorna void.
import React, { useRef } from 'react';
import { useEventListener } from 'react-use-utils';

const App: React.FC = () => {
  const buttonRef = useRef<HTMLButtonElement>(null);

  useEventListener(buttonRef, 'click', () => {
    console.log('Button clicked');
  });

  return (
    <div>
      <button ref={buttonRef}>Click me</button>
    </div>
  );
};

useMediaQuery

useMediaQuery<T = any>(queries: {
    [query: string]: T;
}, defaultValue: T): T

Hook que retorna um valor com base em uma consulta de mídia.

  • queries: Consultas de mídia.
  • defaultValue: Valor padrão.
  • return: Retorna um valor com base na consulta de mídia.
import React from 'react';
import { useMediaQuery } from 'react-use-utils';

const App: React.FC = () => {
  const theme = useMediaQuery(
    {
      '(prefers-color-scheme: dark)': 'dark',
      '(prefers-color-scheme: light)': 'light',
    },
    'light'
  );

  const device = useMediaQuery(
    {
      '(min-width: 1000px)': 'desktop',
      '(min-width: 600px)': 'tablet',
      '(max-width: 599px)': 'mobile',
    },
    'mobile'
  );

  return (
    <div>
      <p>Theme: {theme}</p>
      <p>Device: {device}</p>
    </div>
  );
};

useStateHistory

useStateHistory<T = any>(initialPresent: T): {
    state: T;
    set: (newPresent: T) => void;
    undo: () => void;
    redo: () => void;
    clear: () => void;
    canUndo: boolean;
    canRedo: boolean;
}

Hook que gerencia o histórico de estados.

  • initialPresent: Estado inicial.
  • state: Estado atual.
  • set: Função para definir um novo estado.
  • undo: Função para desfazer a última ação.
  • redo: Função para refazer a última ação.
  • clear: Função para limpar o histórico.
  • canUndo: Se true, é possível desfazer a última ação.
  • canRedo: Se true, é possível refazer a última ação.
  • return: Retorna um objeto com as propriedades state, set, undo, redo, clear, canUndo e canRedo.
import React from 'react';
import { useStateHistory } from 'react-use-utils';

const App: React.FC = () => {
  const { state, set, undo, redo, clear, canUndo, canRedo } = useStateHistory(0);

  return (
    <div>
      <p>Value: {state}</p>
      <button onClick={() => set(state + 1)}>Increment</button>
      <button onClick={() => set(state - 1)}>Decrement</button>
      <button onClick={undo} disabled={!canUndo}>
        Undo
      </button>
      <button onClick={redo} disabled={!canRedo}>
        Redo
      </button>
      <button onClick={clear}>Clear</button>
    </div>
  );
};

useScript

useScript(src: string): "error" | "idle" | "loading" | "ready"

Hook que carrega um script.

  • src: URL do script.
  • return: Retorna o status do script.
import React from 'react';
import { useScript } from 'react-use-utils';

const App: React.FC = () => {
  const status = useScript('https://code.jquery.com/jquery-3.6.0.min.js');

  return <p>Script status: {status}</p>;
};

useKeyPress

useKeyPress(targetKey: KeyboardEvent["key"], callback: (pressed:boolean) => void): void

Hook que executa um callback quando uma tecla é pressionada.

  • targetKey: Tecla alvo.
  • callback: Função de retorno.
  • return: Retorna void.
import React from 'react';
import { useKeyPress } from 'react-use-utils';

const App: React.FC = () => {
  useKeyPress('Enter', (pressed) => {
    console.log('Enter key pressed:', pressed);
  });

  return <div>Press Enter key</div>;
};

useOnScreen

useOnScreen<T extends HTMLElement>(
    ref: React.RefObject<T>, 
    rootMargin?: string
): boolean

Hook que verifica se um elemento está visível na tela.

  • ref: Referência do elemento.
  • rootMargin: Margem do elemento.
  • return: Retorna true se o elemento estiver visível.
import React, { useRef } from 'react';
import { useOnScreen } from 'react-use-utils';

const App: React.FC = () => {
  const ref = useRef<HTMLDivElement>(null);
  const isVisible = useOnScreen(ref, '-100px');

  return (
    <div>
      <div style={{ height: '100vh' }}>Scroll down</div>
      <div ref={ref} style={{ height: '100vh', background: isVisible ? 'red' : 'blue' }}>
        {isVisible ? 'Visible' : 'Not visible'}
      </div>
    </div>
  );
};

usePrevious

usePrevious<T = any>(value: T): T | undefined

Hook que retorna o valor anterior.

  • value: Valor atual.
  • return: Retorna o valor anterior.
import React, { useState } from 'react';
import { usePrevious } from 'react-use-utils';

const App: React.FC = () => {
  const [count, setCount] = useState(0);
  const previousCount = usePrevious(count);

  return (
    <div>
      <p>Previous count: {previousCount}</p>
      <p>Current count: {count}</p>
      <button onClick={() => setCount(count + 1)}>Increment</button>
    </div>
  );
};

useOnClickOutside

useOnClickOutside<T extends HTMLElement>(
    ref: React.RefObject<T>, 
    handler: (event: MouseEvent | TouchEvent) => void
): void

Hook que executa um callback quando um clique fora de um elemento é detectado.

  • ref: Referência do elemento.
  • handler: Função de retorno.
  • return: Retorna void.
import React, { useRef } from 'react';
import { useOnClickOutside } from 'react-use-utils';

const App: React.FC = () => {
  const ref = useRef<HTMLDivElement>(null);

  useOnClickOutside(ref, () => {
    console.log('Clicked outside');
  });

  return (
    <div>
      <div ref={ref} style={{ width: 200, height: 200, background: 'red' }}>
        Click outside
      </div>
    </div>
  );
};

useHover

useHover<T extends HTMLElement>(ref: React.RefObject<T>): boolean

Hook que verifica se um elemento está sendo passado o mouse por cima.

  • ref: Referência do elemento.
  • return: Retorna true se o mouse estiver passando por cima do elemento.
import React, { useRef } from 'react';
import { useHover } from 'react-use-utils';

const App: React.FC = () => {
  const ref = useRef<HTMLDivElement>(null);
  const isHovered = useHover(ref);

  return (
    <div>
      <div ref={ref} style={{ width: 200, height: 200, background: isHovered ? 'red' : 'blue' }}>
        Hover me
      </div>
    </div>
  );
};

useCounterTimer

useCounterTimer(delay?: number, duration?: number, delayFrame?: number): number

Hook que retorna o tempo decorrido desde o início da contagem.

  • delay: Tempo de espera.
  • duration: Duração da contagem.
  • delayFrame: Quadro de atraso.
  • return: Retorna o tempo decorrido.
import React from 'react';
import { useCounterTimer } from 'react-use-utils';

const App: React.FC = () => {
  const elapsed = useCounterTimer(1000, 5000, 100);

  return <div>Elapsed time: {elapsed}ms</div>;
};

useBezierEasing

useBezierEasing(
    easing: 
        | [number, number, number, number]
        | [[number, number], [number, number]]
        | "linear"
        | "elastic"
        | "ease"
        | "ease-in"
        | "ease-in-elastic"
        | "ease-in-bounce"
        | "ease-in-expo"
        | "ease-in-sine"
        | "ease-in-quad"
        | "ease-in-cubic"
        | "ease-in-back"
        | "ease-in-quart"
        | "ease-in-quint"
        | "ease-in-circ"
        | "ease-in-out"
        | "ease-in-out-elastic"
        | "ease-in-out-bounce"
        | "ease-in-out-sine"
        | "ease-in-out-quad"
        | "ease-in-out-cubic"
        | "ease-in-out-back"
        | "ease-in-out-quart"
        | "ease-in-out-quint"
        | "ease-in-out-expo"
        | "ease-in-out-circ"
        | "ease-out"
        | "ease-out-elastic"
        | "ease-out-bounce"
        | "ease-out-sine"
        | "ease-out-quad"
        | "ease-out-cubic"
        | "ease-out-back"
        | "ease-out-quart"
        | "ease-out-quint"
        | "ease-out-expo"
        | "ease-out-circ"
        | "fast-out-slow-in"
        | "fast-out-linear-in"
        | "linear-out-slow-in" = "linear", 
    delay: number, 
    duration: number, 
    delayFrame?: number
): any

Hook que retorna um valor com base em uma função de easing.

  • easing: Função de easing.
    • [number, number, number, number]: Curva de Bezier.
    • [[number, number], [number, number]]: Curva de Bezier.
    • "linear": Linear.
    • "elastic": Elástico.
    • "ease": Suave.
    • "ease-in": Suave de entrada.
    • "ease-in-elastic": Suave de entrada elástica.
    • "ease-in-bounce": Suave de entrada de salto.
    • "ease-in-expo": Suave de entrada exponencial.
    • "ease-in-sine": Suave de entrada senoidal.
    • "ease-in-quad": Suave de entrada quadrática.
    • "ease-in-cubic": Suave de entrada cúbica.
    • "ease-in-back": Suave de entrada de volta.
    • "ease-in-quart": Suave de entrada quartica.
    • "ease-in-quint": Suave de entrada quintica.
    • "ease-in-circ": Suave de entrada circular.
    • "ease-in-out": Suave de entrada e saída.
    • "ease-in-out-elastic": Suave de entrada e saída elástica.
    • "ease-in-out-bounce": Suave de entrada e saída de salto.
    • "ease-in-out-sine": Suave de entrada e saída senoidal.
    • "ease-in-out-quad": Suave de entrada e saída quadrática.
    • "ease-in-out-cubic": Suave de entrada e saída cúbica.
    • "ease-in-out-back": Suave de entrada e saída de volta.
    • "ease-in-out-quart": Suave de entrada e saída quartica.
    • "ease-in-out-quint": Suave de entrada e saída quintica.
    • "ease-in-out-expo": Suave de entrada e saída exponencial.
    • "ease-in-out-circ": Suave de entrada e saída circular.
    • "ease-out": Suave de saída.
    • "ease-out-elastic": Suave de saída elástica.
    • "ease-out-bounce": Suave de saída de salto.
    • "ease-out-sine": Suave de saída senoidal.
    • "ease-out-quad": Suave de saída quadrática.
    • "ease-out-cubic": Suave de saída cúbica.
    • "ease-out-back": Suave de saída de volta.
    • "ease-out-quart": Suave de saída quartica.
    • "ease-out-quint": Suave de saída quintica.
    • "ease-out-expo": Suave de saída exponencial.
    • "ease-out-circ": Suave de saída circular.
    • "fast-out-slow-in": Rápido de saída lento de entrada.
    • "fast-out-linear-in": Rápido de saída linear de entrada.
    • "linear-out-slow-in": Linear de saída lento de entrada.
  • delay: Tempo de espera.
  • duration: Duração.
  • delayFrame: Quadro de atraso.
  • return: Retorna um valor com base na função de easing.
import React from 'react';
import { useBezierEasing } from 'react-use-utils';

const App: React.FC = () => {
  const value = useBezierEasing('ease-in-out', 100, 1000, 10);

  return <div>Value: {value}</div>;
};

useLocalStorage

useLocalStorage<T = any>(key: string, initialValue: T): [T, (value: T|(previous: T)=>T) => void]

Hook que armazena um valor no localStorage.

  • key: Chave.
  • initialValue: Valor inicial.
  • return: Retorna um array com o valor e uma função para definir um novo valor.
import React from 'react';
import { useLocalStorage } from 'react-use-utils';

const App: React.FC = () => {
  const [name, setName] = useLocalStorage('name', 'John Doe');

  return (
    <div>
      <input
        type="text"
        value={name}
        onChange={(e) => setName(e.target.value)}
      />
    </div>
  );
};

useElementRect

useElementRect<T extends HTMLElement>(ref: React.RefObject<T>): {
    width: number;
    height: number;
    bottom: number;
    top: number;
    left: number;
    right: number;
    x: number;
    y: number;
}

Hook que retorna as dimensões de um elemento.

  • ref: Referência do elemento.
  • width: Largura.
  • height: Altura.
  • bottom: Distância do topo.
  • top: Distância da base.
  • left: Distância da esquerda.
  • right: Distância da direita.
  • x: Posição horizontal.
  • y: Posição vertical.
  • return: Retorna um objeto com as propriedades width, height, bottom, top, left, right, x e y.
import React, { useRef } from 'react';
import { useElementRect } from 'react-use-utils';

const App: React.FC = () => {
  const ref = useRef<HTMLDivElement>(null);
  const rect = useElementRect(ref);

  return (
    <div>
      <div ref={ref} style={{ width: 200, height: 200, background: 'red' }}>
        Element
      </div>
      <p>Width: {rect.width}</p>
      <p>Height: {rect.height}</p>
    </div>
  );
};

useFitText

useFitText<T extends HTMLElement, I extends HTMLElement>(
    textRef: React.MutableRefObject<T | null>, 
    containerRef: React.MutableRefObject<I | null>, 
    minFontSize?: number, 
    maxFontSize?: number, 
    increment?: number
): void

Hook que ajusta o tamanho do texto para caber no contêiner.

  • textRef: Referência do texto.
  • containerRef: Referência do contêiner.
  • minFontSize: Tamanho mínimo da fonte.
  • maxFontSize: Tamanho máximo da fonte.
  • increment: Incremento.
  • return: Retorna void.
import React, { useRef } from 'react';
import { useFitText } from 'react-use-utils';

const App: React.FC = () => {
  const textRef = useRef<HTMLDivElement>(null);
  const containerRef = useRef<HTMLDivElement>(null);

  useFitText(textRef, containerRef, 12, 24, 1);

  return (
    <div>
      <div ref={containerRef} style={{ width: 200, height: 200, background: 'red' }}>
        <div ref={textRef}>Fit text</div>
      </div>
    </div>
  );
};