usehooks

This example demonstrates how to use useScript to load the MooTools library and conditionally render metadata once the script is in the ready state.

import * as React from "react";
import { useScript } from "@uidotdev/usehooks";
import ScriptMeta from './ScriptMeta';

export default function App() {
  const status = useScript(
    `https://cdnjs.cloudflare.com/ajax/libs/mootools/1.6.0/mootools-core.js`,
    {
      removeOnUnmount: false,
    }
  );

  React.useEffect(() => {
    if (typeof window.$$ !== "undefined") {
      const id = document.id("moo");
      id.setStyle("background-color", "var(--green)");
    }
  }, [status]);

  const isReady = status === "ready";

  return (
    <section>
      <h1>useScript</h1>
      <p>
        <span id="moo" className={isReady ? "ready" : ""} />
        <label>Status: {status}</label>
      </p>
      {status === "ready" && (
        <ScriptMeta title="MooTools" status={status} meta={window.MooTools} />
      )}
    </section>
  );
}

This example demonstrates how to use useDebounce to trigger a network request (searching Hacker News) only after the user has stopped typing for 300ms, preventing excessive API calls.

import * as React from "react";
import { useDebounce } from "@uidotdev/usehooks";
import searchHackerNews from "./searchHackerNews";
import SearchResults from "./SearchResults";

export default function App() {
  const [searchTerm, setSearchTerm] = React.useState("js");
  const [results, setResults] = React.useState([]);
  const [isSearching, setIsSearching] = React.useState(false);
  
  // Debounce the search term by 300ms
  const debouncedSearchTerm = useDebounce(searchTerm, 300);

  const handleChange = (e) => {
    setSearchTerm(e.target.value);
  };

  const handleSubmit = (e) => {
    e.preventDefault();
    const formData = new FormData(e.target);
    setSearchTerm(formData.get("search"));
    e.target.reset();
    e.target.focus();
  };

  React.useEffect(() => {
    const searchHN = async () => {
      let results = [];
      setIsSearching(true);
      if (debouncedSearchTerm) {
        const data = await searchHackerNews(debouncedSearchTerm);
        results = data?.hits || [];
      }

      setIsSearching(false);
      setResults(results);
    };

    searchHN();
  }, [debouncedSearchTerm]);

  return (
    <section>
      <header>
        <h1>useDebounce</h1>
        <form onSubmit={handleSubmit}>
          <input
            name="search"
            placeholder="Search HN"
            style={{ background: "var(--charcoal)" }}
            onChange={handleChange}
          />
          <button className="primary" disabled={isSearching} type="submit">
            {isSearching ? "..." : "Search"}
          </button>
        </form>
      </header>
      <SearchResults results={results} />
    </section>
  );
}

You can use useEventListener on the document to detect clicks outside of a specific element (like a modal) by checking if the click target is contained within the element's ref.

import * as React from "react";
import { useEventListener } from "@uidotdev/usehooks";

export default function App() {
  const ref = React.useRef(null);
  const [isOpen, setIsOpen] = React.useState(false);

  const handleClick = (e) => {
    const element = ref.current;
    // If the modal is open and the click was NOT inside the modal element
    if (element && !element.contains(e.target)) {
      setIsOpen(false);
    }
  };

  // Attach listener to the entire document
  useEventListener(document, "mousedown", handleClick);

  return (
    <section>
      <button onClick={() => setIsOpen(true)}>Open Modal</button>
      {isOpen && (
        <dialog ref={ref}>
          <h2>Modal</h2>
          <p>Click outside to close.</p>
          <button onClick={() => setIsOpen(false)}>Close</button>
        </dialog>
      )}
    </section>
  );
}

import * as React from "react";
import { useEventListener } from "@uidotdev/usehooks";
import { closeIcon } from "./icons";

export default function App() {
  const ref = React.useRef(null);
  const [isOpen, setIsOpen] = React.useState(false);

  const handleClick = (e) => {
    const element = ref.current;
    if (element && !element.contains(e.target)) {
      setIsOpen(false);
    }
  };

  useEventListener(document, "mousedown", handleClick);

  return (
    <section>
      <h1>useEventListener</h1>
      <div style={{ minHeight: "200vh" }}>
        <button className="link" onClick={() => setIsOpen(true)}>
          Click me
        </button>
      </div>
      {isOpen && (
        <dialog ref={ref}>
          <button onClick={() => setIsOpen(false)}>{closeIcon}</button>
          <h2>Modal</h2>
          <p>
            Click outside the modal to close (or use the button) whatever you
            prefer.
          </p>
        </dialog>
      )}
    </section>
  );
}

This example demonstrates how to use useLocalStorage to persist a canvas drawing state. The drawing state is stored under the key "drawing" and is automatically updated whenever the drawing changes.

import * as React from "react";
import { useLocalStorage } from "@uidotdev/usehooks";
import createDrawing from "./createDrawing";

export default function App() {
  const [drawing, saveDrawing] = useLocalStorage("drawing", null);
  const ref = React.useRef(null);

  React.useEffect(() => {
    createDrawing(ref.current, drawing, saveDrawing);
  }, [drawing, saveDrawing]);

  return (
    <section>
      <header>
        <h1>useLocalStorage</h1>

        <button className="link" onClick={() => window.location.reload()}>
          Reload Window
        </button>
        <button
          className="link"
          onClick={() => {
            window.localStorage.clear();
            window.location.reload();
          }}
        >
          Clear Local Storage
        </button>
      </header>
      <figure>
        <canvas ref={ref} width={800} height={800} />
        <figcaption>(draw something)</figcaption>
      </figure>
    </section>
  );
}

This example demonstrates how to use usePrevious to display both the current state and the value that was held immediately before the last update.

import * as React from "react";
import { usePrevious } from "@uidotdev/usehooks";

function getRandomColor() {
  const colors = ["green", "blue", "purple", "red", "pink"];
  return colors[Math.floor(Math.random() * colors.length)];
}

export default function App() {
  const [color, setColor] = React.useState(getRandomColor());
  const previousColor = usePrevious(color);

  const handleClick = () => {
    function getNewColor() {
      const newColor = getRandomColor();
      if (color === newColor) {
        getNewColor();
      } else {
        setColor(newColor);
      }
    }
    getNewColor();
  };

  return (
    <section>
      <h1>usePrevious</h1>
      <button className="link" onClick={handleClick}>
        Next
      </button>
      <article>
        <figure>
          <p style={{ background: `var(--${previousColor})` }} />
          <figcaption>Previous: {previousColor}</figcaption>
        </figure>
        <figure>
          <p style={{ background: `var(--${color})` }} />
          <figcaption>Current: {color}</figcaption>
        </figure>
      </article>
    </section>
  );
}

This example demonstrates how to use useInterval to cycle through an array of colors and how to use the returned clear function to stop the interval via a button click.

import * as React from "react";
import { useInterval } from "@uidotdev/usehooks";

const colors = ["green", "blue", "purple", "red", "pink", "beige", "yellow"];

export default function App() {
  const [running, setIsRunning] = React.useState(true);
  const [index, setIndex] = React.useState(0);

  const clear = useInterval(() => {
    setIndex(index + 1);
  }, 1000);

  const handleStop = () => {
    clear();
    setIsRunning(false);
  };

  const color = colors[index % colors.length];
  return (
    <section>
      <h1>useInterval</h1>
      <button disabled={!running} className="link" onClick={handleStop}>
        {running ? "Stop" : "Stopped"}
      </button>
      <div style={{ backgroundColor: `var(--${color})` }} />
    </section>
  );
}

This example demonstrates how to use useCountdown to create a timer that can be extended by clicking buttons. It uses endTime (a timestamp in milliseconds) and provides callbacks for ticking and completion.

import * as React from "react";
import { useCountdown } from "@uidotdev/usehooks";

export default function App() {
  const [endTime, setEndTime] = React.useState(new Date(Date.now() + 10000));
  const [complete, setComplete] = React.useState(false);

  const count = useCountdown(endTime, {
    interval: 1000,
    onTick: () => console.log("tick"),
    onComplete: (time) => setComplete(true),
  });

  const handleClick = (time) => {
    if (complete === true) return;
    const nextTime = endTime.getTime() + time;
    setEndTime(new Date(nextTime));
  };

  return (
    <section>
      <header>
        <h1>useCountdown</h1>
      </header>
      <span className="countdown">{count}</span>
      {complete === false && (
        <div className="button-row">
          <button onClick={() => handleClick(5000)}>+5s</button>
          <button onClick={() => handleClick(10000)}>+10s</button>
          <button onClick={() => handleClick(15000)}>+15s</button>
        </div>
      )}
    </section>
  );
}

The useIdle hook detects user inactivity by tracking interactions and determining if a specified duration of time has passed without activity. It is useful for implementing features like automatic logout, inactivity notifications, or UI adjustments based on engagement.

Parameters

Return Values

import * as React from "react";
import { useIdle } from "@uidotdev/usehooks";

export default function App() {
  const idle = useIdle(5000);
  return (
    <section>
      <h1>useIdle</h1>
      <div>
        <span className={idle ? "idle" : ""} />
        <label>Status: {idle ? "Idle" : "Active"}</label>
      </div>
      {idle ? <p>Time to move your mouse</p> : <p>Hold still and wait</p>}
    </section>
  );
}