Fizzy Hooks

Fizzy Hooks is a lightweight collection of production-ready, reusable React hooks written in TypeScript. Simplify your code, speed up development, and keep your components clean and efficient.

Features

• Written in TypeScript
• Tiny & tree-shakable
• Plug & play hooks for real-world needs
• Actively maintained

Installation

npm install fizzy-hooks

Included Hooks

| Hook | Description | | ----------------------------------------- | ----------------------------------------------- | | useAsync | Manage asynchronous operations and track status | | useBattery | Get battery status (charging, level, etc.) | | useClickOutside | Detect clicks outside of a specified element | | useCopyToClipboard | Copy text to clipboard and track copy status | | useDebounce | Debounce a value | | useDefault | Use a fallback value when a value is invalid | | useDocumentTitle | Dynamically update the document title | | useEventListener | Attach event listeners to any DOM element | | useFavicon | Dynamically change the page's favicon | | useFetch | Simple fetch wrapper hook | | useGeolocation | Get and track user's geolocation | | useHover | Detect hover state on an element | | useIdle | Track if the user is idle (no activity) | | useIntersectionObserver | Observe if an element enters the viewport | | useInterval | Run a callback on an interval with pause/resume | | useIsOnline | Track internet connectivity status | | useLocalStorage | Read and write from localStorage | | useMediaQuery | Track media query matches | | usePrevious | Access the previous value of a state/prop | | useScreenOrientation | Get the current screen orientation | | useSessionStorage | Use sessionStorage like state | | useSpeechSynthesis | Speak text using browser’s speech API | | useThrottle | Throttle a value or callback | | useTimeout | Delay function execution with clearable timeout | | useToggle | Toggle boolean state | | useUndoRedo | Add undo/redo capabilities to state | | useUndoRedoPersist | Undo/redo state with persistence | | useWindowSize | Get current window dimensions |

Contributing

Contributions, ideas, and feedback are welcome!

git clone https://github.com/fizzycoding/fizzy-hooks.git
cd fizzy-hooks
npm install

Then:

Add or improve a hook in src/hooks

Run npm run build

Open a PR

License

MIT © fizzycoding

Support

If you find this library helpful:

• Star this repo

• Share it with other developers

• Use it in your projects

Usage Examples

useAsync

useAsync helps you manage asynchronous operations in React. It tracks the loading state, result, and any errors from an async function.

Import

import { useAsync } from "fizzy-hooks";

Parameters

• asyncFn: The async function you want to execute.
• autoRun (optional): If true, runs asyncFn immediately on mount. Default is false.
• deps (optional): Dependency array to re-run asyncFn if autoRun is enabled.

Returns

| Value | Type | Description | | --------- | ---------------- | ----------------------------------------------------- | | value | any | The returned data from the async function | | loading | boolean | Indicates whether the async function is still running | | error | string \| null | The error message if the function fails | | run | function | Function to trigger the async operation manually | | reset | function | Resets the state to the initial state |

Example

import { useAsync } from "fizzy-hooks";

const fetchData = async () => {
  const res = await fetch("https://jsonplaceholder.typicode.com/todos");
  if (!res.ok) throw new Error("Failed to fetch");
  return res.json();
};

function ExampleComponent() {
  // useAsync(asyncFn, autoRun, deps)

  const { value, loading, error, run, reset } = useAsync(fetchData, true);
  if (loading) return <p>Loading</p>;
  return (
    <div>
      <button onClick={run}>Fetch</button>
      <button onClick={reset}>Reset</button>
      {error && <p>Error: {error}</p>}
      {value && <pre>{JSON.stringify(value, null, 2)}</pre>}
    </div>
  );
}

Explanation: You define an async function (like fetchData), then use run() to trigger it. While it's running, loading is true. When it finishes, the result is stored in value. If it fails, error contains the error message. You can reset everything using reset().

useBattery

useBattery hook provides real-time information about the user's device battery status using the Battery Status API.

Import

import { useBattery } from "fizzy-hooks";

Returns | Value | Type | Description | | ----------------- | --------- | --------------------------------------------------- | | charging | boolean | Whether the battery is currently charging | | level | number | Battery level (from 0 to 1) | | chargingTime | number | Time in seconds until the battery is fully charged | | dischargingTime | number | Time in seconds until the battery is empty | | supported | boolean | Whether the browser supports the Battery Status API | | loading | boolean | true while the battery status is being fetched |

Example

import { useBattery } from "fizzy-hooks";

function BatteryInfo() {
  const { charging, level, chargingTime, dischargingTime, supported, loading } =
    useBattery();

  if (!supported) return <p>Battery API not supported on this device.</p>;
  if (loading) return <p>Loading battery status...</p>;

  return (
    <div>
      <p>Battery Level: {Math.round(level * 100)}%</p>
      <p>{charging ? "Charging" : "Not Charging"}</p>
      <p>Charging Time: {chargingTime} seconds</p>
      <p>Discharging Time: {dischargingTime} seconds</p>
    </div>
  );
}

useClickOutside

useClickOutside is a React hook that detects clicks outside of a referenced element and runs a callback handler. This is especially useful for closing modals, dropdowns, tooltips, or menus when a user clicks outside of them.

Import

import { useClickOutside } from "fizzy-hooks";

Parameters | Parameter | Type | Description | | --------- | ------------------------------------------- | ----------------------------------------- | | handler | handlerFunction | Callback function to run on outside click |

Returns

| Value | Type | Description | | ----- | -------------------- | --------------------------------------------------------------------- | | ref | React.RefObject<T> | Attach this ref to the element you want to monitor for outside clicks |

Example

import { useClickOutside } from "fizzy-hooks";
import { useState } from "react";

function Dropdown() {
  const [open, setOpen] = useState(false);

  const ref = useClickOutside<HTMLDivElement>(() => {
    setOpen(false);
  });

  return (
    <div>
      <button onClick={() => setOpen(!open)}>Toggle Dropdown</button>

      {open && (
        <div
          ref={ref}
          style={{
            position: "absolute",
            background: "green",
            padding: "10px",
            border: "1px solid #ccc",
          }}
        >
          <p>This is a dropdown.</p>
        </div>
      )}
    </div>
  );
}

Explanation

• This hook returns a ref that you attach to the component (like a modal or dropdown).

• When a user clicks anywhere outside that element, the handler is triggered.

• Works with both mousedown and touchstart for cross-device support.

useCopyToClipboard

useCopyToClipboard hook provides an easy way to copy text to the user's clipboard and track whether the operation succeeded.

Import

import { useCopyToClipboard } from "fizzy-hooks";

Returns | Value | Type | Description | | --------- | ------------------------------------ | ---------------------------------------------------- | | copy | (text: string) => Promise<boolean> | Function to copy given text to clipboard | | success | boolean | true if the last copy was successful, else false |

import { useCopyToClipboard } from "fizzy-hooks";
import { useState } from "react";

function CopyExample() {
  const [text, setText] = useState("Hello world!");
  const { copy, success } = useCopyToClipboard();

  return (
    <div>
      <input
        value={text}
        onChange={(e) => setText(e.target.value)}
        placeholder="Enter text to copy"
      />
      <button onClick={() => copy(text)}>Copy</button>
      {success && <p style={{ color: "green" }}>Copied to clipboard!</p>}
    </div>
  );
}

Explanation

• The copy() function copies any string to the clipboard using the Clipboard API.

• The success state is set to true for 2 seconds after a successful copy.

• You can use success to show a confirmation or status message to the user.

useDebounce

useDebounce hook delays updating a value until after a specified wait time has passed without changes. This is useful for optimizing performance in input fields, search queries, or any value that changes rapidly.

Import

import { useDebounce } from "fizzy-hooks";

Parameters | Parameter | Type | Default | Description | | --------- | -------- | ------- | ------------------------------------- | | value | T | – | The input value to debounce | | delay | number | 500 | Time in milliseconds to delay updates |

Returns | Value | Type | Description | | ---------------- | ---- | --------------------------------- | | debouncedValue | T | The updated value after the delay |

Example

import { useEffect, useState } from "react";
import { useDebounce } from "fizzy-hooks";

function SearchInput() {
  const [query, setQuery] = useState("");
  const debouncedQuery = useDebounce(query, 300);

  useEffect(() => {
    if (debouncedQuery) {
      // Trigger API or search
    }
  }, [debouncedQuery]);

  return (
    <>
      <input
        type="text"
        placeholder="Search..."
        value={query}
        onChange={(e) => setQuery(e.target.value)}
      />

      <p>{debouncedQuery}</p>
    </>
  );
}

useDefault

useDefault hook helps you provide a fallback value when the current value is null, undefined, or deemed invalid by a custom validator. This is especially useful when working with user input, optional props, or external data that may not always be available.

Import

import { useDefault } from "fizzy-hooks";

Parameters

| Parameter | Type | Description | | ---------------------- | ----------------------- | ----------------------------------------------------------------------- | | value | T | The value to check and potentially replace | | defaultValue | T | The fallback value to use if value is invalid | | isInvalid (optional) | (value: T) => boolean | Optional custom validation function. Return true to use default value |

Returns | Value | Type | Description | | ---------------- | ---- | ------------------------------------------------- | | effectiveValue | T | Either the original value or the fallback default |

Example 1 – Basic Fallback

import { useDefault } from "fizzy-hooks";

function Username({ name }: { name?: string }) {
  const displayName = useDefault(name, "Guest");

  return <h2>Hello, {displayName}!</h2>;
}

If name is undefined, the hook returns "Guest" as the default.

Example 2 – Custom Validation

import { useDefault } from "fizzy-hooks";

function AgeDisplay({ age }: { age: number | null }) {
  const displayAge = useDefault(age, 18, (v) => v === null || v <= 0);

  return <p>Age: {displayAge}</p>;
}

If age is null or less than or equal to 0, the hook returns 18.

useDocumentTitle

useDocumentTitle hook allows you to dynamically set the browser tab's title from within a React component.

Import

import { useDocumentTitle } from "fizzy-hooks";

Parameters | Parameter | Type | Description | | --------- | -------- | ---------------------------------------- | | title | string | The title you want to display in the tab |

Example

import { useDocumentTitle } from "fizzy-hooks";

function AboutPage() {
  useDocumentTitle("About Us");

  return <h1>Welcome to the About Page</h1>;
}

When the AboutPage component mounts, the browser tab title will be set to "About Us". If the title changes (e.g., via props or state), it updates the title accordingly.

useEventListener

useEventListener is a flexible React hook that lets you add event listeners to various targets like window, document, or DOM elements (including React refs). It handles automatic cleanup and maintains a stable handler function.

Import

import { useEventListener } from "fizzy-hooks";

Parameters | Parameter | Type | Description | | ----------- | --------------------------------------------------------- | ---------------------------------------------------------------------- | | target | Window | Document | HTMLElement | RefObject<T> | The element or reference to attach the event listener to | | eventName | string | The name of the event to listen for (e.g., "click", "scroll") | | handler | (event: Event) => void | The callback function that will be invoked when the event is triggered | | options (optional) | boolean | AddEventListenerOptions | Optional options passed to addEventListener (e.g., { once: true }) |

Example 1 : Listen to window resize

import { useState } from "react";
import { useEventListener } from "fizzy-hooks";

function WindowResizeTracker() {
  const [size, setSize] = useState({
    width: window.innerWidth,
    height: window.innerHeight,
  });

  useEventListener("resize", () => {
    setSize({ width: window.innerWidth, height: window.innerHeight });
  });

  return (
    <p>
      Width: {size.width}, Height: {size.height}
    </p>
  );
}

Example 2 : Click outside an element

import { useRef } from "react";
import { useEventListener } from "fizzy-hooks";

function ClickOutsideAlert() {
  const boxRef = useRef<HTMLDivElement>(null);

  useEventListener(boxRef, "click", (e) => {
    console.log("Box clicked");
  });

  useEventListener(document, "click", (e) => {
    if (!boxRef.current?.contains(e.target as Node)) {
      alert("Clicked outside the box!");
    }
  });

  return (
    <div ref={boxRef} style={{ padding: 20, background: "#eee" }}>
      Click inside or outside
    </div>
  );
}

useFavicon

useFavicon hook allows you to dynamically update the favicon of your web page by setting a new image URL.

Import

import { useFavicon } from "fizzy-hooks";

Parameter | Parameter | Type | Description | | --------- | -------------- | -------------------------------------- | | href | string | The URL of the image to use as favicon |

Example

import { useFavicon } from "fizzy-hooks";

function FaviconExample() {
  useFavicon("https://example.com/my-icon.ico");

  return <p>The favicon should now be updated!</p>;
}

The hook checks if a <link rel="icon"> exists in the <head>. If it exists, it updates its href to the new favicon URL. If it doesn’t, it creates a new <link rel="icon"> element and appends it to the <head>. The update happens reactively every time the href value changes.

useFetch

useFetch hook is a simple and powerful way to fetch data from APIs in your React components. It handles loading, error, and success states, and also provides a refetch() method.

Import

import { useFetch } from "fizzy-hooks";

Parameters

| Name | Type | Description | | -------------- | ------------- | ---------------------------------------------------------------------- | | url | string | The endpoint URL to fetch data from. | | options | RequestInit | Optional fetch options (headers, method, body, etc). | | dependencies | any[] | Optional dependency array that triggers refetching when values change. |

Returns | Value | Type | Description | | ----------- | --------------------- | ------------------------------------------- | | data | T \| null | The response data after a successful fetch. | | loading | boolean | Indicates if the request is in progress. | | error | string \| null | Error message if the fetch fails. | | refetch() | function | Manually re-trigger the fetch operation. |

Example

import { useState } from "react";
import { useFetch } from "fizzy-hooks";

function FetchData() {
  const [id, setId] = useState(1);
  const { data, loading, error, refetch } = useFetch(
    `https://jsonplaceholder.typicode.com/users/${id}`,
    {
      method: "GET",
    },
    [id]
  );

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error: {error}</p>;

  return (
    <>
      <button onClick={() => setId((v) => v + 1)}>Next</button>
      <button
        onClick={() => {
          console.log("refetched");
          refetch();
        }}
      >
        Refetch
      </button>
      <div>
        <p>User ID: {data?.id}</p>
        <p>Name: {data?.name}</p>
        <p>Email: {data?.email}</p>
        <p>Username: {data?.username}</p>
      </div>
    </>
  );
}

useFetch automatically calls the API when the component mounts. You can pass any valid fetch options like headers or POST data.

If you want the fetch to re-run when certain values change (like query), pass them in the dependencies array.

Use refetch() manually to re-trigger the request