# ReactUse — Full Documentation (llms-full.txt)

Website: https://reactuse.com
GitHub: https://github.com/childrentime/reactuse
NPM: https://www.npmjs.com/package/@reactuses/core

ReactUse (@reactuses/core) is an open-source library of 110+ custom React Hooks for production applications. Hooks are TypeScript-first, tree-shakable, and SSR-compatible. Supports React 16.8 through React 19, Next.js, Remix, and other SSR frameworks.

This file inlines the full Markdown for every hook documentation page. Each hook section starts with the line "URL: https://reactuse.com/{category}/{hookname}/" so passages can be cited individually.

---

# State hooks (24)

## use

URL: https://reactuse.com/state/use/
Category: state
Description: use is a React hook that polyfills React 19's use() for v18 and below — resolve and consume promise state. For React 19 and above, use the built-in use hook.
Import: `import { use } from '@reactuses/core'`

# use

`use` is a polyfill hook to resolve promises state for React v18 and below. Note that it only implements the ability to consume promises.
For React v19 and above, you can use the built-in `use` hook: https://react.dev/reference/react/use

`use` accepts a `Usable<T>` (a promise or React context) and resolves it within a Suspense boundary. It tracks the thenable's status internally (`pending`, `fulfilled`, `rejected`) and throws the promise while pending so that a parent `<Suspense>` fallback is displayed. Once resolved, it returns the unwrapped value directly. This brings the React 19 `use` semantics to older React versions.

### When to Use

- Loading asynchronous data inside a component tree that already uses `<Suspense>` boundaries
- Migrating a codebase toward the React 19 `use` pattern while still supporting React 18
- Reading from a React context without the `useContext` hook for API consistency with future React versions

### Notes

- **Suspense required**: The component calling `use` must be wrapped in a `<Suspense>` boundary; otherwise the thrown promise will be unhandled.
- **Promise identity matters**: Pass a stable promise reference (e.g., created outside the render or memoized). Creating a new promise on every render will restart the loading cycle.
- **Limited scope**: This polyfill only supports promises and contexts. Other usable types that React 19 may support in the future are not covered.

## Usage

```tsx live noInline
const promise = new Promise((resolve) => {
  setTimeout(() => {
    resolve("resolved");
  }, 5000);
});

function Demo() {
  const data = use(promise);

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

render(
  <Suspense fallback="loading...">
    <Demo />
  </Suspense>
);

```

---

## useBoolean

URL: https://reactuse.com/state/useboolean/
Category: state
Description: useBoolean is a React hook to manage a boolean state with convenient setTrue, setFalse, and toggle helpers — no inline arrow functions needed.
Import: `import { useBoolean } from '@reactuses/core'`

# useBoolean

React state hook that manages a boolean value

`useBoolean` wraps a boolean state and returns an object with the current `value` along with convenience methods: `setValue`, `setTrue`, `setFalse`, and `toggle`. This avoids the need to write inline arrow functions like `() => setState(true)` throughout your components. The hook accepts an optional initial value that defaults to `false`.

### When to Use

- Controlling visibility of modals, drawers, tooltips, or other disclosure UI with explicit `setTrue`/`setFalse` semantics
- Managing feature flags or on/off states where named helpers improve readability over raw `useState`
- Any scenario where you want a richer API than a plain `[boolean, setter]` tuple

### Notes

- **SSR-safe**: Uses only React state internally, so it works identically on server and client.
- **Object return**: Unlike `useToggle` which returns a tuple, `useBoolean` returns a named object, making it easier to destructure only the methods you need.
- See also `useToggle` for a minimal tuple-based boolean hook and `useDisclosure` for modal-oriented open/close patterns with callback support.

## Usage

```tsx live
function Demo() {
  const { value, setValue, setTrue, setFalse, toggle } = useBoolean(false);

  return (
    <div>
      <p>Current value: <strong>{value ? 'True' : 'False'}</strong></p>
      <div style={{ marginBottom: 16 }}>
        <button
          type="button"
          onClick={() => setValue(true)}
          style={{ marginRight: 8 }}
          disabled={value}
        >
          Set True
        </button>
        <button
          type="button"
          onClick={() => setValue(false)}
          style={{ marginRight: 8 }}
          disabled={!value}
        >
          Set False
        </button>
        <button
          type="button"
          onClick={setTrue}
          style={{ marginRight: 8 }}
          disabled={value}
        >
          setTrue()
        </button>
        <button
          type="button"
          onClick={setFalse}
          style={{ marginRight: 8 }}
          disabled={!value}
        >
          setFalse()
        </button>
        <button
          type="button"
          onClick={toggle}
          style={{ marginRight: 8 }}
        >
          Toggle
        </button>
      </div>
      <div>
        <p>Status: {value ? '✅ Enabled' : '❌ Disabled'}</p>
      </div>
    </div>
  );
};
```

---

## useControlled

URL: https://reactuse.com/state/usecontrolled/
Category: state
Description: useControlled is a React hook for components that work as both controlled and uncontrolled — returns a useState-like tuple that mirrors props or internal state.
Import: `import { useControlled } from '@reactuses/core'`

# useControlled

`useControlled` is a custom hook that helps you manage controlled components. It is a wrapper around `useState` that allows you to control the value of a component from the outside.

`useControlled` returns a `[value, setValue]` tuple that behaves like `useState` when the first argument is `undefined` (uncontrolled mode), or mirrors the provided value when it is defined (controlled mode). An optional `onChange` callback is invoked whenever the value changes. This pattern is essential for building components that need to work both as controlled and uncontrolled inputs.

### When to Use

- Building reusable form components (inputs, selects, sliders) that must support both controlled and uncontrolled usage
- Wrapping third-party components that require a controlled interface while still providing a sensible uncontrolled default
- Implementing component libraries where consumers decide whether to own the state or let the component manage it

### Notes

- **No mode switching**: The hook does not support switching between controlled and uncontrolled modes after initial mount. Choose one mode at creation time.
- **No function updater**: Unlike `useState`, the setter does not accept a `(prev) => next` function form. Pass values directly.
- See also `useSetState` for a class-component-style partial state updater.

:::note
The `useControlled` component does not support switching between controlled and uncontrolled modes, nor does it support passing a function for state updates. You can refer to this discussion for more information: https://github.com/adobe/react-spectrum/issues/2320.
:::

## Usage

```tsx live
function Demo() {
  const [state, setState] = useState<string>("");
  const [value, setValue] = useControlled(state, "");
  const [value1, setValue1] = useControlled(undefined, "unControlled value");

  const handleChange = (event) => {
    setState(event.target.value);
  };

  const handleChange1 = (event) => {
    setValue1(event.target.value);
  };

  return (
    <>
      <input value={value} onChange={handleChange} />
      <p>Controlled Value: {value}</p>
      <input value={value1} onChange={handleChange1} />
    </>
  );
};

```

---

## useCookie

URL: https://reactuse.com/state/usecookie/
Category: state
Description: useCookie is a React hook to store, update, and delete a browser cookie by key — returns the value plus update and refresh functions, with js-cookie options.
Import: `import { useCookie } from '@reactuses/core'`

# useCookie

React hook that facilitates the storage, updating and deletion of values within the CookieStore

`useCookie` manages a single browser cookie by key. It returns a tuple of `[cookieValue, updateCookie, refreshCookie]`. Call `updateCookie` with a string to set the cookie or with `undefined` to delete it. The `refreshCookie` function re-reads the cookie from the store, which is useful when the cookie may have been modified externally. Options are passed through to `js-cookie` for controlling path, domain, expiration, and other cookie attributes.

### When to Use

- Persisting user preferences (locale, theme, consent flags) in cookies for server-side access
- Reading and writing authentication or session tokens stored in cookies
- Synchronizing cookie state in a component when external code (analytics, third-party scripts) may also modify the cookie

### Notes

- **SSR considerations**: Pass a `defaultValue` when using SSR so the hook has a value before `document.cookie` is available on the client.
- **Same-tab sync**: Updating a cookie in one component automatically re-renders sibling `useCookie` instances using the same key in the same tab. Cookies fire no native cross-tab event, so this does **not** propagate across tabs (unlike `useLocalStorage`/`useSessionStorage`).
- **`refreshCookie`**: Only needed to pick up changes made *outside* the hook — a server `Set-Cookie`, a direct `document.cookie` write, or the CookieStore API. Sibling hook instances no longer need it.

:::note
`useCookie` instances that share the same key stay in sync within the same tab:
calling `updateCookie` in one component re-renders the others automatically. (Earlier
versions did not — a manual broadcast was required; that is no longer necessary.)
:::

## Usage

```tsx live
function Demo() {
  const defaultOption = {
    path: "/",
  };

  const cookieName = "cookie-key";
  const [cookieValue, updateCookie, refreshCookie] = useCookie(
    cookieName,
    defaultOption,
    "default-value"
  );

  const updateButtonClick = () => {
    updateCookie("new-cookie-value");
  };

  const deleteButtonClick = () => {
    updateCookie(undefined);
  };

  const change = () => {
    if ("cookieStore" in window) {
      const store = window.cookieStore as any;
      store.set({ name: cookieName, value: "changed" });
    } else {
      document.cookie = `${cookieName}=changed; path=/`;
    }
  };

  return (
    <div>
      <p>Click on the button to update or clear the cookie</p>
      <p color="blue">cookie: {cookieValue || "no value"}</p>
      <button onClick={updateButtonClick}>Update the cookie</button>
      <button onClick={deleteButtonClick}>Clear the cookie</button>
      <button onClick={change}>
        Changing the cookie through other methods
      </button>
      <button onClick={refreshCookie}>Refresh the cookie</button>
    </div>
  );
};

```

## Same-tab sync

Two components using the same cookie key stay in sync within the tab — click a button in either panel and the other updates immediately, no manual broadcast and no reload:

```tsx live noInline
function CookiePanel({ label }) {
  const [value, updateCookie] = useCookie("shared-demo-cookie", { path: "/" }, "A");
  return (
    <div
      style={{
        border: "1px solid var(--sl-color-gray-5, #ccc)",
        borderRadius: 6,
        padding: 12,
        marginBottom: 8,
      }}
    >
      <strong>{label}</strong> reads: <code>{value ?? "(empty)"}</code>
      <div style={{ display: "flex", gap: 8, marginTop: 8 }}>
        <button onClick={() => updateCookie("A")}>Set A</button>
        <button onClick={() => updateCookie("B")}>Set B</button>
        <button onClick={() => updateCookie("C")}>Set C</button>
        <button onClick={() => updateCookie(undefined)}>Clear</button>
      </div>
    </div>
  );
}

function Demo() {
  return (
    <div>
      <p>Click a button in either panel — the other updates in the same tab:</p>
      <CookiePanel label="Component A" />
      <CookiePanel label="Component B" />
    </div>
  );
}

render(<Demo />);
```

---

## useCountDown

URL: https://reactuse.com/state/usecountdown/
Category: state
Description: useCountDown is a React hook that counts down from a duration in seconds — returns formatted hour, minute, and second strings and fires a callback at zero.
Import: `import { useCountDown } from '@reactuses/core'`

# useCountDown

React State Hooks that return the minutes gracefull

`useCountDown` accepts a duration in seconds and returns a `[hour, minute, second]` tuple of formatted strings that update every second. An optional `format` function lets you customize the string formatting, and an optional `callback` is invoked when the countdown reaches zero. The hook handles the interval lifecycle automatically, cleaning up on unmount.

### When to Use

- Displaying countdown timers for sales, events, or limited-time offers
- Building exam or quiz timers that trigger an action when time expires
- Showing time remaining until a scheduled event (e.g., midnight, a launch date)

### Notes

- **SSR compatibility**: When rendering on the server, ensure the initial `time` value is computed identically on both server and client to avoid hydration mismatches. The demo uses `suppressHydrationWarning` for this reason.
- **Custom formatting**: The default format produces `HH:MM:SS` strings. Pass a custom `format` function to change the output (e.g., zero-padding, localized labels).
- **Completion callback**: The optional third argument fires once when the countdown reaches zero, useful for redirects, alerts, or state transitions.

## Usage

```tsx live
function Demo() {
  const now = new Date();
  const tomorrow = new Date();
  tomorrow.setDate(now.getDate() + 1);
  tomorrow.setHours(0, 0, 0, 0);
  const diffInSec = Math.floor((tomorrow.getTime() - now.getTime()) / 1000);

  // note: If your app is running in server side, must pass the same time as the client
  // this demo is not running in server side
  const [hour, minute, second] = useCountDown(diffInSec);
  return (
    <div suppressHydrationWarning={true}>{`${hour}:${minute}:${second}`}</div>
  );
};

```

---

## useCounter

URL: https://reactuse.com/state/usecounter/
Category: state
Description: useCounter is a React hook to manage a numeric counter with inc, dec, set, and reset helpers and optional min and max clamping.
Import: `import { useCounter } from '@reactuses/core'`

# useCounter

React state hook that tracks a numeric value

`useCounter` manages an integer counter with built-in `inc`, `dec`, `set`, and `reset` functions. It returns a tuple of `[current, set, inc, dec, reset]`. You can optionally specify `max` and `min` bounds; the counter will be clamped to stay within those limits. The initial value defaults to `0` and can be a number or a function returning a number.

### When to Use

- Implementing quantity selectors, pagination controls, or stepper inputs
- Tracking scores, votes, or item counts with enforced minimum/maximum boundaries
- Any numeric state that benefits from dedicated increment, decrement, and reset actions

### Notes

- **Bounded values**: When `max` or `min` is provided, the counter is clamped after every operation. Setting a value outside the bounds will be silently adjusted.
- **SSR-safe**: Uses only React state internally with no browser API dependencies.
- See also `useCycleList` for cycling through a fixed list of items rather than an open numeric range.

## Usage

```tsx live
function Demo() {
  const [current, set, inc, dec, reset] = useCounter(10, 100, 1);

  return (
    <div>
      <p>{current} max: 100; min: 1;</p>
      <div>
        <button
          type="button"
          onClick={() => {
            inc();
          }}
          style={{ marginRight: 8 }}
        >
          inc()
        </button>
        <button
          type="button"
          onClick={() => {
            dec();
          }}
          style={{ marginRight: 8 }}
        >
          dec()
        </button>
        <button
          type="button"
          onClick={() => {
            set(3);
          }}
          style={{ marginRight: 8 }}
        >
          set(3)
        </button>
        <button type="button" onClick={reset} style={{ marginRight: 8 }}>
          reset()
        </button>
      </div>
    </div>
  );
};

```

---

## useCycleList

URL: https://reactuse.com/state/usecyclelist/
Category: state
Description: useCycleList is a React hook to cycle through a list of items — returns the current item plus next and prev functions with wraparound behavior.
Import: `import { useCycleList } from '@reactuses/core'`

# useCycleList

Cycle through a list of items

`useCycleList` takes an array of items and returns a tuple of `[currentItem, next, prev]`. Calling `next()` advances to the next item in the list, wrapping around to the beginning when the end is reached. Calling `prev()` moves backward with the same wraparound behavior. You can optionally pass a starting index and also jump by more than one step by passing an offset to `next` or `prev`.

### When to Use

- Cycling through theme options, color schemes, or display modes
- Building carousels or slideshows that loop through a set of items
- Rotating through a list of predefined values (e.g., font sizes, sort orders)

### Notes

- **Generic type**: The hook is fully generic; the list can contain any type (strings, numbers, objects, etc.).
- **SSR-safe**: Uses only React state with no browser API dependencies.
- See also `useCounter` for cycling through a numeric range with min/max bounds.

## Usage

```tsx live
function Demo() {
  const [state, next, prev] = useCycleList([
    "Dog",
    "Cat",
    "Lizard",
    "Shark",
    "Whale",
    "Dolphin",
    "Octopus",
    "Seal",
  ]);

  return (
    <div>
      <div>{state}</div>
      <div>
        <button onClick={() => next()}>next</button>
        <button onClick={() => prev()}>prev</button>
      </div>
    </div>
  );
};

```

---

## useDebounce

URL: https://reactuse.com/state/usedebounce/
Category: state
Description: useDebounce is a React hook that returns a debounced copy of a value — updates only after the input stops changing for the given delay.
Import: `import { useDebounce } from '@reactuses/core'`

# useDebounce

React hooks that [debounce](https://lodash.com/docs/4.17.15#debounce) value

`useDebounce` accepts a value and a wait time in milliseconds, and returns a debounced version of that value. The returned value only updates after the specified delay has elapsed since the last change to the input value. Under the hood it uses `lodash.debounce`, so you can pass the same options (`leading`, `trailing`, `maxWait`) for fine-grained control.

### When to Use

- Delaying search input to avoid firing API requests on every keystroke
- Throttling expensive re-renders triggered by rapidly changing values (e.g., window resize dimensions)
- Smoothing out form validation so error messages do not flicker while the user is still typing

### Notes

- **Value-level debounce**: This hook debounces the *value* itself, not a callback. If you need to debounce a function, use `useDebounceFn` instead.
- **Options passthrough**: The third argument is forwarded directly to `lodash.debounce`, supporting `leading`, `trailing`, and `maxWait`.
- See also `useThrottle` for rate-limiting value updates at a fixed interval rather than delaying until idle.

## Usage

```tsx live
function Demo() {
  const [value, setValue] = useState<string>("");
  const debouncedValue = useDebounce(value, 500);

  return (
    <div>
      <input
        value={value}
        onChange={e => setValue(e.target.value)}
        placeholder="Typed value"
        style={{ width: 280 }}
      />
      <p style={{ marginTop: 16 }}>DebouncedValue: {debouncedValue}</p>
    </div>
  );
};

```

---

## useDisclosure

URL: https://reactuse.com/state/usedisclosure/
Category: state
Description: useDisclosure is a React hook for disclosure widgets like modals and dropdowns — manages open and close state with controlled and uncontrolled modes.
Import: `import { useDisclosure } from '@reactuses/core'`

# useDisclosure

`useDisclosure` is a hook that provides all the tools you need to create a disclosure widget. Disclosure widgets are used to show or hide content. This hook provides the state and functions to control the visibility of the content.

`useDisclosure` returns an object with `isOpen`, `onOpen`, `onClose`, and `onOpenChange` along with an `isControlled` flag. It supports both controlled mode (pass `isOpen` via props) and uncontrolled mode (uses internal state with an optional `defaultOpen`). Callbacks for `onOpen`, `onClose`, and `onChange` can be provided in the props to run side effects when the state transitions.

### When to Use

- Managing modal, dialog, or drawer open/close state with lifecycle callbacks
- Building collapsible panels, accordions, or expandable sections
- Any disclosure pattern where you need both controlled and uncontrolled support with open/close event hooks

### Notes

- **Controlled and uncontrolled**: Pass `isOpen` in props for controlled mode. Omit it (or leave it `undefined`) for uncontrolled mode with optional `defaultOpen`.
- **Callback support**: Unlike simpler boolean hooks, `useDisclosure` accepts `onOpen`, `onClose`, and `onChange` callbacks, making it well-suited for side effects like analytics or focus management.
- See also `useBoolean` for a simpler boolean state hook without callbacks, and `useToggle` for a minimal tuple-based toggle.

## Usage

```tsx live
function Demo() {
  const { isOpen, onOpen, onClose } = useDisclosure();

  return (
    <>
      <button onClick={onOpen}>Open</button>
      <button onClick={onClose}>Close</button>
      <p>{isOpen ? "Open" : "Close"}</p>
    </>
  );
};

```

---

## useFirstMountState

URL: https://reactuse.com/state/usefirstmountstate/
Category: state
Description: useFirstMountState is a React hook that returns true on the initial render and false on every render after — synchronous, with no extra re-render.
Import: `import { useFirstMountState } from '@reactuses/core'`

# useFirstMountState

React state hook that returns true if component is just mounted

`useFirstMountState` returns `true` during the component's initial render and `false` on all subsequent renders. It uses a ref internally so the check is synchronous and does not trigger additional re-renders. This is useful for skipping logic that should only run after the first paint or for distinguishing the initial mount from updates.

### When to Use

- Skipping animations or transitions on the very first render so the component appears instantly
- Conditionally running effect logic only on updates (not on mount) by combining with `useEffect`
- Displaying "new" or "just loaded" indicators that disappear after the first re-render

### Notes

- **Synchronous check**: The returned value is available immediately during render, not deferred to an effect.
- **SSR-safe**: Works identically on server and client since it only uses a React ref internally.
- See also `useMountedState` for a function-based approach that checks whether the component is currently mounted (as opposed to whether it is on its *first* render).

## Usage

```tsx live
function Demo() {
  const isFirstMount = useFirstMountState();
  const [render, reRender] = useState(0);

  return (
    <div>
      <span>This component is just mounted: {isFirstMount ? "YES" : "NO"}</span>
      <br />
      <button onClick={() => reRender(1)}>{render}</button>
    </div>
  );
};

```

---

## useHover

URL: https://reactuse.com/state/usehover/
Category: state
Description: useHover is a React hook that returns whether the mouse is hovering over a referenced element, via mouseenter and mouseleave listeners.
Import: `import { useHover } from '@reactuses/core'`

# useHover

Detect if mouse is over given element.

`useHover` accepts a ref to a DOM element and returns a boolean indicating whether the mouse is currently hovering over that element. It attaches `mouseenter` and `mouseleave` event listeners internally and cleans them up on unmount. The returned value updates reactively, triggering a re-render whenever the hover state changes.

### When to Use

- Showing tooltips, popovers, or contextual information when the user hovers over an element
- Highlighting or enlarging UI elements on hover without CSS-only solutions (e.g., when you need to trigger side effects)
- Conditionally rendering content or fetching data based on hover intent

### Notes

- **Ref-based target**: Pass a React ref object. The hook handles attaching and detaching event listeners automatically.
- **Mouse only**: This hook tracks mouse events (`mouseenter`/`mouseleave`). It does not detect touch-based hover on mobile devices.
- See also `useTextSelection` for tracking what the user has selected, or the browser-category hooks for other pointer-related utilities.

## Usage

```tsx live
function Demo() {
  const ref = useRef<HTMLDivElement>(null);
  const hovered = useHover(ref);
  return <div ref={ref}> {hovered ? "true" : "false"}</div>;
};

```

---

## useLatest

URL: https://reactuse.com/state/uselatest/
Category: state
Description: useLatest is a React hook that returns a ref to the latest value — access current props or state inside async callbacks without stale closures.
Import: `import { useLatest } from '@reactuses/core'`

# useLatest

React state hook that returns the latest state as described in the [React hooks FAQ](https://reactjs.org/docs/hooks-faq.html#why-am-i-seeing-stale-props-or-state-inside-my-function).

This is mostly useful to get access to the latest value of some props or state inside an asynchronous callback, instead of that value at the time the callback was created from.

`useLatest` accepts any value and returns a `MutableRefObject` whose `.current` property always holds the most recent value. The ref is updated synchronously on every render, so reading `ref.current` inside timeouts, intervals, or event handlers always gives you the up-to-date value rather than a stale closure capture.

### When to Use

- Accessing the latest state or props inside `setTimeout`, `setInterval`, or other asynchronous callbacks
- Avoiding stale closures in event handlers that are registered once but need to reference changing values
- Passing the latest value into imperative code (e.g., third-party library callbacks) without re-registering listeners

### Notes

- **Not a state hook**: The returned ref does not trigger re-renders when updated. It is meant to be read inside callbacks, not used as a render dependency.
- **SSR-safe**: Uses only a React ref internally with no browser dependencies.
- See also `usePrevious` for tracking the value from the prior render rather than the current one.

## Usage

```tsx live
function Demo() {
  const [count, setCount] = useState(0);
  const latestCount = useLatest(count);
  const handleAlertClick = () => {
    setTimeout(() => {
      alert(`Latest count value: ${latestCount.current}`);
    }, 3000);
  };

  return (
    <div>
      <p>You clicked {count} times</p>
      <button onClick={() => setCount(count + 1)}>Click me</button>
      <button onClick={handleAlertClick}>Show alert</button>
    </div>
  );
};

```

---

## useLocalStorage

URL: https://reactuse.com/state/uselocalstorage/
Category: state
Description: useLocalStorage is a React hook that binds state to a localStorage key — a useState-like tuple with SSR safety, custom serializers, and cross-tab sync.
Import: `import { useLocalStorage } from '@reactuses/core'`

# useLocalStorage

React side-effect hook that manages a single `localStorage` key

`useLocalStorage` binds a React state to a `localStorage` key. It returns a `[value, setValue]` tuple similar to `useState`. The value is read from storage on mount and written back whenever you call `setValue`. Setting the value to `null` removes the key. Custom serializers can be provided for non-string data types, and the hook listens for cross-tab `storage` events by default so that changes in one tab are reflected in others.

### When to Use

- Persisting user preferences (theme, language, layout) across page reloads
- Caching form drafts or application state so users can resume where they left off
- Sharing simple state between browser tabs via the `storage` event

### Notes

- **Persistence**: Data survives page reloads and browser restarts. Use `useSessionStorage` if you only need data for the current session.
- **Cross-tab & same-tab sync**: Every component bound to the same key stays in sync — within the current tab (always on, no reload) and across other tabs (via the `storage` event). `listenToStorageChanges: false` disables only the cross-tab listener; same-tab sync stays active.
- **Custom serialization**: For objects or non-string values, provide `serializer.read` and `serializer.write` functions in the options. The default behavior uses JSON serialization for objects and raw strings for string values.
- See also `useSessionStorage` for session-scoped storage and `useCookie` for cookie-based persistence.

## Usage

```tsx live
function Demo() {
  // bind string
  const [value, setValue] = useLocalStorage("my-key", "key");
  
  // bind object with custom serializer
  const [myObj, setMyObj] = useLocalStorage(
    "myObj",
    {
      name: "test",
    },
    {
      serializer: {
        read: (val) => {
          console.log("read", val);
          return JSON.parse(val);
        },
        write: (val) => {
          console.log("write", val);
          return JSON.stringify(val);
        },
      },
    }
  );

  return (
    <div>
      <div>
        <h3>String Value</h3>
        <div>Value: {value}</div>
        <button onClick={() => setValue("bar")}>Set to "bar"</button>
        <button onClick={() => setValue("baz")}>Set to "baz"</button>
        <button onClick={() => setValue(null)}>Remove</button>
      </div>
      
      <div style={{ marginTop: "20px" }}>
        <h3>Object Value</h3>
        <div>Object: {JSON.stringify(myObj)}</div>
        <button onClick={() => setMyObj({ name: "updated" })}>
          Update Object
        </button>
        <button onClick={() => setMyObj({ name: "test", count: 1 })}>
          Add Property
        </button>
        <button onClick={() => setMyObj(null)}>Remove Object</button>
      </div>
    </div>
  );
};

```

## Same-tab sync

Two components bound to the same key stay in sync within the tab — not just across tabs. Click a button in one panel and the other updates immediately, no reload:

```tsx live noInline
function StoragePanel({ label }) {
  const [value, setValue] = useLocalStorage("shared-demo-key", "A");
  return (
    <div
      style={{
        border: "1px solid var(--sl-color-gray-5, #ccc)",
        borderRadius: 6,
        padding: 12,
        marginBottom: 8,
      }}
    >
      <strong>{label}</strong> reads: <code>{String(value ?? "(empty)")}</code>
      <div style={{ display: "flex", gap: 8, marginTop: 8 }}>
        <button onClick={() => setValue("A")}>Set A</button>
        <button onClick={() => setValue("B")}>Set B</button>
        <button onClick={() => setValue(null)}>Clear</button>
      </div>
    </div>
  );
}

function Demo() {
  return (
    <div>
      <p>Click a button in one panel — the other updates in the same tab:</p>
      <StoragePanel label="Component A" />
      <StoragePanel label="Component B" />
    </div>
  );
}

render(<Demo />);
```

---

## useMap

URL: https://reactuse.com/state/usemap/
Category: state
Description: useMap is a React hook to manage a JavaScript Map in state — exposes set, get, remove, has, clear, and reset methods that trigger re-renders automatically.
Import: `import { useMap } from '@reactuses/core'`

# useMap

React state hook that manages a Map

`useMap` wraps a JavaScript `Map` in React state and exposes a rich set of methods: `set`, `get`, `remove`, `has`, `clear`, and `reset`, along with the current `map` instance and its `size`. Mutations through these methods trigger re-renders automatically. The initial value can be a `Map` instance, an array of key-value pairs, or a factory function.

### When to Use

- Managing key-value collections (e.g., selected items, tag mappings, lookup tables) that change frequently
- Building dynamic forms or configuration editors where entries are added and removed at runtime
- Any scenario where you need `Map` semantics (ordered keys, non-string keys) with reactive state updates

### Notes

- **Immutable updates**: Each mutation creates a new `Map` instance internally so React detects the state change and re-renders.
- **Reset support**: The `reset` function restores the map to its initial value, which is useful for "undo" or "clear filters" actions.
- **SSR-safe**: Uses only React state internally with no browser API dependencies.

## Usage

```tsx live
function Demo() {
  const { map, set, get, remove, has, clear, reset, size } = useMap([
    ['react', '18.0.0'],
    ['vue', '3.0.0'],
  ]);

  return (
    <div>
      <p>Map size: {size}</p>
      <div style={{ marginBottom: 16 }}>
        <button
          type="button"
          onClick={() => set('angular', '16.0.0')}
          style={{ marginRight: 8 }}
        >
          Add Angular
        </button>
        <button
          type="button"
          onClick={() => set('react', '18.2.0')}
          style={{ marginRight: 8 }}
        >
          Update React
        </button>
        <button
          type="button"
          onClick={() => remove('vue')}
          style={{ marginRight: 8 }}
        >
          Remove Vue
        </button>
        <button
          type="button"
          onClick={clear}
          style={{ marginRight: 8 }}
        >
          Clear All
        </button>
        <button
          type="button"
          onClick={reset}
          style={{ marginRight: 8 }}
        >
          Reset
        </button>
      </div>
      <div>
        <p>Current entries:</p>
        <ul>
          {Array.from(map.entries()).map(([key, value]) => (
            <li key={key}>
              {key}: {value} 
              {has(key) && ' ✓'}
            </li>
          ))}
        </ul>
      </div>
      <div>
        <p>Get React version: {get('react') || 'Not found'}</p>
      </div>
    </div>
  );
};
```

---

## useMergedRefs

URL: https://reactuse.com/state/usemergedrefs/
Category: state
Description: useMergedRefs is a React hook that merges multiple refs into a single callback ref — attach more than one ref to the same DOM node with a stable ref.
Import: `import { useMergedRefs } from '@reactuses/core'`

# useMergedRefs

`useMergedRefs` is a hook that merges multiple refs into a single ref. Use this hook when you need to use more than one ref on a single dom node.

`useMergedRefs` accepts any number of refs (callback refs, `RefObject`s, or `undefined`) and returns a single callback ref that forwards the DOM node to all of them. This eliminates the need to manually synchronize multiple refs on the same element. The returned ref is stable and handles both ref objects and callback refs uniformly.

### When to Use

- Combining a forwarded ref from `React.forwardRef` with an internal ref used by another hook (e.g., `useHover`, `useFocus`)
- Attaching multiple independent behaviors (measurement, intersection observation, drag handling) to the same DOM element
- Building compound components or component libraries where both the library and the consumer need ref access

### Notes

- **Handles all ref types**: Works with `RefObject`, callback refs, and `undefined` values seamlessly.
- **SSR-safe**: The returned callback ref does not access any browser APIs on its own.
- See also `useHover` and other element hooks that accept refs, which can be combined via `useMergedRefs`.

## Usage

```tsx live noInline
function Demo() {
  const hoverRef = useRef(null);
  const buttonRef = useRef<HTMLButtonElement>(null);
  const isHovered = useHover(hoverRef);
  const [isFocused, toggleFocus] = useToggle(false);

  const mergedRef = useMergedRefs(hoverRef, buttonRef);

  useEffect(() => {
    const handleKeyPress = (event) => {
      if (event.key === 'f' || event.key === 'F') {
        buttonRef.current?.focus();
      }
    };

    window.addEventListener('keypress', handleKeyPress);

    return () => {
      window.removeEventListener('keypress', handleKeyPress);
    };
  }, []);

  const handleFocus = () => toggleFocus(true);
  const handleBlur = () => toggleFocus(false);

  return (
    <div>
      <button
        ref={mergedRef}
        onFocus={handleFocus}
        onBlur={handleBlur}
        style={{
          padding: '10px 20px',
          backgroundColor: isHovered ? 'lightblue' : isFocused ? 'lightyellow' : 'white',
          border: '1px solid black',
          cursor: 'pointer',
          outline: isFocused ? '2px solid blue' : 'none',
        }}
      >
        {isHovered ? 'Hovered!' : isFocused ? 'Focused!' : 'Hover or Focus me'}
      </button>
      <p>Press 'F' key to focus the button</p>
    </div>
  );
};

render(<Demo/>);

```

---

## useMountedState

URL: https://reactuse.com/state/usemountedstate/
Category: state
Description: useMountedState is a React hook that returns a function to check whether the component is still mounted — guard against state updates after unmount.
Import: `import { useMountedState } from '@reactuses/core'`

# useMountedState

Lifecycle hook providing ability to check component's mount state.
Returns a function that will return `true` if component mounted and `false` otherwise

`useMountedState` returns a function (not a value) that you can call at any time to check whether the component is still mounted. This is particularly useful inside asynchronous operations where you need to guard against setting state on an unmounted component. The function is stable across re-renders and always reflects the current mount status.

### When to Use

- Guarding `setState` calls inside async operations (`fetch`, `setTimeout`) to prevent "state update on unmounted component" warnings
- Conditionally executing cleanup or follow-up logic only if the component is still in the DOM
- Implementing safe polling or subscription patterns that should stop when the component unmounts

### Notes

- **Function return**: Unlike `useFirstMountState` which returns a boolean, this hook returns a *function* that returns a boolean. Call it (`isMounted()`) to get the current status.
- **SSR-safe**: The function returns `false` during server-side rendering and becomes `true` after the component mounts on the client.
- See also `useFirstMountState` for detecting only the initial mount rather than ongoing mount status.

## Usage

```tsx live
function Demo() {
  const isMounted = useMountedState();

  const [, update] = useState(0);
  useEffect(() => {
    update(1);
  }, []);
  return <div>This component is {isMounted() ? "MOUNTED" : "NOT MOUNTED"}</div>;
};

```

---

## usePrevious

URL: https://reactuse.com/state/useprevious/
Category: state
Description: usePrevious is a React hook that returns a value from the previous render — useful for comparing the current and prior state or props.
Import: `import { usePrevious } from '@reactuses/core'`

# usePrevious

React state hook that returns the previous state as described in the [React Docs](https://react.dev/reference/react/useState#storing-information-from-previous-renders)

`usePrevious` accepts a value and returns the value from the previous render. On the initial render it returns `undefined` since there is no prior value. The hook stores the previous value in a ref and updates it after each render, giving you a snapshot of what the value was before the most recent change.

### When to Use

- Comparing current and previous values to trigger animations, transitions, or conditional logic
- Detecting direction of change (e.g., whether a counter increased or decreased)
- Implementing undo functionality or displaying "changed from X to Y" indicators

### Notes

- **Initial value**: Returns `undefined` on the first render. Type the result as `T | undefined` accordingly.
- **SSR-safe**: Uses only a React ref internally with no browser dependencies.
- See also `useLatest` for accessing the *current* (most recent) value inside callbacks without stale closures.

## Usage

```tsx live
function Demo() {
  const [count, setCount] = useState(0);
  const prevCount = usePrevious(count);

  return (
    <div>
      <button onClick={() => setCount(count + 1)}>+</button>
      <button onClick={() => setCount(count - 1)}>-</button>
      <p>
        Now: {count}, before: {prevCount}
      </p>
    </div>
  );
};

```

---

## useRafState

URL: https://reactuse.com/state/userafstate/
Category: state
Description: useRafState is a React hook with the same API as useState that defers updates to the next animation frame — batches high-frequency changes.
Import: `import { useRafState } from '@reactuses/core'`

# useRafState

React state hook that only updates state in the callback of [requestAnimationFrame](https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame)

`useRafState` has the same API as `useState` but defers state updates to the next animation frame via `requestAnimationFrame`. This batches rapid state changes (such as those from mouse or scroll events) into a single update per frame, reducing unnecessary re-renders and improving performance for high-frequency updates.

### When to Use

- Tracking mouse position, scroll offset, or window dimensions where events fire far more often than the screen refreshes
- Smoothing out state updates from sensors or streams that produce data faster than 60fps
- Reducing render overhead for any state that changes very rapidly and is used primarily for visual output

### Notes

- **Browser-only**: `requestAnimationFrame` is not available during SSR. The hook still works, but updates will not be batched on the server.
- **Same API as useState**: The returned tuple is `[state, setState]` with the same `SetStateAction<S>` signature, so it is a drop-in replacement.
- **Automatic cleanup**: Pending animation frame requests are cancelled on unmount to prevent memory leaks.

## Usage

```tsx live
function Demo() {
  const [state, setState] = useRafState({ x: 0, y: 0 });

  useMount(() => {
    const onMouseMove = (event: MouseEvent) => {
      setState({ x: event.clientX, y: event.clientY });
    };
    const onTouchMove = (event: TouchEvent) => {
      setState({
        x: event.changedTouches[0].clientX,
        y: event.changedTouches[0].clientY,
      });
    };

    document.addEventListener("mousemove", onMouseMove);
    document.addEventListener("touchmove", onTouchMove);

    return () => {
      document.removeEventListener("mousemove", onMouseMove);
      document.removeEventListener("touchmove", onTouchMove);
    };
  });

  return <pre>{JSON.stringify(state, null, 2)}</pre>;
};

```

---

## useSessionStorage

URL: https://reactuse.com/state/usesessionstorage/
Category: state
Description: useSessionStorage is a React hook that binds state to a sessionStorage key — a useState-like tuple with SSR safety, custom serializers, and cross-tab sync.
Import: `import { useSessionStorage } from '@reactuses/core'`

# useSessionStorage

React side-effect hook that manages a single `sessionStorage` key

`useSessionStorage` binds a React state to a `sessionStorage` key. It returns a `[value, setValue]` tuple that behaves like `useState`. The value is read from session storage on mount and written back on updates. Setting the value to `null` removes the key. Like `useLocalStorage`, it supports custom serializers and listens for cross-tab `storage` events by default.

### When to Use

- Storing temporary state that should persist across page navigations within the same tab but not across browser restarts
- Keeping wizard or multi-step form progress that resets when the user closes the tab
- Caching data that is sensitive or session-specific (e.g., one-time tokens, temporary filters)

### Notes

- **Session-scoped**: Unlike `localStorage`, data in `sessionStorage` is cleared when the tab or browser is closed. Use `useLocalStorage` for long-lived persistence.
- **Same-tab sync**: Components bound to the same key in one tab stay in sync — updating one re-renders the others without a reload. (`sessionStorage` is per-tab, so this does not cross tabs.) The cross-tab `storage` listener is on by default; disable it with `listenToStorageChanges: false`.
- **Custom serialization**: Provide `serializer.read` and `serializer.write` in the options for non-string data types.
- See also `useLocalStorage` for persistent storage and `useCookie` for cookie-based persistence.

## Usage

```tsx live
function Demo() {
  // bind string
  const [value, setValue] = useSessionStorage("my-key", "key");

  return (
    <div>
      <div>Value: {value}</div>
      <button onClick={() => setValue("bar")}>bar</button>
      <button onClick={() => setValue("baz")}>baz</button>
      {/* delete data from storage */}
      <button onClick={() => setValue(null)}>Remove</button>
    </div>
  );
};

```

---

## useSetState

URL: https://reactuse.com/state/usesetstate/
Category: state
Description: useSetState is a React hook that returns a useState tuple where the setter merges a partial object into state — like this.setState in class components.
Import: `import { useSetState } from '@reactuses/core'`

# useSetState

useState wrapper to work with state like in class component

`useSetState` returns a `[state, setState]` tuple where `setState` accepts a *partial* object (or a function returning a partial object) and merges it into the current state, just like `this.setState` in React class components. This avoids the need to spread the previous state manually when updating a single field in an object.

### When to Use

- Managing complex form state with many fields where you want to update one field at a time without spreading the rest
- Migrating class components to hooks while preserving the familiar `this.setState({ key: value })` pattern
- Any scenario involving an object state where partial updates are more ergonomic than full replacements

### Notes

- **Shallow merge**: The partial object is merged one level deep via object spread. Nested objects are replaced, not deeply merged.
- **Function updater**: You can pass a function `(currentState) => Partial<T>` for updates that depend on the current state.
- **SSR-safe**: Uses only React state internally with no browser dependencies.

## Usage

```tsx live
function Demo() {
  const [state, setState] = useSetState({ value1: "value1", value2: "value2" });
  const { value1, value2 } = state;
  return (
    <div>
      <p>value1: {value1}</p>
      <p>value2: {value2}</p>
      <button
        onClick={() => {
          setState({
            value1: "value",
          });
        }}
      >
        change value
      </button>
    </div>
  );
};

```

---

## useSupported

URL: https://reactuse.com/state/usesupported/
Category: state
Description: useSupported is a React hook for browser feature detection — runs a check after mount and returns a boolean, safely returning false during SSR.
Import: `import { useSupported } from '@reactuses/core'`

# useSupported

Check to see if your browser supports some feature

`useSupported` accepts a callback that performs a feature-detection check (e.g., `() => 'IntersectionObserver' in window`) and returns a boolean indicating whether the feature is available. The check runs after mount in a `useEffect` (or `useLayoutEffect` if the `sync` option is `true`), so it safely returns `false` during SSR and on the initial server render.

### When to Use

- Conditionally enabling browser features (e.g., EyeDropper API, Clipboard API, Web Bluetooth) based on runtime availability
- Showing fallback UI or informational messages when a required API is not supported
- Gating hook logic that depends on a specific browser capability to avoid runtime errors

### Notes

- **SSR-safe**: Always returns `false` on the server and during the initial render, then updates to the true value after mount.
- **Sync mode**: Pass `sync: true` to run the check in `useLayoutEffect` instead of `useEffect`, which can prevent a flash of incorrect UI.
- This hook is used internally by many other hooks in this library (e.g., `useEyeDropper`, `useClipboard`) to gate browser API access.

## Usage

```tsx live
function Demo() {
  const isSupported = useSupported(() => "EyeDropper" in window);
  return (
    <div>
      <p>
        window.EyeDropper is {isSupported ? "supported" : "unsupported"} in your
        browser
      </p>
    </div>
  );
};

```

---

## useTextSelection

URL: https://reactuse.com/state/usetextselection/
Category: state
Description: useTextSelection is a React hook that reactively tracks the user's text selection via the selectionchange event — returns the current Selection object, or null.
Import: `import { useTextSelection } from '@reactuses/core'`

# useTextSelection

Track user text selection based on [document.getSelection](https://developer.mozilla.org/en-US/docs/Web/API/Document/getSelection)

`useTextSelection` listens for `selectionchange` events on the document and returns the current `Selection` object (or `null` if nothing is selected). The returned object updates reactively whenever the user selects, modifies, or clears a text selection anywhere on the page. You can call `.toString()` on the result to get the selected text as a string.

### When to Use

- Building annotation or highlighting tools that respond to user text selections
- Displaying floating toolbars (bold, italic, link) when the user selects text in an editor
- Tracking selected text for search, copy, or share-to-social features

### Notes

- **Document-wide**: The hook tracks selections across the entire document, not a specific element. Filter by checking the selection's anchor or focus node if you need element-scoped behavior.
- **Browser-only**: `document.getSelection` is not available during SSR. The hook returns `null` on the server.
- The returned `Selection` object is a live reference from the browser; its properties update in place between re-renders.

## Usage

```tsx live
function Demo() {
  const selection = useTextSelection();

  return (
    <div style={{ padding: 40 }}>
      <p>
        Select some text here or anywhere on the page and it will be displayed
        below
      </p>

      <div>Selected text: {selection?.toString()}</div>
    </div>
  );
};

```

---

## useThrottle

URL: https://reactuse.com/state/usethrottle/
Category: state
Description: useThrottle is a React hook that returns a throttled copy of a value — updates at most once per interval for a steady stream of changes.
Import: `import { useThrottle } from '@reactuses/core'`

# useThrottle

React hooks that [throttle](https://lodash.com/docs/4.17.15#throttle) value

`useThrottle` accepts a value and a wait time in milliseconds, and returns a throttled version of that value. Unlike debouncing (which waits for idle), throttling ensures the value updates at most once per interval, providing a steady stream of updates. Under the hood it uses `lodash.throttle`, so you can pass the same options (`leading`, `trailing`) for fine-grained control.

### When to Use

- Rate-limiting UI updates driven by high-frequency events (e.g., scroll position, resize dimensions)
- Ensuring a value is emitted at regular intervals rather than waiting for a pause in changes
- Providing steady visual feedback (e.g., progress indicators) from rapidly changing source values

### Notes

- **Value-level throttle**: This hook throttles the *value* itself, not a callback. If you need to throttle a function invocation, use `useDebounceFn` with a `maxWait` option or a dedicated throttle utility.
- **Options passthrough**: The third argument is forwarded directly to `lodash.throttle`, supporting `leading` and `trailing` edge configuration.
- See also `useDebounce` for delaying updates until the value stops changing, which is better suited for search inputs and validation.

## Usage

```tsx live noInline
function Demo() {
  const [value, setValue] = useState<string>();
  const throttledValue = useThrottle(value, 500);

  return (
    <div>
      <input
        value={value}
        onChange={e => setValue(e.target.value)}
        placeholder="Typed value"
        style={{ width: 280 }}
      />
      <p style={{ marginTop: 16 }}>throttledValue: {throttledValue}</p>
    </div>
  );
};

render(<Demo/>);

```

---

## useToggle

URL: https://reactuse.com/state/usetoggle/
Category: state
Description: useToggle is a React hook to manage a boolean state with a toggle function — flip the value with no arguments or set it directly with true or false.
Import: `import { useToggle } from '@reactuses/core'`

# useToggle

React state hook that tracks value of a boolean

`useToggle` manages a boolean state value with a convenient toggle function. It returns a tuple containing the current boolean value and a toggle function. Calling `toggle()` with no arguments flips the value; calling `toggle(true)` or `toggle(false)` sets it directly. This provides a minimal API for the most common boolean state pattern.

### When to Use

- Toggling UI elements like modals, dropdowns, sidebars, or accordions
- Managing on/off states for features, dark mode, or settings
- Controlling show/hide visibility of components with a simple tuple API

### Notes

- **SSR-safe**: Works identically on server and client since it uses only React state.
- **Flexible toggle**: The toggle function accepts an optional argument. Pass a boolean to set a specific value, or call with no arguments to flip.
- See also `useBoolean` for a richer API with explicit `setTrue`/`setFalse` helpers, and `useDisclosure` for modal-style open/close patterns with callbacks.

## Usage

```tsx live
function Demo() {
  const [on, toggle] = useToggle(true);

  return (
    <div>
      <div>{on ? "ON" : "OFF"}</div>
      <button onClick={toggle}>Toggle</button>
      <button onClick={() => toggle(true)}>set ON</button>
      <button onClick={() => toggle(false)}>set OFF</button>
    </div>
  );
};

```

---

# Effect hooks (20)

## useAsyncEffect

URL: https://reactuse.com/effect/useasynceffect/
Category: effect
Description: useAsyncEffect is a React hook that brings async and await support to useEffect — run async effects with an optional async cleanup, safe against unmount.
Import: `import { useAsyncEffect } from '@reactuses/core'`

# useAsyncEffect

React useEffect with async await support. Note it don't support generator function

`useAsyncEffect` wraps React's `useEffect` to allow async/await syntax directly inside the effect callback. It accepts an async effect function, an optional async cleanup function, and a dependency list. The hook guards against state updates after unmount by checking the component's mounted status before running the effect.

### When to Use

- Fetching data from an API on mount or when dependencies change, without needing a separate async IIFE inside `useEffect`
- Running sequential asynchronous operations (e.g., reading from IndexedDB then updating state) with clean syntax
- Performing async cleanup logic (e.g., closing a connection) when the component unmounts or deps change

### Notes

- **No generator support**: Only `async` functions and plain functions are supported; generator functions are not handled.
- **Unmount safety**: Internally uses `useMountedState` to skip execution if the component has already unmounted, preventing "state update on unmounted component" warnings.
- The cleanup function runs synchronously when the effect re-fires or the component unmounts, matching standard `useEffect` cleanup behavior.

## Usage

```tsx live
function Demo() {
  const [data, setData] = useState(0);

  useAsyncEffect(
    async () => {
      const result = await new Promise<number>((resolve) => {
        setTimeout(() => {
          resolve(200);
        }, 5000);
      });
      setData(result);
    },
    () => {},
    [],
  );
  return <div>data: {data}</div>;
};

```

---

## useCustomCompareEffect

URL: https://reactuse.com/effect/usecustomcompareeffect/
Category: effect
Description: useCustomCompareEffect is a React useEffect variant that re-runs based on a custom comparator instead of reference equality.
Import: `import { useCustomCompareEffect } from '@reactuses/core'`

# useCustomCompareEffect

A modified useEffect hook that accepts a comparator which is used for comparison on dependencies instead of reference equality

`useCustomCompareEffect` gives you full control over when an effect re-runs by letting you supply a custom comparison function for the dependency array. Instead of React's default reference equality check, the effect only fires when your comparator returns `false`. This is useful when dependencies are objects or arrays that are structurally equivalent but referentially different across renders.

### When to Use

- Running an effect only when a specific property of a dependency object changes (e.g., an `id` field) while ignoring other property changes
- Integrating with external data sources that produce new object references on every read but rarely change in meaningful ways
- When `useDeepCompareEffect` is too broad and you need fine-grained comparison logic

### Notes

- **Comparator signature**: The comparator receives `(prevDeps, nextDeps)` and should return `true` if they are considered equal (skip the effect), or `false` to re-run it.
- **Return value**: Supports cleanup functions the same way as standard `useEffect`.
- See also `useDeepCompareEffect` for automatic deep equality comparison without a custom comparator.

## Usage

```tsx live
function Demo() {
  const [person, setPerson] = useState({ name: "bob", id: 1 });
  const [count, setCount] = useState(0);
  useCustomCompareEffect(
    () => {
      setCount(c => c + 1);
    },
    [person],
    (prevDeps, nextDeps) => prevDeps[0].id === nextDeps[0].id,
  );

  return (
    <div>
      <button
        onClick={() => {
          setPerson({ name: "joey", id: 1 });
        }}
      >
        Change Person Name
      </button>
      <button
        onClick={() => {
          setPerson({ name: "bob", id: 2 });
        }}
      >
        Change Person Id
      </button>
      <p>useCustomCompareEffect with deep comparison: {count}</p>
    </div>
  );
};

```

---

## useDebounceFn

URL: https://reactuse.com/effect/usedebouncefn/
Category: effect
Description: useDebounceFn is a React hook that wraps a function with debounce behavior — returns run, cancel, and flush controls, powered by lodash.debounce.
Import: `import { useDebounceFn } from '@reactuses/core'`

# useDebounceFn

React hooks that [debounce](https://lodash.com/docs/4.17.15#debounce) function

`useDebounceFn` wraps a function with debounce behavior powered by `lodash.debounce`. It returns an object with `run`, `cancel`, and `flush` methods, giving you full control over the debounced execution. The debounced function delays invoking your callback until after the specified wait time has elapsed since the last call.

### When to Use

- Debouncing search input so API requests are only sent after the user stops typing
- Limiting the rate of expensive computations triggered by rapidly changing values (e.g., window resize calculations)
- Delaying form validation until the user pauses input

### Notes

- **Lodash options**: The third parameter accepts `lodash.debounce` options such as `leading`, `trailing`, and `maxWait` for fine-tuned control.
- **Cleanup**: Call `cancel()` to discard any pending debounced invocation, or `flush()` to execute it immediately.
- See also `useThrottleFn` for rate-limiting that guarantees execution at regular intervals rather than waiting for inactivity.

## Usage

```tsx live
function Demo() {
  const [value, setValue] = useState(0);
  const { run } = useDebounceFn(() => {
    setValue(value + 1);
  }, 500);

  return (
    <div>
      <p style={{ marginTop: 16 }}> Clicked count: {value} </p>
      <button type="button" onClick={run}>
        Click fast!
      </button>
    </div>
  );
};

```

---

## useDeepCompareEffect

URL: https://reactuse.com/effect/usedeepcompareeffect/
Category: effect
Description: useDeepCompareEffect is a React useEffect drop-in that deep-compares dependencies instead of reference equality — avoids needless effect runs on equal deps.
Import: `import { useDeepCompareEffect } from '@reactuses/core'`

# useDeepCompareEffect

A modified useEffect hook that is using deep comparison on its dependencies instead of reference equality

`useDeepCompareEffect` is a drop-in replacement for `useEffect` that performs deep structural comparison on the dependency array instead of shallow reference checks. This prevents unnecessary effect executions when dependencies are new object or array references that contain the same values. It has the same signature as `useEffect` and supports cleanup functions.

### When to Use

- When your effect depends on objects or arrays that are re-created on every render (e.g., inline objects, API response data)
- Avoiding infinite effect loops caused by non-memoized dependency references
- When `useMemo` or `useCallback` on every dependency would be overly verbose

### Notes

- **Performance**: Deep comparison has overhead proportional to the size of the dependency values. For large or deeply nested objects, consider `useCustomCompareEffect` with a targeted comparator instead.
- **Cleanup support**: Supports return-based cleanup functions identically to `useEffect`.
- See also `useCustomCompareEffect` when you need comparison logic beyond deep equality.

## Usage

```tsx live
function Demo() {
  const [count, setCount] = useState(0);
  const effectCountRef = useRef(0);
  const deepCompareCountRef = useRef(0);

  useEffect(() => {
    effectCountRef.current += 1;
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [{}]);

  useDeepCompareEffect(() => {
    deepCompareCountRef.current += 1;
    return () => {
      // do something
    };
  }, [{}]);

  return (
    <div>
      <p>effectCount: {effectCountRef.current}</p>
      <p>deepCompareCount: {deepCompareCountRef.current}</p>
      <p>
        <button type="button" onClick={() => setCount(c => c + 1)}>
          reRender
        </button>
      </p>
    </div>
  );
};

```

---

## useEvent

URL: https://reactuse.com/effect/useevent/
Category: effect
Description: useEvent is a React hook implementing the useEvent RFC — get an event handler with a stable identity that always calls the latest props and state.
Import: `import { useEvent } from '@reactuses/core'`

# useEvent

Basic implementation of [React RFC useEvent](https://github.com/reactjs/rfcs/pull/220). It lets you define event handlers that can read the latest props/state but have always stable function identity

`useEvent` returns a function with a stable reference that never changes between renders, while always calling through to the latest version of your callback. This is achieved by storing the callback in a ref that is updated on every render via `useIsomorphicLayoutEffect`. The returned function can safely be passed as a prop or dependency without causing unnecessary re-renders or effect re-runs.

### When to Use

- Passing event handlers to memoized child components (`React.memo`) without breaking their memoization
- Using a callback as a dependency in `useEffect` without triggering the effect on every render
- Any scenario where you need a stable function identity that always reads the latest closure values

### Notes

- **Stable identity**: The returned function reference is created once via `useCallback([], ...)` and never changes, making it safe to omit from dependency arrays.
- **Layout-phase update**: The internal ref is updated during the layout phase (`useIsomorphicLayoutEffect`), ensuring the latest callback is available before any post-layout effects run.
- In development mode, a console error is logged if the argument is not a function.

## Usage

```tsx live
function Demo() {
  const [count, setCount] = useState(0);

  const callbackFn = useCallback(() => {
    alert(`Current count is ${count}`);
  }, [count]);

  const memoizedFn = useEvent(() => {
    alert(`Current count is ${count}`);
  });

  return (
    <>
      <p>count: {count}</p>
      <button
        type="button"
        onClick={() => {
          setCount(c => c + 1);
        }}
      >
        Add Count
      </button>
      <div style={{ marginTop: 16 }}>
        <button type="button" onClick={callbackFn}>
          call callbackFn
        </button>
        <button type="button" onClick={memoizedFn} style={{ marginLeft: 8 }}>
          call memoizedFn
        </button>
      </div>
    </>
  );
};

```

---

## useEventEmitter

URL: https://reactuse.com/effect/useeventemitter/
Category: effect
Description: useEventEmitter is a React hook that creates a lightweight publish and subscribe event system scoped to your component, stable across renders.
Import: `import { useEventEmitter } from '@reactuses/core'`

# useEventEmitter

A basic eventemitter

`useEventEmitter` creates a lightweight publish/subscribe event system scoped to your component. It returns a tuple of three items: an `event` function to register listeners (each returning a disposable), a `fire` function to broadcast a value to all listeners, and a `dispose` function to remove all listeners at once. Listener references are stored in a ref, so the emitter identity is stable across renders.

### When to Use

- Coordinating communication between sibling components or decoupled modules without lifting state up
- Building custom notification or messaging systems within a React tree
- Implementing undo/redo or command patterns where multiple subscribers react to dispatched events

### Notes

- **Disposable pattern**: Each call to the `event` function returns an object with a `dispose()` method, allowing you to remove individual listeners without affecting others.
- **No automatic cleanup**: Listeners are not removed on unmount automatically. Call `dispose()` in a `useEffect` cleanup or use `useUnmount` to prevent memory leaks.
- The emitter supports generic typing for both the event payload and an optional second argument.

## Usage

```tsx live noInline
function Demo() {
  const [state, setState] = useState(0);
  const [event, fire, dispose] = useEventEmitter<number>();

  const event1 = useRef<IDisposable>();
  useEffect(() => {
    event((val) => {
      setState(s => s + val);
    });
    event1.current = event(val => setState(s => s + val + 10));
  }, [event]);

  return (
    <div>
      <div>state: {state}</div>
      <button onClick={() => fire(1)}>fire</button>
      <button onClick={() => dispose()}>disposeALL</button>
      <button onClick={() => event1.current?.dispose()}>disposeOne</button>
    </div>
  );
};

render(<Demo/>);

```

---

## useEventListener

URL: https://reactuse.com/effect/useeventlistener/
Category: effect
Description: useEventListener is a React hook to attach a DOM event listener to an element, window, or document with automatic cleanup and an always-current handler.
Import: `import { useEventListener } from '@reactuses/core'`

# useEventListener

Use EventListener with ease.

`useEventListener` attaches a DOM event listener to a target element (or `window`/`document`) and automatically removes it on unmount or when dependencies change. It accepts the event name, handler function, and an optional target ref or element. The handler is always up-to-date without needing to re-register the listener, thanks to an internal ref via `useLatest`.

### When to Use

- Listening for keyboard shortcuts, mouse clicks, or scroll events on specific elements
- Attaching `resize`, `visibilitychange`, or `storage` events to `window`/`document`
- Any case where you need automatic cleanup of event listeners tied to component lifecycle

### Notes

- **SSR-safe**: Skips listener registration during server-side rendering since `window`/`document` are unavailable.
- **Stable handler**: Uses `useLatest` internally so the handler always points to the latest closure without re-attaching the listener.
- The third argument defaults to `window` and accepts a raw element, a ref object, or a function returning an element. See also `useEvent` for a stable callback ref pattern, and `useDebounceFn`/`useThrottleFn` for rate-limited event handling.

## Usage

```tsx live
function Demo() {
  const buttonRef = useRef<HTMLButtonElement>(null);
  const [state, setState] = useState("NO DB Click");

  const onDBClick = () => {
    setState("DB Clicked");
  };

  const onClick = (event: Event) => {
    console.log("button clicked!", event);
  };

  const onVisibilityChange = (event: Event) => {
    console.log("doc visibility changed!", {
      isVisible: !document.hidden,
      event,
    });
  };

  // example with window based event
  useEventListener("dblclick", onDBClick);

  // example with document based event
  useEventListener("visibilitychange", onVisibilityChange, () => document);

  // example with element based event
  useEventListener("click", onClick, buttonRef);

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

```

---

## useInterval

URL: https://reactuse.com/effect/useinterval/
Category: effect
Description: useInterval is a React hook for a declarative setInterval — pass a callback and a delay (or null to pause), with isActive, pause, and resume controls.
Import: `import { useInterval } from '@reactuses/core'`

# useInterval

A declarative interval hook based on [Dan Abramov's article on overreacted.io](https://overreacted.io/making-setinterval-declarative-with-react-hooks/). The interval can be paused by setting the delay to null

You can also manually control it by passing the `controls` parameter.

`useInterval` wraps `setInterval` in a declarative React API. It takes a callback, a delay in milliseconds (or `null` to pause), and an optional options object. It returns a `Pausable` object with `isActive`, `pause`, and `resume` methods for manual control. The callback always references the latest closure without resetting the interval.

### When to Use

- Building countdown timers, clocks, or polling mechanisms that tick at a regular interval
- Auto-refreshing data from an API at a fixed cadence
- Animating values over time with a consistent step interval

### Notes

- **Pause/resume**: Set `delay` to `null` to pause the interval, or use the returned `pause()`/`resume()` methods for imperative control.
- **Immediate option**: Pass `{ immediate: true }` to execute the callback immediately on start in addition to after each interval.
- The interval is automatically cleared on component unmount. See also `useTimeout` for single-fire delayed execution and `useRafFn` for frame-based animation loops.

## Usage

```tsx live
function Demo() {
  const [count, setCount] = useState(0);

  useInterval(() => {
    setCount(count + 1);
  }, 1000);

  return <div>count: {count}</div>;
};

```

---

## useIsomorphicLayoutEffect

URL: https://reactuse.com/effect/useisomorphiclayouteffect/
Category: effect
Description: useIsomorphicLayoutEffect is a React hook that uses useLayoutEffect in the browser and useEffect on the server — avoids the SSR useLayoutEffect warning.
Import: `import { useIsomorphicLayoutEffect } from '@reactuses/core'`

# useIsomorphicLayoutEffect

`useIsomorphicLayoutEffect` that does not show warning when server-side rendering, see [Alex Reardon's article](https://medium.com/@alexandereardon/uselayouteffect-and-ssr-192986cdcf7a) for more info

`useIsomorphicLayoutEffect` resolves to `useLayoutEffect` in browser environments and `useEffect` on the server. This eliminates the React warning about `useLayoutEffect` doing nothing during SSR while preserving synchronous DOM measurement behavior in the client. It has the exact same signature as `useEffect`/`useLayoutEffect`, making it a drop-in replacement.

### When to Use

- Measuring or mutating the DOM synchronously before the browser paints, in projects that also support server-side rendering
- Building library hooks that need layout-phase timing but must work in SSR frameworks (Next.js, Remix, etc.)
- Any place you would use `useLayoutEffect` but need to avoid SSR console warnings

### Notes

- **Environment detection**: Uses a simple `isBrowser` check (typeof `window` !== `undefined`) to select the appropriate hook.
- **Same API**: Accepts an effect callback and optional dependency array, identical to both `useEffect` and `useLayoutEffect`.
- This hook is used internally by several other hooks in this library (e.g., `useEvent`) to ensure SSR compatibility.

## Usage

```tsx live
function Demo() {
  const [value] = useState("useIsomorphicLayoutEffect");
  useIsomorphicLayoutEffect(() => {
    window.console.log(value);
  }, [value]);

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

```

---

## useMount

URL: https://reactuse.com/effect/usemount/
Category: effect
Description: useMount is a React lifecycle hook that runs a callback exactly once after the component mounts — a clear alternative to useEffect with empty deps.
Import: `import { useMount } from '@reactuses/core'`

# useMount

React lifecycle hook that executes a function after the component is mounted

`useMount` runs a callback exactly once after the component mounts, equivalent to `useEffect(() => { ... }, [])`. It provides a semantically clear way to express mount-only logic without manually specifying an empty dependency array. The callback receives no arguments and does not support a return-based cleanup function.

### When to Use

- Running one-time initialization logic such as analytics tracking, logging, or third-party SDK setup
- Performing DOM measurements or imperative focus calls immediately after the component first renders
- Replacing class component `componentDidMount` behavior with a concise hook

### Notes

- **No cleanup**: `useMount` does not support a cleanup return value. If you need unmount cleanup, pair it with `useUnmount` or use `useEffect` directly.
- **Development validation**: In development mode, a console error is logged if the provided argument is not a function.
- See also `useUnmount` for the corresponding unmount lifecycle, and `useOnceEffect` if you need React 18 Strict Mode double-invoke protection.

## Usage

```tsx live
function Demo() {
  const [value, setValue] = useState("UnMounted");
  useMount(() => {
    setValue("Mounted");
  });
  return <div>{value}</div>;
};

```

---

## useOnceEffect

URL: https://reactuse.com/effect/useonceeffect/
Category: effect
Description: useOnceEffect is a React useEffect variant that runs the effect only once, even under React 18 Strict Mode's double-invocation in development.
Import: `import { useOnceEffect } from '@reactuses/core'`

# useOnceEffect

A Hook that avoids React18 useEffect run twice

`useOnceEffect` is a variant of `useEffect` that guarantees the effect callback executes only once, even under React 18's Strict Mode which intentionally double-invokes effects during development. It uses a `WeakSet`-based tracking mechanism to detect and skip duplicate invocations. The API is identical to `useEffect` -- it accepts an effect callback and an optional dependency array.

### When to Use

- Performing side effects that must run exactly once (e.g., sending an analytics event, initializing a third-party library) and cannot tolerate React 18 Strict Mode double-firing
- Protecting against duplicate API calls on mount in development mode with `<StrictMode>` enabled
- Replacing manual `useRef`-based "already ran" guards with a cleaner API

### Notes

- **React 18 Strict Mode**: In development, React 18 mounts, unmounts, and re-mounts components to surface impure effects. `useOnceEffect` prevents the second invocation by tracking the effect reference in a `WeakSet`.
- **Production behavior**: In production builds where Strict Mode double-invocation does not occur, `useOnceEffect` behaves identically to `useEffect`.
- See also `useOnceLayoutEffect` for the same behavior using `useLayoutEffect` timing, and `useMount` for a simpler mount-only callback.

## Usage

```tsx live
function Demo() {
  const [effect, setEffect] = useState(0);
  const [onceEffect, setOnceEffect] = useState(0);

  useOnceEffect(() => {
    setOnceEffect(onceEffect => onceEffect + 1);
  }, []);

  useEffect(() => {
    setEffect(effect => effect + 1);
  }, []);

  return (
    <div>
      <div>onceEffect: {onceEffect}</div>
      <br />
      <div>effect: {effect}</div>
    </div>
  );
};

```

---

## useOnceLayoutEffect

URL: https://reactuse.com/effect/useoncelayouteffect/
Category: effect
Description: useOnceLayoutEffect is a React useLayoutEffect variant that runs only once, even under React 18 Strict Mode's double-invocation — synchronous before paint.
Import: `import { useOnceLayoutEffect } from '@reactuses/core'`

# useOnceLayoutEffect

A Hook that avoids React18 useLayoutEffect run twice

`useOnceLayoutEffect` is a variant of `useLayoutEffect` that guarantees the effect callback executes only once, even under React 18's Strict Mode which intentionally double-invokes effects during development. It uses the same `WeakSet`-based tracking mechanism as `useOnceEffect` but runs with `useLayoutEffect` timing -- synchronously after DOM mutations and before the browser paints.

### When to Use

- Performing DOM measurements or mutations that must happen exactly once before paint, without being duplicated by React 18 Strict Mode
- Initializing layout-dependent third-party libraries (e.g., chart or animation libraries that manipulate the DOM directly) that break when initialized twice
- Any case where you need `useLayoutEffect` semantics with guaranteed single-execution

### Notes

- **Layout timing**: Runs synchronously after all DOM mutations, before the browser repaints. This can block visual updates if the effect is slow.
- **React 18 Strict Mode**: Prevents the double-invocation that React 18 performs in development to help detect side-effect issues.
- See also `useOnceEffect` for the `useEffect`-timed equivalent, and `useIsomorphicLayoutEffect` for SSR-safe layout effects.

## Usage

```tsx live
function Demo() {
  const [updateEffect, setLayoutEffect] = useState(0);
  const [onceLayoutEffect, setOnceLayoutEffect] = useState(0);

  useOnceLayoutEffect(() => {
    setOnceLayoutEffect(onceEffect => onceEffect + 1);
  }, []);

  useLayoutEffect(() => {
    setLayoutEffect(effect => effect + 1);
  }, []);

  return (
    <div>
      <div>onceEffect: {onceLayoutEffect}</div>
      <br />
      <div>effect: {updateEffect}</div>
    </div>
  );
};

```

---

## useRafFn

URL: https://reactuse.com/effect/useraffn/
Category: effect
Description: useRafFn is a React hook that runs a callback on every requestAnimationFrame tick with a timestamp, plus stop, start, and isActive controls.
Import: `import { useRafFn } from '@reactuses/core'`

# useRafFn

Call function on every [requestAnimationFrame](https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame). With controls of pausing and resuming

`useRafFn` schedules a callback to run on every `requestAnimationFrame` tick, providing a high-resolution timestamp to the callback on each frame. It returns a tuple of `[stop, start, isActive]` for full imperative control over the animation loop. The callback reference is kept up-to-date via `useLatest`, so you always access the latest closure values without restarting the loop.

### When to Use

- Building smooth animations that need to update on every browser paint frame (e.g., canvas drawing, CSS transforms)
- Implementing real-time visualizations like FPS counters, progress indicators, or physics simulations
- Running continuous visual updates that should pause and resume based on user interaction or visibility

### Notes

- **Auto-start**: By default the loop starts immediately on mount. Pass `false` as the second argument to start in a paused state.
- **Cleanup**: The animation frame is automatically cancelled on unmount via the effect cleanup.
- See also `useInterval` for fixed-interval timing and `useUpdate` for triggering a single re-render on demand.

## Usage

```tsx live
function Demo() {
  const [ticks, setTicks] = useState(0);
  const [lastCall, setLastCall] = useState(0);
  const update = useUpdate();

  const [loopStop, loopStart, isActive] = useRafFn((time) => {
    setTicks(ticks => ticks + 1);
    setLastCall(time);
  });

  return (
    <div>
      <div>RAF triggered: {ticks} (times)</div>
      <div>Last high res timestamp: {lastCall}</div>
      <br />
      <button
        onClick={() => {
          isActive() ? loopStop() : loopStart();
          update();
        }}
      >
        {isActive() ? "STOP" : "START"}
      </button>
    </div>
  );
};

```

---

## useThrottleFn

URL: https://reactuse.com/effect/usethrottlefn/
Category: effect
Description: useThrottleFn is a React hook that wraps a function with throttle behavior — runs at most once per interval, with run, cancel, and flush controls.
Import: `import { useThrottleFn } from '@reactuses/core'`

# useThrottleFn

React hooks that [throttle](https://lodash.com/docs/4.17.15#throttle) function

`useThrottleFn` wraps a function with throttle behavior powered by `lodash.throttle`. It returns an object with `run`, `cancel`, and `flush` methods. Unlike debounce, throttle guarantees that the function executes at most once per specified time interval, making it ideal for rate-limiting high-frequency events while still providing periodic updates.

### When to Use

- Rate-limiting scroll or mousemove event handlers to maintain smooth performance without dropping all intermediate calls
- Ensuring a save or sync operation runs at regular intervals during continuous user input
- Throttling resize handlers to limit layout recalculations while still responding periodically

### Notes

- **Lodash options**: The third parameter accepts `lodash.throttle` options such as `leading` and `trailing` to control whether the function fires at the start, end, or both edges of the throttle window.
- **Cleanup**: Call `cancel()` to discard any pending throttled invocation, or `flush()` to execute it immediately.
- See also `useDebounceFn` for delaying execution until after a pause in activity, which is better suited for search-as-you-type patterns.

## Usage

```tsx live
function Demo() {
  const [value, setValue] = useState(0);
  const { run } = useThrottleFn(() => {
    setValue(value + 1);
  }, 500);

  return (
    <div>
      <p style={{ marginTop: 16 }}> Clicked count: {value} </p>
      <button type="button" onClick={run}>
        Click fast!
      </button>
    </div>
  );
};

```

---

## useTimeout

URL: https://reactuse.com/effect/usetimeout/
Category: effect
Description: useTimeout is a React hook that provides a pending state which flips to false after a delay — returns isPending plus start and cancel controls.
Import: `import { useTimeout } from '@reactuses/core'`

# useTimeout

Update value after a given time

`useTimeout` provides a reactive pending state that flips from `true` to `false` after a specified delay. It returns a tuple of `[isPending, start, cancel]`, giving you both a declarative status value and imperative controls. By default, the timer starts immediately on mount, but you can configure it to start manually via the `immediate` option.

### When to Use

- Showing a loading indicator or splash screen for a minimum duration before revealing content
- Implementing auto-dismiss behavior for notifications, toasts, or banners after a fixed time
- Creating timed UI state transitions (e.g., disabling a button for a cooldown period)

### Notes

- **Immediate by default**: The timer starts automatically on mount. Pass `{ immediate: false }` to require an explicit `start()` call.
- **Restartable**: Calling `start()` resets and restarts the timer. Calling `cancel()` stops it and keeps `isPending` at its current value.
- See also `useTimeoutFn` for executing a callback after a delay instead of toggling a boolean state, and `useInterval` for repeated execution.

## Usage

```tsx live
function Demo() {
  const [isPending, start, cancel] = useTimeout(5000);

  return (
    <div>
      <div>Pending: {JSON.stringify(isPending)}</div>
      <button
        onClick={() => {
          start();
        }}
      >
        Start Again
      </button>
      <button
        onClick={() => {
          cancel();
        }}
      >
        Cancel
      </button>
    </div>
  );
};

```

---

## useTimeoutFn

URL: https://reactuse.com/effect/usetimeoutfn/
Category: effect
Description: useTimeoutFn is a React hook that wraps setTimeout with a React-friendly API — runs a callback after a delay, with isPending, start, and cancel controls.
Import: `import { useTimeoutFn } from '@reactuses/core'`

# useTimeoutFn

Wrapper for setTimeout with controls

`useTimeoutFn` wraps `setTimeout` with a React-friendly API, executing a callback after a specified delay. It returns a tuple of `[isPending, start, cancel]` for full control over the timeout lifecycle. The callback reference stays current so you always execute the latest closure values when the timer fires.

### When to Use

- Delaying a side effect (e.g., showing a tooltip, triggering a redirect) by a fixed duration after a user action
- Implementing retry logic with a delay between attempts
- Deferring expensive operations to run after a brief pause (e.g., lazy-loading content after a transition)

### Notes

- **Immediate by default**: The timer starts on mount unless you pass `{ immediate: false }`, which requires calling `start()` manually.
- **Restartable**: Calling `start()` cancels any in-flight timeout and starts a new one. Calling `cancel()` stops the pending timeout.
- See also `useTimeout` for a simpler boolean-state variant, and `useDebounceFn` for delaying execution until input activity stops.

## Usage

```tsx live
function Demo() {
  const [text, setText] = useState("Please wait for 3 seconds");
  const [isPending, start] = useTimeoutFn(
    () => {
      setText("Fired!");
    },
    3000,
    { immediate: false },
  );

  return (
    <div>
      <p>{text}</p>
      <button
        onClick={() => {
          setText("Please wait for 3 seconds");
          start();
        }}
      >
        {isPending ? "Pending" : "Restart"}
      </button>
    </div>
  );
};

```

---

## useUnmount

URL: https://reactuse.com/effect/useunmount/
Category: effect
Description: useUnmount is a React lifecycle hook that runs a cleanup function once when the component unmounts, with access to the latest props and state.
Import: `import { useUnmount } from '@reactuses/core'`

# useUnmount

React lifecycle hook that calls a function when the component will unmount

`useUnmount` runs a cleanup function exactly once when the component unmounts. It stores the callback in a ref via `useLatest`, ensuring the function always has access to the latest props and state at the time of unmount -- without needing to list them as dependencies. This avoids the stale closure problem common with plain `useEffect` cleanup.

### When to Use

- Cleaning up subscriptions, WebSocket connections, or event listeners when a component is removed from the tree
- Cancelling in-flight network requests or aborting async operations on unmount
- Logging or analytics tracking when a user navigates away from a page or closes a modal

### Notes

- **Latest closure**: Unlike a bare `useEffect` cleanup, the callback always sees the most recent state and props because it reads from a ref.
- **Development validation**: In development mode, a console error is logged if the provided argument is not a function.
- See also `useMount` for the corresponding mount lifecycle hook.

## Usage

```tsx live
function Demo() {
  const [value] = useState("mounted");
  useUnmount(() => {
    alert("UnMounted");
  });
  return <div>{value}</div>;
};

```

---

## useUpdate

URL: https://reactuse.com/effect/useupdate/
Category: effect
Description: useUpdate is a React hook that returns a stable function to force a component re-render when called — useful for imperative refresh scenarios.
Import: `import { useUpdate } from '@reactuses/core'`

# useUpdate

React utility hook that returns a function that forces component to re-render when called

`useUpdate` returns a stable function that forces the component to re-render when invoked. Internally it uses `useReducer` with an incrementing counter, so each call produces a new state value that triggers React's reconciliation. The returned function identity is stable across renders, making it safe to pass as a prop or store in a ref.

### When to Use

- Forcing a re-render after mutating a ref or external mutable value that React does not track
- Integrating with imperative APIs or third-party libraries that update state outside of React's awareness
- Refreshing displayed values (e.g., `Date.now()`) on demand without managing explicit state

### Notes

- **Stable identity**: The returned update function never changes between renders, so it can safely be used in dependency arrays or passed to child components.
- **Use sparingly**: Forcing re-renders bypasses React's declarative model. Prefer state or context updates when possible.
- See also `useRafFn` for continuous re-rendering on every animation frame.

## Usage

```tsx live
function Demo() {
  const update = useUpdate();

  return (
    <>
      {/* to avoid ssr error beacause date.now() will not be same in server and client */}
      <div suppressHydrationWarning={true}>Time: {Date.now()}</div>
      <button onClick={update}>Update</button>
    </>
  );
};

```

---

## useUpdateEffect

URL: https://reactuse.com/effect/useupdateeffect/
Category: effect
Description: useUpdateEffect is a React useEffect variant that skips the initial mount run — the effect fires only on subsequent dependency changes.
Import: `import { useUpdateEffect } from '@reactuses/core'`

# useUpdateEffect

React effect hook that ignores the first invocation (e.g. on mount). The signature is exactly the same as the `useEffect` hook

`useUpdateEffect` works identically to `useEffect` except that it skips the initial execution on mount. The effect only fires on subsequent dependency changes, making it useful when you want to react to updates but not to the initial render. It uses `useFirstMountState` internally to detect and skip the first invocation.

### When to Use

- Running a side effect only when a value changes after the initial render (e.g., syncing a form field to an API only on updates, not on mount)
- Showing a "value changed" notification without triggering it when the component first appears
- Skipping initial data fetches when the component already has default or cached data

### Notes

- **Same signature**: Accepts an effect callback and optional dependency array, identical to `useEffect`. Supports cleanup functions via the return value.
- **First-mount detection**: Uses `useFirstMountState` internally, which tracks mount status via a ref.
- See also `useUpdateLayoutEffect` for the same skip-first-run behavior using `useLayoutEffect` timing, and `useDeepCompareEffect` for deep dependency comparison.

## Usage

```tsx live
function Demo() {
  const [count, setCount] = useState(0);
  const [effectCount, setEffectCount] = useState(0);
  const [updateEffectCount, setUpdateEffectCount] = useState(0);

  useEffect(() => {
    setEffectCount(c => c + 1);
  }, [count]);

  useUpdateEffect(() => {
    setUpdateEffectCount(c => c + 1);
    return () => {
      // do something
    };
  }, [count]); // you can include deps array if necessary

  return (
    <div>
      <p>effectCount: {effectCount}</p>
      <p>updateEffectCount: {updateEffectCount}</p>
      <p>
        <button type="button" onClick={() => setCount(c => c + 1)}>
          reRender
        </button>
      </p>
    </div>
  );
};

```

---

## useUpdateLayoutEffect

URL: https://reactuse.com/effect/useupdatelayouteffect/
Category: effect
Description: useUpdateLayoutEffect is a React useLayoutEffect variant that skips the initial mount run — fires synchronously after DOM mutations on later changes.
Import: `import { useUpdateLayoutEffect } from '@reactuses/core'`

# useUpdateLayoutEffect

React layoutEffect hook that ignores the first invocation (e.g. on mount). The signature is exactly the same as the `useLayoutEffect` hook

`useUpdateLayoutEffect` works identically to `useLayoutEffect` except that it skips the initial execution on mount. The effect fires synchronously after DOM mutations but only on subsequent dependency changes, not on the first render. This is useful for DOM measurements or mutations that should only respond to updates.

### When to Use

- Adjusting layout or scroll position in response to state changes, but not on the initial render when the DOM is first painted
- Synchronously updating DOM attributes or styles only when a dependency has actually changed after mount
- Preventing initial flash-of-content issues when a layout effect would incorrectly run its update logic on mount

### Notes

- **Layout timing**: Runs synchronously after DOM mutations and before the browser repaints, the same as `useLayoutEffect`. Avoid slow operations to prevent blocking visual updates.
- **Same signature**: Accepts an effect callback and optional dependency array, identical to `useLayoutEffect`. Supports cleanup functions via the return value.
- See also `useUpdateEffect` for the `useEffect`-timed equivalent, and `useIsomorphicLayoutEffect` for SSR-safe layout effects.

## Usage

```tsx live
function Demo() {
  const [count, setCount] = useState(0);
  const [layoutEffectCount, setLayoutEffectCount] = useState(0);
  const [updateLayoutEffectCount, setUpdateLayoutEffectCount] = useState(0);

  useLayoutEffect(() => {
    setLayoutEffectCount(c => c + 1);
  }, [count]);

  useUpdateLayoutEffect(() => {
    setUpdateLayoutEffectCount(c => c + 1);
    return () => {
      // do something
    };
  }, [count]); // you can include deps array if necessary

  return (
    <div>
      <p>layoutEffectCount: {layoutEffectCount}</p>
      <p>updateLayoutEffectCount: {updateLayoutEffectCount}</p>
      <p>
        <button type="button" onClick={() => setCount(c => c + 1)}>
          reRender
        </button>
      </p>
    </div>
  );
};

```

---

# Element hooks (19)

## useActiveElement

URL: https://reactuse.com/element/useactiveelement/
Category: element
Description: useActiveElement is a React hook that reactively tracks document.activeElement — returns the focused DOM element, or null, updating on focus and blur.
Import: `import { useActiveElement } from '@reactuses/core'`

# useActiveElement

React Sensor Hooks that tracks document.activeElement

`useActiveElement` reactively tracks which DOM element currently has focus via [`document.activeElement`](https://developer.mozilla.org/en-US/docs/Web/API/Document/activeElement). It returns the focused element (typed with a generic parameter) or `null` when no element is focused. The hook automatically listens for `focus` and `blur` events on the document to keep the value up to date.

### When to Use

- Highlighting or styling the currently focused input in a form
- Building accessibility tools or focus-trap components that need to know which element has focus
- Debugging focus flow in complex UIs with many interactive elements

### Notes

- **SSR-safe**: Returns `null` during server-side rendering since `document` is not available.
- **Generic type**: You can narrow the return type with a type parameter, e.g. `useActiveElement<HTMLInputElement>()`, to get typed access to element properties like `dataset`.
- See also `useFocus` for controlling and tracking focus state on a specific element.

## Usage

```tsx live noInline
function Demo() {
  const arr = [1, 2, 3, 4, 5, 6];

  const activeElement = useActiveElement<HTMLElement>();

  const key = useMemo(() => {
    return activeElement?.dataset?.id;
  }, [activeElement?.dataset?.id]);

  return (
    <div>
      <p>Select the inputs below to see the changes </p>
      <div style={{ display: "flex", gap: 15, flexWrap: "wrap" }}>
        {arr.map((i) => {
          return <input key={i} placeholder={`${i}`} data-id={i} />;
        })}
      </div>
      <br />
      <div>
        Current Active Element:
        <span> {activeElement?.tagName}</span>
      </div>
       <div>
        Current Active Element data-key:
        <span>{key}</span>
      </div>
    </div>
  );
};

render(<Demo/>);

```

---

## useClickAway

URL: https://reactuse.com/element/useclickaway/
Category: element
Description: useClickAway is a React hook to detect clicks outside an element — an alias for useClickOutside. Ideal for closing modals, dropdowns, and popovers.
Import: `import { useClickAway } from '@reactuses/core'`

# useClickAway

Listen for clicks outside of an element. Useful for modal or dropdown.

:::info
`useClickAway` is an alias for [`useClickOutside`](/element/useclickoutside). They have identical functionality and API.
:::

`useClickAway` detects clicks (mouse and touch events) that occur outside of a referenced DOM element and invokes a callback when they happen. Pass a ref to the element you want to protect and a handler function. You can also pass an `enabled` flag to conditionally activate or deactivate the listener.

### When to Use

- Closing dropdown menus, popovers, or modals when the user clicks outside of them
- Deselecting or deactivating an inline editing component when focus moves away
- Dismissing notification toasts or context menus on outside interaction

### Notes

- **Event types**: Listens for both `mousedown` and `touchstart` events, covering desktop and mobile interactions.
- **Cleanup**: The event listeners are automatically removed when the component unmounts or when `enabled` is set to `false`.
- This hook is an alias for `useClickOutside`. Use whichever name you prefer -- they share the same implementation.

## Usage

```tsx live
function Demo() {
  const [visible, setVisible] = useState(false);

  const modalRef = useRef<HTMLDivElement>(null);

  useClickAway(modalRef, () => {
    setVisible(false);
  });

  return (
    <div>
      <button onClick={() => setVisible(true)}> Open Modal</button>
      {visible && (
        <div
          ref={modalRef}
          style={{
            position: "fixed",
            left: "50%",
            top: "50%",
            transform: "translate(-50%,-50%)",
            width: 420,
            maxWidth: "100%",
            zIndex: 10,
            border: "1px solid var(--c-input-border)",
            background: "var(--c-bg)",
          }}
        >
          <div
            style={{
              padding: "0.4em 2em",
              boxShadow: "2px 2px 10px var(--c-box-shadow)",
            }}
          >
            <p
              style={{
                fontWeight: 700,
                fontSize: "1.4rem",
                marginBottom: "2rem",
              }}
            >
              Demo Modal
            </p>
            <p>Click outside of the modal to close it.</p>
          </div>
        </div>
      )}
    </div>
  );
};

```

---

## useClickOutside

URL: https://reactuse.com/element/useclickoutside/
Category: element
Description: useClickOutside is a React hook that detects mouse and touch clicks outside a referenced element and fires a callback — ideal for modals and dropdowns.
Import: `import { useClickOutside } from '@reactuses/core'`

# useClickOutside

Listen for clicks outside of an element. Useful for modal or dropdown

`useClickOutside` detects clicks (mouse and touch events) that occur outside of a referenced DOM element and invokes a callback when they happen. Pass a ref to the target element, a handler function, and an optional `enabled` boolean to conditionally toggle the listener. The handler receives the original `MouseEvent` or `TouchEvent`.

### When to Use

- Closing dropdown menus, popovers, or modals when the user clicks outside of them
- Deselecting or deactivating an inline editing component when focus moves away
- Dismissing notification toasts or context menus on outside interaction

### Notes

- **Event types**: Listens for both `mousedown` and `touchstart` events, covering desktop and mobile interactions.
- **Cleanup**: The event listeners are automatically removed when the component unmounts or when `enabled` is set to `false`.
- Also available as `useClickAway`, which is an alias with the identical API and implementation.

## Usage

```tsx live
function Demo() {
  const [visible, setVisible] = useState(false);

  const modalRef = useRef<HTMLDivElement>(null);

  useClickOutside(modalRef, () => {
    setVisible(false);
  });

  return (
    <div>
      <button onClick={() => setVisible(true)}> Open Modal</button>
      {visible && (
        <div
          ref={modalRef}
          style={{
            position: "fixed",
            left: "50%",
            top: "50%",
            transform: "translate(-50%,-50%)",
            width: 420,
            maxWidth: "100%",
            zIndex: 10,
            border: "1px solid var(--c-input-border)",
            background: "var(--c-bg)",
          }}
        >
          <div
            style={{
              padding: "0.4em 2em",
              boxShadow: "2px 2px 10px var(--c-box-shadow)",
            }}
          >
            <p
              style={{
                fontWeight: 700,
                fontSize: "1.4rem",
                marginBottom: "2rem",
              }}
            >
              Demo Modal
            </p>
            <p>Click outside of the modal to close it.</p>
          </div>
        </div>
      )}
    </div>
  );
};

```

---

## useDocumentVisibility

URL: https://reactuse.com/element/usedocumentvisibility/
Category: element
Description: useDocumentVisibility is a React hook that reactively tracks page visibility via the Page Visibility API — returns visible or hidden as the user switches tabs.
Import: `import { useDocumentVisibility } from '@reactuses/core'`

# useDocumentVisibility

React Sensor Hook that tracks [document.visibilityState](https://developer.mozilla.org/en-US/docs/Web/API/Document/visibilityState)

`useDocumentVisibility` reactively tracks whether the page is visible or hidden using the [Page Visibility API](https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API). It returns the current `DocumentVisibilityState` (`"visible"` or `"hidden"`) and updates automatically when the user switches tabs or minimizes the browser. You can provide a default value for the initial state.

### When to Use

- Pausing animations, videos, or timers when the user navigates away from the tab
- Showing a "welcome back" message or refreshing stale data when the user returns
- Reducing network requests or resource consumption while the page is in the background

### Notes

- **SSR-safe**: Accepts a `defaultValue` parameter (e.g. `"hidden"`) that is used during server-side rendering when `document` is not available.
- **Lightweight**: Listens to the `visibilitychange` event on `document` and cleans up the listener on unmount.
- See also `useWindowFocus` for tracking whether the browser window itself has focus (vs. just tab visibility).

## Usage

```tsx live
function Demo() {
  const visibility = useDocumentVisibility("hidden");
  const [message, setMessage] = useState(
    "💡 Minimize the page or switch tab then return",
  );

  useEffect(() => {
    if (visibility === "visible") {
      setTimeout(() => {
        setMessage("🎉 Welcome back!");
      }, 2000);
    }
    else {
      setTimeout(() => {
        setMessage("🥰 Take a break");
      }, 2000);
    }
  }, [visibility]);

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

```

---

## useDoubleClick

URL: https://reactuse.com/element/usedoubleclick/
Category: element
Description: useDoubleClick is a React hook that distinguishes single-click from double-click on an element using a configurable latency, with separate handlers.
Import: `import { useDoubleClick } from '@reactuses/core'`

# useDoubleClick

React sensor hook that controls double click and single click

`useDoubleClick` lets you distinguish between single-click and double-click interactions on a DOM element. It uses a configurable latency delay to determine whether a click is a single click or the first click of a double-click sequence. Pass a target ref and provide separate `onSingleClick` and `onDoubleClick` handlers to respond to each interaction.

### When to Use

- Implementing "click to select, double-click to edit" patterns on list items or table cells
- Adding double-click-to-zoom on images or maps while preserving single-click for other actions
- Any UI where single and double clicks must trigger distinct behaviors on the same element

### Notes

- **Latency**: The default delay between single and double click detection can be customized via the `latency` option (in milliseconds). A shorter latency makes single clicks feel faster but may miss slower double clicks.
- **Event types**: Supports both mouse and touch events, making it suitable for desktop and mobile.
- **Cleanup**: All event listeners are removed automatically when the component unmounts.

## Usage

```tsx live
function Demo() {
  const element = useRef<HTMLButtonElement>(null);
  const [text, setText] = useState("no click");

  useDoubleClick({
    target: element,
    onSingleClick: () => {
      setText("single click");
    },
    onDoubleClick: () => {
      setText("double click");
    },
  });
  return (
    <div>
      <button ref={element}>Click Me</button>
      <p>{text}</p>
    </div>
  );
};

```

---

## useDraggable

URL: https://reactuse.com/element/usedraggable/
Category: element
Description: useDraggable is a React hook that makes any HTML or SVG element draggable — tracks pointer, mouse, and touch input, returning x and y position.
Import: `import { useDraggable } from '@reactuses/core'`

# useDraggable

Make elements draggable

`useDraggable` makes any HTML or SVG element draggable by tracking pointer events and returning the current `x` and `y` position, a boolean indicating whether the element is being dragged, and a function to programmatically set the position. It supports pointer, mouse, touch, and pen inputs, and can optionally constrain movement within a container element.

### When to Use

- Building draggable panels, floating toolbars, or resizable widgets
- Implementing drag-to-reposition functionality for dashboard cards or kanban items
- Creating interactive diagrams or editors where elements need free movement

### Notes

- **Touch support**: Set `touch-action: none` on the draggable element's CSS to prevent browser scroll interference on touch devices.
- **Container bounds**: Use the `containerElement` option to restrict dragging within a parent element. The hook will calculate bounds automatically.
- **Callbacks**: The `onStart`, `onMove`, and `onEnd` callbacks give you fine-grained control. Returning `false` from `onStart` prevents the drag from beginning.
- **Cleanup**: All pointer event listeners are removed automatically on unmount.

## Usage

### Fixed Demo

```tsx live
function Demo() {
  const el = useRef<HTMLDivElement>(null);

  const [initialValue, setInitialValue] = useState({ x: 200 / 2.2, y: 120 });

  useEffect(() => {
    setInitialValue({ x: window.innerWidth / 2.2, y: 120 });
  }, []);

  const [x, y, isDragging] = useDraggable(el, {
    initialValue,
    preventDefault: true,
  });

  return (
    <div>
      <p style={{ textAlign: "center" }}>Check the floating boxes</p>
      <div
        ref={el}
        style={{
          position: "fixed",
          cursor: "move",
          zIndex: 10,
          touchAction: "none",
          padding: 10,
          border: "solid 1px",
          left: x,
          top: y,
        }}
      >
        {isDragging ? "Dragging!" : "👋 Drag me!"}
        <div>
          I am at {Math.round(x)}, {Math.round(y)}
        </div>
      </div>
    </div>
  );
};

```

### Relative Demo

```tsx live
function Demo() {
  const el = useRef<HTMLDivElement>(null);
  const scope = useRef<HTMLDivElement>(null);

  const initialValue = { x: 200 / 2.2, y: 120 };

  const [x, y, isDragging, setPosition] = useDraggable(el, {
    initialValue,
    preventDefault: true,
    containerElement: scope,
  });

  return (
    <div
      ref={scope}
      style={{
        width: 500,
        height: 500,
        border: "1px solid blue",
        position: "relative",
      }}
    >
      <button
        style={{ textAlign: "center" }}
        onClick={() => {
          setPosition({
            x: 250,
            y: 250,
          });
        }}
      >
        Set Position
      </button>
      <div
        ref={el}
        style={{
          position: "absolute",
          cursor: "move",
          zIndex: 10,
          touchAction: "none",
          padding: 10,
          border: "solid 1px",
          left: x,
          top: y,
          whiteSpace: "nowrap",
        }}
      >
        {isDragging ? "Dragging!" : "👋 Drag me!"}
        <div style={{ whiteSpace: "nowrap" }}>
          I am at {Math.round(x)}, {Math.round(y)}
        </div>
      </div>
    </div>
  );
};

```

---

## useDropZone

URL: https://reactuse.com/element/usedropzone/
Category: element
Description: useDropZone is a React hook that turns an element into a file drop zone — handles drag events and returns an over-zone boolean, with a dropped-files callback.
Import: `import { useDropZone } from '@reactuses/core'`

# useDropZone

Create an zone where files can be dropped

`useDropZone` turns a DOM element into a file drop target by handling the `dragenter`, `dragover`, `dragleave`, and `drop` events. It returns a boolean indicating whether a file is currently being dragged over the zone. When files are dropped, the provided callback receives an array of `File` objects (or `null` if no files were dropped).

### When to Use

- Building file upload interfaces where users drag and drop files from their desktop
- Creating media galleries or document managers with drag-and-drop support
- Implementing drag-and-drop zones in form builders or CMS editors

### Notes

- **Visual feedback**: Use the returned `isOver` boolean to highlight the drop zone (e.g., change border color or background) when a file is dragged over it.
- **Cleanup**: All drag-related event listeners are removed automatically when the component unmounts.
- See also `useDraggable` for making elements draggable within the page (element repositioning vs. file drops).

## Usage

```tsx live
function Demo() {
  const ref = useRef<HTMLDivElement>(null);

  const isOver = useDropZone(ref, (_files) => {});
  return (
    <div>
      <p>Drop files into dropZone</p>
      {/* <img src={logo} alt="" /> */}
      <div
        ref={ref}
        style={{
          minHeight: 200,
          display: "flex",
          alignItems: "center",
          justifyContent: "center",
          marginTop: "1.5rem",
          background: "rgba(156,163,175,0.1)",
        }}
      >
        <div> isOverDropZone: {JSON.stringify(isOver)}</div>
      </div>
    </div>
  );
};

```

---

## useElementBounding

URL: https://reactuse.com/element/useelementbounding/
Category: element
Description: useElementBounding is a React hook that reactively tracks an element's getBoundingClientRect — x, y, width, height, and edges, updating on scroll and resize.
Import: `import { useElementBounding } from '@reactuses/core'`

# useElementBounding

React Element Hook that tracks bounding box of an HTML element

`useElementBounding` reactively tracks the bounding rectangle of a DOM element using [`getBoundingClientRect()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect). It returns an object containing `x`, `y`, `top`, `bottom`, `left`, `right`, `width`, `height`, and an `update()` function for manual re-measurement. By default it automatically recalculates on window scroll and resize.

### When to Use

- Positioning tooltips, popovers, or floating elements relative to a target element
- Implementing collision detection or overlap checks between UI elements
- Tracking element position for scroll-linked animations or parallax effects

### Notes

- **Reactivity**: Automatically updates on window `resize` and `scroll` events by default. Both behaviors can be disabled via `windowResize` and `windowScroll` options.
- **SSR-safe**: Returns zero values during server-side rendering. Set `immediate: false` to defer the first measurement until you explicitly call `update()`.
- See also `useElementSize` and `useMeasure` for tracking only width/height via ResizeObserver, and `useWindowSize` for viewport dimensions.

## Usage

```tsx live
function Demo() {
  const ref = useRef<HTMLTextAreaElement>(null);
  const rect = useElementBounding(ref);
  return (
    <div>
      <p> Resize the box to see changes</p>
      <textarea ref={ref} readOnly value={JSON.stringify(rect, null, 2)} />
    </div>
  );
};

```

---

## useElementSize

URL: https://reactuse.com/element/useelementsize/
Category: element
Description: useElementSize is a React hook that tracks an element's width and height in real time using the ResizeObserver API, updating whenever the element resizes.
Import: `import { useElementSize } from '@reactuses/core'`

# useElementSize

React Sensor Hook that tracks size of an HTML element. [ResizeObserver MDN](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver)

`useElementSize` tracks the width and height of a DOM element in real time using the [ResizeObserver API](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver). It returns the current `width` and `height` as a reactive tuple that updates whenever the element is resized. Pass a ref to the target element and optional `ResizeObserverOptions` (e.g., `{ box: "border-box" }`) to control which box model is observed.

### When to Use

- Building responsive components that adapt based on their own size rather than viewport size
- Implementing container queries in older browsers that lack native support
- Dynamically sizing canvas elements, charts, or virtualized lists

### Notes

- **SSR-safe**: Returns `[0, 0]` during server-side rendering. Observation starts after mount.
- **Performance**: Uses ResizeObserver which is more efficient than polling or listening to window resize events. The observer is disconnected automatically on unmount.
- See also `useMeasure` for a similar hook that returns a full `DOMRect`, `useElementBounding` for position and size via `getBoundingClientRect`, and `useWindowSize` for viewport dimensions.

## Usage

```tsx live
function Demo() {
  const ref = useRef<HTMLTextAreaElement>(null);

  const [width, height] = useElementSize(ref, { box: "border-box" });

  return (
    <div>
      <div>Resize the box to see changes</div>
      <br />
      <textarea
        ref={ref}
        disabled
        style={{ width: 200, height: 200 }}
        value={`width: ${width}\nheight: ${height}`}
      />
    </div>
  );
};

```

---

## useElementVisibility

URL: https://reactuse.com/element/useelementvisibility/
Category: element
Description: useElementVisibility is a React hook that returns whether an element is visible within the viewport — built on useIntersectionObserver, with a stop control.
Import: `import { useElementVisibility } from '@reactuses/core'`

# useElementVisibility

React Element Hooks that tracks the visibility of an element within the viewport. A wrapper of `useIntersectionObserver`

`useElementVisibility` provides a simple boolean indicating whether a DOM element is currently visible within the viewport. It is built on top of `useIntersectionObserver` and abstracts away the complexity of the Intersection Observer API. It returns a tuple of `[isVisible, stop]` where `stop` is a function to disconnect the observer.

### When to Use

- Triggering animations or lazy-loading content when an element scrolls into view
- Implementing "read receipt" or "seen" tracking for feed items or notifications
- Conditionally rendering or pausing resource-intensive components when they are off-screen

### Notes

- **SSR-safe**: Returns `false` during server-side rendering since no DOM is available.
- **Customizable**: Accepts standard `IntersectionObserverInit` options (`root`, `rootMargin`, `threshold`) for fine-grained control over when visibility triggers.
- See also `useIntersectionObserver` for full access to `IntersectionObserverEntry` data, and `useDocumentVisibility` for page-level (tab) visibility.

## Usage

```tsx live
function Demo() {
  const ref = useRef<HTMLDivElement>(null);
  const [visible, stop] = useElementVisibility(ref);

  return (
    <div>
      <p>Info on the right bottom corner</p>
      <div
        ref={ref}
        style={{
          borderWidth: 2,
          borderStyle: "solid",
          padding: "1rem",
        }}
      >
        Target Element (scroll down)
      </div>
      <button
        onClick={() => {
          stop();
        }}
      >
        Stop
      </button>
      <div
        style={{
          borderWidth: 2,
          borderStyle: "solid",
          padding: "1rem",
          position: "fixed",
          bottom: 0,
          right: 0,
          zIndex: 100,
        }}
      >
        Element {visible ? "inside" : "outside"} the viewport
      </div>
    </div>
  );
};

```

---

## useFocus

URL: https://reactuse.com/element/usefocus/
Category: element
Description: useFocus is a React hook that tracks and controls an element's focus state — returns an isFocused boolean and a setter to focus or blur it.
Import: `import { useFocus } from '@reactuses/core'`

# useFocus

React Sensor Hooks that tracks element foucs state

`useFocus` tracks and controls the focus state of a specific DOM element. It returns a tuple of `[isFocused, setFocused]` -- a boolean indicating whether the element currently has focus, and a function to programmatically focus or blur it. You can optionally pass `true` as the second argument to auto-focus the element on mount.

### When to Use

- Building accessible form components that need to track and programmatically control focus
- Implementing focus management in modal dialogs, wizards, or multi-step forms
- Creating focus indicators or visual feedback that responds to focus state changes

### Notes

- **Two-way binding**: The returned setter calls `element.focus()` or `element.blur()` under the hood, so the DOM and React state stay in sync.
- **Initial focus**: Pass `true` as the `initialValue` parameter to focus the element immediately after mount.
- See also `useActiveElement` for tracking which element has focus globally across the entire document.

## Usage

```tsx live
function Demo() {
  const text = useRef<HTMLParagraphElement>(null);
  const input = useRef<HTMLInputElement>(null);
  const button = useRef<HTMLButtonElement>(null);

  const [paragraphFocus, setParagraphFocus] = useFocus(text);
  const [inputFocus, setInputFocus] = useFocus(input, true);
  const [buttonFocus, setButtonFocus] = useFocus(button);
  return (
    <div>
      <p ref={text} style={paragraphFocus ? { opacity: 0.5 } : {}} tabIndex={0}>
        Paragraph that can be focused
      </p>
      <input ref={input} placeholder="Input that can be focused" />
      <br />
      <br />
      <button ref={button} style={buttonFocus ? { opacity: 0.5 } : {}}>
        Button that can be focused
      </button>
      <br />
      <br />
      <hr />
      <p style={{ height: "2rem" }}>
        {paragraphFocus && "The paragraph has focus"}
        {inputFocus && "The input control has focus"}
        {buttonFocus && "The button has focus"}
      </p>
      <div>
        <button
          onClick={() => {
            setParagraphFocus(!paragraphFocus);
          }}
        >
          Focus text
        </button>
        <button
          onClick={() => {
            setInputFocus(!inputFocus);
          }}
        >
          Focus input
        </button>
        <button
          onClick={() => {
            setButtonFocus(!buttonFocus);
          }}
        >
          Focus button
        </button>
      </div>
    </div>
  );
};

```

---

## useIntersectionObserver

URL: https://reactuse.com/element/useintersectionobserver/
Category: element
Description: useIntersectionObserver is a React hook for the Intersection Observer API — observe an element and get entry updates when its viewport intersection changes.
Import: `import { useIntersectionObserver } from '@reactuses/core'`

# useIntersectionObserver

React sensor hook that tracks the changes in the intersection of a target element with an ancestor element or with a top-level document's viewport. Uses the [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) and returns a [IntersectionObserverEntry](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry)

`useIntersectionObserver` wraps the native [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) in a React-friendly interface. It observes a target element and fires a callback with the full `IntersectionObserverEntry` array whenever the element's intersection with a root container changes. The hook returns a `stop` function to disconnect the observer early.

### When to Use

- Implementing infinite scroll by detecting when a sentinel element enters the viewport
- Lazy-loading images or heavy components only when they become visible
- Triggering scroll-based animations or analytics events at specific intersection thresholds

### Notes

- **Configurable**: Supports all standard `IntersectionObserverInit` options (`root`, `rootMargin`, `threshold`) for precise control over when the callback fires.
- **Cleanup**: The observer is automatically disconnected on unmount. Call the returned `stop` function to disconnect manually if needed.
- See also `useElementVisibility` for a simplified boolean-only wrapper around this hook.

## Usage

```tsx live
function Demo() {
  const Spacer = () => (
    <div
      style={{
        width: "200px",
        height: "300px",
      }}
    />
  );

  const options = {
    root: null,
    rootMargin: "0px",
    threshold: 1,
  };

  const intersectionRef = useRef(null);
  const [entry, setEntry] = useState<IntersectionObserverEntry[]>([]);
  const stop = useIntersectionObserver(
    intersectionRef,
    (entry) => {
      setEntry(entry);
    },
    options
  );

  return (
    <div
      style={{
        width: "400px",
        height: "400px",
        overflow: "scroll",
      }}
    >
      Scroll me
      <Spacer />
      <button
        onClick={() => {
          stop();
        }}
      >
        stop observe
      </button>
      <div
        ref={intersectionRef}
        style={{
          width: "100px",
          height: "100px",
          padding: "20px",
          background: "var(--c-hj-b)",
        }}
      >
        {entry[0] && entry[0].intersectionRatio < 1
          ? "Obscured"
          : "Fully in view"}
      </div>
      <Spacer />
    </div>
  );
};

```

---

## useMeasure

URL: https://reactuse.com/element/usemeasure/
Category: element
Description: useMeasure is a React hook that tracks an element's full dimensions (a DOMRect) using the ResizeObserver API — returns the rect and a stop control.
Import: `import { useMeasure } from '@reactuses/core'`

# useMeasure

React sensor hook that tracks dimensions of an HTML element using the Resize Observer API

`useMeasure` tracks the full dimensions of a DOM element using the [ResizeObserver API](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver). It returns a tuple of `[rect, stop]` where `rect` is a `DOMRect`-like object containing `x`, `y`, `width`, `height`, `top`, `right`, `bottom`, and `left`, and `stop` is a function to disconnect the observer. Pass a ref to the element and optional `ResizeObserverOptions`.

### When to Use

- Measuring element dimensions for layout calculations that need full bounding-box data
- Building responsive containers that adjust internal layout based on their own size
- Tracking size changes in dynamically resizable components like text editors or split panes

### Notes

- **SSR-safe**: Returns zeroed-out rect values during server-side rendering. Observation begins after mount.
- **Stoppable**: Call the returned `stop` function to disconnect the ResizeObserver when measurement is no longer needed.
- See also `useElementSize` for a simpler `[width, height]` tuple, `useElementBounding` for position-aware measurements via `getBoundingClientRect`, and `useResizeObserver` for direct access to the raw ResizeObserver callback.

## Usage

```tsx live
function Demo() {
  const ref = useRef<HTMLTextAreaElement>(null);
  const [rect, stop] = useMeasure(ref);

  return (
    <div>
      <div>Resize the box to see changes</div>
      <div>
        <button onClick={() => stop()}>stop observe</button>
      </div>
      <br />
      <textarea
        ref={ref}
        disabled
        style={{ width: 286, height: 166 }}
        value={JSON.stringify(rect, null, 2)}
      />
    </div>
  );
};

```

---

## useMutationObserver

URL: https://reactuse.com/element/usemutationobserver/
Category: element
Description: useMutationObserver is a React hook for the MutationObserver API — watch for DOM changes in an element's subtree and receive MutationRecord updates.
Import: `import { useMutationObserver } from '@reactuses/core'`

# useMutationObserver

Watch for changes being made to the DOM tree. [MutationObserver MDN](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver)

`useMutationObserver` wraps the native [MutationObserver API](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) to watch for changes in the DOM subtree of a target element. It fires a callback with the list of `MutationRecord` entries whenever observed mutations occur. The hook returns a `stop` function to disconnect the observer at any time.

### When to Use

- Reacting to attribute changes on elements controlled by third-party libraries
- Monitoring dynamic DOM changes such as child node additions or removals in content-editable areas
- Building devtools or debugging utilities that track DOM mutations in real time

### Notes

- **Configuration**: Pass standard `MutationObserverInit` options (`attributes`, `childList`, `subtree`, `characterData`, etc.) to control which types of mutations are observed.
- **Cleanup**: The observer is automatically disconnected on unmount. Use the returned `stop` function for early disconnection.
- See also `useResizeObserver` for observing size changes and `useIntersectionObserver` for visibility changes.

## Usage

```tsx live
function Demo() {
  const options = { attributes: true };
  const [width, setWidth] = useState(200);
  const [count, setCount] = useState(0);

  const ref = useRef<HTMLDivElement>(null);

  const stop = useMutationObserver(
    (mutationsList) => {
      mutationsList.forEach(() => setCount(c => c + 1));
    },
    ref,
    options,
  );

  useEffect(() => {
    setWidth(300);
  }, []);

  return (
    <div>
      <div
        ref={ref}
        style={{
          width,
          padding: 12,
          border: "1px solid #000",
          marginBottom: 8,
        }}
      >
        current width：{width}
      </div>
      <button onClick={() => setWidth(w => w + 10)}>widening</button>
      <button onClick={() => stop()}>stop observe</button>
      <p>Mutation count {count}</p>
    </div>
  );
};

```

---

## useResizeObserver

URL: https://reactuse.com/element/useresizeobserver/
Category: element
Description: useResizeObserver is a React hook for the ResizeObserver API — watch an element for size changes and receive entry updates, with box-model options.
Import: `import { useResizeObserver } from '@reactuses/core'`

# useResizeObserver

Watch size of an HTML element. [ResizeObserver MDN](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver)

`useResizeObserver` wraps the native [ResizeObserver API](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver) to watch for size changes on a DOM element. It invokes a callback with the full `ResizeObserverEntry` array whenever the element's dimensions change. The hook returns a `stop` function to disconnect the observer. You can also pass `ResizeObserverOptions` to control which box model (`content-box`, `border-box`, or `device-pixel-content-box`) is observed.

### When to Use

- Executing custom logic (e.g., recalculating layouts or redrawing canvases) in response to element size changes
- Building wrapper components that need raw ResizeObserver entries for advanced measurement logic
- Observing size changes on elements that resize independently of the window (e.g., resizable panels, flex items)

### Notes

- **Performance**: ResizeObserver is much more efficient than polling element dimensions or listening to window resize events. The callback fires only when the observed element actually changes size.
- **Cleanup**: The observer is automatically disconnected on unmount. Call the returned `stop` function to disconnect manually at any time.
- See also `useElementSize` for a simple `[width, height]` return value, and `useMeasure` for a full `DOMRect` return value -- both built on top of ResizeObserver.

## Usage

```tsx live
function Demo() {
  const ref = useRef<HTMLTextAreaElement>(null);
  const [width, setWidth] = useState(0);
  const [height, setHeight] = useState(0);
  const stop = useResizeObserver(ref, (entries) => {
    const [entry] = entries;
    const { width, height } = entry.contentRect;
    setWidth(width);
    setHeight(height);
  });

  return (
    <div>
      <div>Resize the box to see changes</div>
      <div>
        <button onClick={() => stop()}>stop observe</button>
      </div>
      <br />
      <textarea
        ref={ref}
        disabled
        style={{ width: 286, height: 166 }}
        value={`width: ${width}\nheight: ${height}`}
      />
    </div>
  );
};

```

---

## useSticky

URL: https://reactuse.com/element/usesticky/
Category: element
Description: useSticky is a React hook that detects when an element scrolls past a threshold and should become sticky — returns an isSticky state with offset and axis config.
Import: `import { useSticky } from '@reactuses/core'`

# useSticky

React Hook that tracks element sticky

`useSticky` detects whether an element has scrolled past a threshold and should become "sticky." It works by observing the scroll position of a container (or the window) relative to a guard element and returns a tuple of `[isSticky, setIsSticky]`. You configure it with a `nav` offset (e.g., a fixed header height) and optionally specify the scroll axis (`x` or `y`).

### When to Use

- Implementing sticky headers, navigation bars, or sidebars that pin after scrolling past a certain point
- Building "back to top" buttons or floating action bars that appear after scrolling
- Creating scroll-aware UI that changes style or behavior based on scroll position relative to a marker element

### Notes

- **Scroll container**: By default, the hook listens to the window scroll. Pass a third `scrollElement` ref to observe scrolling within a specific container.
- **Axis support**: Set `axis: 'x'` in the params to track horizontal scrolling instead of the default vertical (`'y'`).
- See also `useWindowScroll` for tracking the raw scroll position of the window.

## Usage

```tsx live
function Demo() {
  const element = useRef<HTMLDivElement>(null);
  const [isSticky] = useSticky(element, {
    // header fixed height
    nav: 64,
  });

  const stickyStyle: CSSProperties = isSticky
    ? {
        position: "fixed",
        top: 64,
        zIndex: 50,
        height: 20,
      }
    : {
        height: 20,
      };

  const guardStyle: CSSProperties = {
    width: 1,
    height: 1,
  };

  return (
    <div style={{height: 300,overflow: 'scroll'}}>
      <div ref={element} style={guardStyle} />
      <button style={stickyStyle}>
        {isSticky ? "stickying" : "not sticky"}
      </button>
      <div style={{ height: "100vh" }} />
    </div>
  );
};

```

---

## useWindowFocus

URL: https://reactuse.com/element/usewindowfocus/
Category: element
Description: useWindowFocus is a React hook that reactively tracks whether the browser window has focus, updating via the window focus and blur events.
Import: `import { useWindowFocus } from '@reactuses/core'`

# useWindowsFocus

React Element Hook that tracks window focus with `window.onfocus` and `window.onblur` events

`useWindowsFocus` reactively tracks whether the browser window currently has focus by listening to `window.onfocus` and `window.onblur` events. It returns a boolean that is `true` when the window is focused and `false` when it is not. You can optionally provide a default value for the initial state.

### When to Use

- Pausing real-time updates (e.g., WebSocket messages or polling) when the user switches to another application
- Showing visual indicators like "you are away" or dimming the UI when the window loses focus
- Resuming or refreshing data when the user returns to the application window

### Notes

- **SSR-safe**: Returns the provided `defaultValue` (or `true`) during server-side rendering since `window` is not available.
- **Cleanup**: Event listeners are removed automatically when the component unmounts.
- See also `useDocumentVisibility` for tracking tab visibility (which also covers minimized windows), and `useFocus` for tracking focus on individual elements.

## Usage

```tsx live
function Demo() {
  const focus = useWindowsFocus();
  return (
    <div>
      <p>
        {focus
          ? "💡 Click somewhere outside of the document to unfocus."
          : "ℹ Tab is unfocused"}
      </p>
    </div>
  );
};

```

---

## useWindowScroll

URL: https://reactuse.com/element/usewindowscroll/
Category: element
Description: useWindowScroll is a React hook that returns the browser window's current x and y scroll position as reactive state, updating on every scroll.
Import: `import { useWindowScroll } from '@reactuses/core'`

# useWindowScroll

useWindowScroll is a React Hook that is used to get the scroll position of the browser window

`useWindowScroll` returns the current horizontal (`x`) and vertical (`y`) scroll position of the browser window as a reactive state object. It listens to the `scroll` event on the window and updates the values whenever the user scrolls. This provides a simple way to access `window.scrollX` and `window.scrollY` as React state.

### When to Use

- Building scroll-progress indicators or reading-position trackers
- Implementing parallax scrolling effects or scroll-linked animations
- Showing or hiding UI elements (e.g., "back to top" buttons) based on the current scroll position

### Notes

- **SSR-safe**: Returns `{ x: 0, y: 0 }` during server-side rendering since `window` is not available.
- **Performance**: The hook listens to the window `scroll` event. For high-frequency scroll tracking, consider combining with `requestAnimationFrame` or throttling in your consuming component.
- See also `useSticky` for detecting when an element should become sticky, and `useWindowSize` for tracking viewport dimensions.

## Usage

```tsx live
function Demo() {
  return (
    <div>
      <div>
        <iframe
          src="https://codesandbox.io/embed/dreamy-lehmann-mzg96r?fontsize=14&hidenavigation=1&theme=dark"
          style={{
            width: "100%",
            height: 500,
            border: 0,
            borderRadius: 4,
            overflow: "hidden",
          }}
          title="dreamy-lehmann-mzg96r"
          allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
          sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
        >
        </iframe>
      </div>
    </div>
  );
};

```

---

## useWindowSize

URL: https://reactuse.com/element/usewindowsize/
Category: element
Description: useWindowSize is a React hook that reactively tracks the browser window's inner width and height, updating automatically whenever the window is resized.
Import: `import { useWindowSize } from '@reactuses/core'`

# useWindowSize

React Element Hooks that tracks window size

`useWindowSize` reactively tracks the browser window's `innerWidth` and `innerHeight`. It returns an object with `width` and `height` properties that update automatically whenever the window is resized. This is useful for any component logic that depends on viewport dimensions.

### When to Use

- Building responsive layouts that need to adapt logic (not just CSS) based on viewport size
- Dynamically calculating how many items to render in a grid or virtual list
- Adjusting canvas, chart, or map dimensions to fill the available viewport

### Notes

- **SSR-safe**: Returns `{ width: 0, height: 0 }` during server-side rendering since `window` is not available.
- **Performance**: Listens to the window `resize` event. The observer is cleaned up automatically on unmount.
- See also `useElementSize` for tracking the size of a specific element, and `useElementBounding` for full bounding-box data including position.

## Usage

```tsx live
function Demo() {
  const { width, height } = useWindowSize();

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

```

---

# Browser hooks (50)

## useBroadcastChannel

URL: https://reactuse.com/browser/usebroadcastchannel/
Category: browser
Description: useBroadcastChannel is a React hook for the BroadcastChannel API — send and receive messages between browser tabs, windows, and iframes on the same origin.
Import: `import { useBroadcastChannel } from '@reactuses/core'`

# useBroadcastChannel

`useBroadcastChannel` is a hook that allows you to use the `BroadcastChannel API` in your components.

`useBroadcastChannel` wraps the [BroadcastChannel API](https://developer.mozilla.org/en-US/docs/Web/API/BroadcastChannel) to enable simple messaging between browsing contexts (tabs, windows, iframes) on the same origin. It returns an object containing the current `data`, a `post` function for sending messages, connection status, error state, and a `close` function. The hook automatically manages the channel lifecycle and cleans up on unmount.

### When to Use

- Synchronizing state across multiple open tabs of the same application (e.g., theme changes, logout events)
- Broadcasting real-time updates to all open instances of your app without a server
- Coordinating actions between iframes or popup windows on the same origin

### Notes

- **SSR-safe**: Returns `isSupported: false` and no-op functions during server-side rendering. No `BroadcastChannel` constructor is called on the server.
- **Browser support**: Supported in all modern browsers. Check `isSupported` before relying on channel functionality.
- **Same-origin only**: The BroadcastChannel API only works between browsing contexts of the same origin.

## Usage

```tsx live
function Demo() {
  const { isSupported, data, post, error,timeStamp } = useBroadcastChannel({
    name: "reactuse-demo-channel",
  });

  const [message, setMessage] = useState("");

  useEffect(() => {
    if (isSupported) {
      alert(data);
    }
  }, [data]);

  return (
    <div>
      <p>Supported: {JSON.stringify(isSupported)}</p>
      <p>Please open this page in at least two tabs</p>
      <p>
        <b>Channel:</b> reactuse-demo-channel
      </p>
      <p>
        <b>Message:</b> {data}<br/>
        <b>TimeStamp:</b> {timeStamp}
      </p>
      <input
        value={message}
        onChange={(event) => {
          setMessage(event.currentTarget.value);
        }}
      />
      <button
        onClick={() => post(message)}
        style={{
          cursor: isSupported ? "pointer" : "not-allowed",
        }}
      >
        Send
      </button>
      {error && <p>Error: {error.message}</p>}
    </div>
  );
};

```

---

## useClipboard

URL: https://reactuse.com/browser/useclipboard/
Category: browser
Description: useClipboard is a React hook to read from and write to the system clipboard via the Clipboard API, returning the copied text, a copy function, and Clipboard API support status.
Import: `import { useClipboard } from '@reactuses/core'`

# useClipboard

Copy text to a user's clipboard

`useClipboard` provides a simple interface for reading and writing to the system clipboard using the [Clipboard API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API). It returns a tuple of the most recently copied text, a `copy` function, and whether the Clipboard API is supported. When the Clipboard API is unavailable, copying falls back to `document.execCommand("copy")`, while copy and cut events read the current text selection.

### When to Use

- Adding "copy to clipboard" buttons for code snippets, URLs, or share links
- Building a paste-from-clipboard feature in forms or editors
- Implementing copy functionality in data tables or dashboards

### Notes

- **SSR-safe**: Returns an empty string, a copy function, and `false` during server-side rendering. No `navigator` access occurs on the server.
- **Browser support**: `isSupported` reports whether `navigator.clipboard` is available. Copying still falls back to `document.execCommand("copy")` in browsers without the Clipboard API.
- **Permissions**: Some browsers require user permission for Clipboard API access. Use alongside `usePermission` to check `clipboard-read` and `clipboard-write` status.

## Usage

```tsx live
function Demo() {
  const [value, setValue] = useState("");
  const [text, copy, isSupported] = useClipboard();
  const permissionRead = usePermission("clipboard-read");
  const permissionWrite = usePermission("clipboard-write");
  return (
    <div>
      <p>
        Clipboard Permission: read <b>{permissionRead}</b> | write&nbsp;
        <b>{permissionWrite}</b>
      </p>
      <p>
        Clipboard API supported: <b>{isSupported ? "yes" : "no"}</b>
      </p>
      <p>
        Current copied: <code>{text || "none"}</code>
      </p>
      <input
        value={value}
        onChange={(event) => {
          setValue(event.currentTarget.value);
        }}
      />
      <button onClick={() => copy(value)}>Copy</button>
    </div>
  );
};

```

---

## useColorMode

URL: https://reactuse.com/browser/usecolormode/
Category: browser
Description: useColorMode is a React hook for reactive color mode (theme) switching, with automatic localStorage persistence, CSS class control, and a cycle helper.
Import: `import { useColorMode } from '@reactuses/core'`

# useColorMode

Reactive color mode (theme) with auto data persistence and flexible configuration.

`useColorMode` manages multi-theme color modes by applying CSS class names or HTML attributes to a target element (default: `<html>`) and persisting the selection to `localStorage`. It returns a tuple of the current mode string, a setter function, and a `cycle` function that rotates through the available modes. You can configure available modes, custom class name mappings, storage key, storage backend, and the DOM attribute used.

### When to Use

- Building applications with multiple themes beyond just light/dark (e.g., blue, green, sepia)
- Creating a theme selector with cycle-through functionality
- Persisting the user's color mode choice across sessions with automatic localStorage sync

### Notes

- **SSR-safe**: Returns the `defaultValue` (or `null`) during server-side rendering. No DOM or localStorage access occurs on the server. See the Tips section below for preventing flash of unstyled content.
- **Persistence**: By default, persists to `localStorage` under the key `"reactuses-color-mode"`. You can customize the storage key and backend (e.g., `sessionStorage`).
- **Related hooks**: For simple dark/light toggle, see `useDarkMode`. For detecting the system preference, see `usePreferredColorScheme`.

## New in v6.1.0

**useColorMode is the more flexible successor to useDarkMode.** Key differences:

- **useColorMode**: Supports multiple themes (light, dark, blue, green, etc.)
- **useDarkMode**: Limited to dark/light modes only, but maintains boolean API for compatibility

Both hooks now use string storage internally. Choose `useColorMode` for new projects requiring multiple themes.

## Tips

<details>
<summary>click to open</summary>

For server-side rendered applications, since it's not possible to obtain the user's color preference on the server side, there might be a flicker during the first render. To avoid this issue, you can refer to the following steps.

1. add a script before your content.

```tsx
<script
  dangerouslySetInnerHTML={{
    __html: `
          (function () {
            function setMode(mode) {
              if (mode) {
                document.documentElement.classList.add(mode);
              }
            }
            let store = localStorage.getItem('reactuses-color-mode');
            let mode;
            if(store === null){
              const darkQuery = window.matchMedia('(prefers-color-scheme: dark)');
              mode = darkQuery.matches ? 'dark' : 'light';
            }else {
              mode = store || 'light';
            }
            setMode(mode)
          })();
      `,
  }}
></script>
```

2. To conveniently manage color modes in a unified way, we recommend using context to store them.

```tsx


type ThemeContext = {
  theme: string | null;
  setTheme: (theme: string) => void;
  cycleTheme: () => void;
};

const ThemeContext = createContext<ThemeContext | undefined>(undefined);

export function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [theme, setTheme, cycleTheme] = useColorMode({
    modes: ['light', 'dark', 'auto'],
    defaultValue: 'auto',
    storageKey: 'my-app-theme',
  });

  return (
    <ThemeContext.Provider value={{ theme, setTheme, cycleTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}

export function useTheme() {
  const context = useContext(ThemeContext);
  if (context === undefined) {
    throw new Error("useTheme must be used within a ThemeProvider");
  }
  return context;
}
```

</details>

## Usage

### Basic Usage

```tsx live
function Demo() {
  const [colorMode, setColorMode, cycle] = useColorMode({
    modes: ['light', 'dark'],
    defaultValue: 'light',
  });

  return (
    <div>
      <div>Current mode: {colorMode}</div>
      <br />
      <div>
        <button onClick={() => setColorMode('light')}>Light</button>
        <button onClick={() => setColorMode('dark')}>Dark</button>
        <button onClick={cycle}>Cycle</button>
      </div>
    </div>
  );
}
```

### Multiple Color Themes

```tsx live
function Demo() {
  const [colorMode, setColorMode, cycle] = useColorMode({
    modes: ['light', 'dark', 'blue', 'green', 'purple', 'sepia'],
    defaultValue: 'light',
    modeClassNames: {
      light: 'theme-light',
      dark: 'theme-dark',
      blue: 'theme-blue',
      green: 'theme-green',
      purple: 'theme-purple',
      sepia: 'theme-sepia'
    }
  });

  const themeColors = {
    light: '#f8f9fa',
    dark: '#343a40',
    blue: '#0d6efd',
    green: '#198754',
    purple: '#6f42c1',
    sepia: '#8b4513'
  };

  return (
    <div style={{
      padding: '20px',
      backgroundColor: themeColors[colorMode] || '#f8f9fa',
      color: ['dark', 'blue', 'green', 'purple', 'sepia'].includes(colorMode) ? 'white' : 'black',
      borderRadius: '8px',
      transition: 'all 0.3s ease'
    }}>
      <div>Current theme: <strong>{colorMode}</strong></div>
      <br />
      <div style={{ display: 'flex', flexWrap: 'wrap', gap: '8px' }}>
        {['light', 'dark', 'blue', 'green', 'purple', 'sepia'].map(mode => (
          <button
            key={mode}
            onClick={() => setColorMode(mode)}
            style={{
              padding: '8px 16px',
              border: colorMode === mode ? '2px solid #007bff' : '1px solid #ccc',
              borderRadius: '4px',
              backgroundColor: colorMode === mode ? '#007bff' : 'white',
              color: colorMode === mode ? 'white' : 'black',
              cursor: 'pointer',
              textTransform: 'capitalize'
            }}
          >
            {mode}
          </button>
        ))}
      </div>
      <br />
      <button
        onClick={cycle}
        style={{
          padding: '10px 20px',
          backgroundColor: '#28a745',
          color: 'white',
          border: 'none',
          borderRadius: '4px',
          cursor: 'pointer'
        }}
      >
        Cycle Themes
      </button>
    </div>
  );
}
```

### Using Data Attributes

```tsx live
function Demo() {
  const [colorMode, setColorMode, cycle] = useColorMode({
    modes: ['light', 'dark'],
    defaultValue: 'light',
    attribute: 'data-theme',
    selector: 'body'
  });

  return (
    <div>
      <div>Current mode: {colorMode}</div>
      <div>Check the body element's data-theme attribute!</div>
      <br />
      <div>
        <button onClick={() => setColorMode('light')}>Light</button>
        <button onClick={() => setColorMode('dark')}>Dark</button>
        <button onClick={cycle}>Cycle</button>
      </div>
    </div>
  );
}
```

---

## useCopyToClipboard

URL: https://reactuse.com/browser/usecopytoclipboard/
Category: browser
Description: useCopyToClipboard is a React hook alias for useClipboard, using the same implementation and returning the copied text, a copy function, and Clipboard API support status.
Import: `import { useCopyToClipboard } from '@reactuses/core'`

# useCopyToClipboard

Copy text to a user's clipboard.

:::info
`useCopyToClipboard` is an alias for [`useClipboard`](/browser/useclipboard). It uses the same implementation and returns `[text, copy, isSupported]`; see `useClipboard` for the complete Clipboard API and legacy fallback behavior.
:::

`useCopyToClipboard` wraps the [Clipboard API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API) through the same implementation as `useClipboard`, returning the copied text, a `copy` function, and the `isSupported` status.

### When to Use

- Adding "copy to clipboard" functionality when you prefer the `useCopyToClipboard` naming convention
- Migrating from other hook libraries that use this naming pattern
- Any scenario where the `useClipboard` behavior is needed under this related hook name

### Notes

- **SSR-safe**: Returns an empty string, a copy function, and `false` during server-side rendering. No `navigator` access occurs on the server.
- **Browser support**: `isSupported` reports whether `navigator.clipboard` is available. Copying still falls back to `document.execCommand("copy")` when needed.
- **Permissions**: Some browsers require user permission for Clipboard API access. Use alongside `usePermission` to check `clipboard-read` and `clipboard-write` status.

## Usage

```tsx live
function Demo() {
  const [value, setValue] = useState("");
  const [text, copy, isSupported] = useCopyToClipboard();
  const permissionRead = usePermission("clipboard-read");
  const permissionWrite = usePermission("clipboard-write");
  return (
    <div>
      <p>
        Clipboard Permission: read <b>{permissionRead}</b> | write&nbsp;
        <b>{permissionWrite}</b>
      </p>
      <p>
        Clipboard API supported: <b>{isSupported ? "yes" : "no"}</b>
      </p>
      <p>
        Current copied: <code>{text || "none"}</code>
      </p>
      <input
        value={value}
        onChange={(event) => {
          setValue(event.currentTarget.value);
        }}
      />
      <button onClick={() => copy(value)}>Copy</button>
    </div>
  );
};

```

---

## useCssVar

URL: https://reactuse.com/browser/usecssvar/
Category: browser
Description: useCssVar is a React hook to read and write CSS custom properties (variables) on a DOM element, optionally observing external changes via MutationObserver.
Import: `import { useCssVar } from '@reactuses/core'`

# useCssVar

Manipulate CSS variables

`useCssVar` reads and writes [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) (variables) on a target DOM element. It returns a tuple of the current variable value and a setter function. Optionally, it can observe changes via `MutationObserver` so the returned value stays in sync when external code modifies the variable.

### When to Use

- Dynamically theming components by reading and updating CSS custom properties at runtime
- Building color pickers or style editors that manipulate CSS variables on specific elements
- Synchronizing React state with CSS variables for animations or transitions

### Notes

- **SSR-safe**: Returns the provided default value and a no-op setter during server-side rendering. No DOM access occurs on the server.
- **MutationObserver**: Set `observe: true` in options to automatically track external changes to the CSS variable via [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver).
- **Target element**: The hook requires a ref to a specific DOM element; changes are scoped to that element's inline style.

## Usage

```tsx live
function Demo() {
  const key = "--color";
  const ref = useRef<HTMLDivElement>(null);
  const [color, setColor] = useCssVar(key, ref, "");
  const style: any = {
    "--color": "#7fa998",
    "color": "var(--color)",
  };

  const switchColor = () => {
    if (color === "#df8543") {
      setColor("#7fa998");
    }
    else {
      setColor("#df8543");
    }
  };

  return (
    <section>
      <div ref={ref} style={style}>
        Sample text, <>{color}</>
      </div>
      <button onClick={switchColor}>Change Color</button>
    </section>
  );
};

```

---

## useDarkMode

URL: https://reactuse.com/browser/usedarkmode/
Category: browser
Description: useDarkMode is a React hook for a dark and light mode toggle, with automatic localStorage persistence and prefers-color-scheme system preference syncing.
Import: `import { useDarkMode } from '@reactuses/core'`

# useDarkMode

dark mode with auto data persistence.

`useDarkMode` provides a simple dark/light mode toggle with automatic persistence to `localStorage`. It returns a tuple of the current theme state and a toggle function. The hook applies CSS class names (configurable as `classNameDark` and `classNameLight`) to the `<html>` element and syncs with the user's system preference via the `prefers-color-scheme` media query when no stored value exists. It respects the system preference as a default but allows the user to override it.

### When to Use

- Adding a dark mode toggle to your application with automatic persistence
- Building a theme switcher that respects the user's system color scheme preference as a default
- Applying dark/light CSS classes to the root element for CSS-driven theming

### Notes

- **SSR-safe**: Returns `false` for the dark mode state during server-side rendering. No DOM or localStorage access occurs on the server. See the Tips section below for preventing flash of unstyled content.
- **Persistence**: Stores the preference in `localStorage` under the key `"reactuses-color-scheme"`. The stored value is automatically migrated from the old boolean format to the new string format in v6.1.0+.
- **Related hooks**: For multi-theme support beyond dark/light, see `useColorMode`. For detecting the system preference without persistence, see `usePreferredDark` or `usePreferredColorScheme`.

## Breaking Change in v6.1.0

**Storage format has changed from boolean to string values.** If you're upgrading from a previous version:

- **Old format**: `true`/`false` boolean values
- **New format**: `"dark"`/`"light"` string values
- **Auto-migration**: Existing data will be automatically migrated
- **SSR scripts**: Need to be updated to handle string comparisons

<details>
<summary>Migration Guide</summary>

If you have custom SSR scripts, update them as shown in the examples below. The library handles data migration automatically, but your custom scripts need to handle both old and new formats during the transition period.

</details>

## Tips

<details>
<summary>click to open</summary>

For server-side rendered applications, since it's not possible to obtain the user's color preference on the server side, there might be a flicker during the first render. To avoid this issue, you can refer to the following steps.

1. add a script before your content.

```tsx
<script
  dangerouslySetInnerHTML={{
    __html: `
          (function () {
            function setDark(dark) {
              dark &&  document.documentElement.classList.add('dark');
            }
            let store = localStorage.getItem('reactuses-color-scheme');
            let dark;
            if(store === null){
              const darkQuery = window.matchMedia('(prefers-color-scheme: dark)');
              dark = darkQuery.matches;
            }else {
              if (store === 'true' || store === 'false') {
                const boolValue = store === 'true';
                const stringValue = boolValue ? 'dark' : 'light';
                localStorage.setItem('reactuses-color-scheme', stringValue);
                dark = boolValue;
              } else {
                dark = store === 'dark';
              }
            }
            setDark(dark)
          })();
      `,
  }}
></script>
```

2. To conveniently manage theme colors in a unified way, we recommend using context to store them.

```tsx


type ThemeContext = { theme: boolean; toggleTheme: () => void };

const ThemeContext = createContext<ThemeContext | undefined>(undefined);

export function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [dark, toggle] = useDarkMode({
    classNameDark: "dark",
    classNameLight: "light",
    defaultValue: false,
  });

  return (
    <ThemeContext.Provider value={{ theme: !!dark, toggleTheme: toggle }}>
      {children}
    </ThemeContext.Provider>
  );
}

export function useTheme() {
  const context = useContext(ThemeContext);
  if (context === undefined) {
    throw new Error("useTheme must be used within a ThemeProvider");
  }
  return context;
}
```

</details>

## Usage

```tsx live
function Demo() {
  const [theme, toggleDark] = useDarkMode({
    classNameDark: "dark",
    classNameLight: "light",
    defaultValue: false,
  });

  return (
    <div>
      <div>theme: {theme ? "dark" : "light"}</div>
      <br />
      <div>
        <button onClick={toggleDark}>toggleDark</button>
      </div>
    </div>
  );
}
```

---

## useDevicePixelRatio

URL: https://reactuse.com/browser/usedevicepixelratio/
Category: browser
Description: useDevicePixelRatio is a React hook that reactively tracks window.devicePixelRatio, updating on display, zoom level, or monitor changes.
Import: `import { useDevicePixelRatio } from '@reactuses/core'`

# useDevicePixelRatio

`useDevicePixelRatio` is a hook that returns the device pixel ratio of the screen.

`useDevicePixelRatio` reactively tracks [`window.devicePixelRatio`](https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio), which indicates the ratio of physical pixels to CSS pixels on the current display. It returns an object with a `pixelRatio` property that updates automatically when the user moves the window between displays with different densities or changes their system zoom level.

### When to Use

- Rendering high-DPI (Retina) images or canvas elements at the correct resolution
- Adjusting visual fidelity or detail level based on display density
- Debugging or displaying device display characteristics in developer tools

### Notes

- **SSR-safe**: Returns a default `pixelRatio` of `1` during server-side rendering. No `window` access occurs on the server.
- **Reactive updates**: Listens for changes via [`matchMedia`](https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia) so the value updates when display density changes (e.g., dragging a window between monitors).
- **Related hooks**: See also `useMediaQuery` for general media query tracking.

## Usage

```tsx live
function Demo() {
  const { pixelRatio } = useDevicePixelRatio();

  return <p>Device pixel ratio: {pixelRatio}</p>;
};

```

---

## useElementByPoint

URL: https://reactuse.com/browser/useelementbypoint/
Category: browser
Description: useElementByPoint is a React hook that returns the DOM element at given x and y coordinates via elementFromPoint, with interval or rAF polling.
Import: `import { useElementByPoint } from '@reactuses/core'`

# useElementByPoint

`useElementByPoint` is a hook that returns the element at a given point. It is useful for implementing drag and drop, or for any other use case where you need to know what element is at a given point.

`useElementByPoint` wraps [`document.elementFromPoint()`](https://developer.mozilla.org/en-US/docs/Web/API/Document/elementFromPoint) (or `elementsFromPoint()` in multi mode) to reactively query the DOM element at given x/y coordinates. It supports polling on an interval or via `requestAnimationFrame`, and returns a pausable object with the matched element, an `isSupported` flag, and `pause`/`resume` controls.

### When to Use

- Building element-inspection tools or visual debuggers that highlight hovered elements
- Implementing custom drag-and-drop logic that needs to detect drop targets at specific coordinates
- Creating interactive tutorials or onboarding overlays that identify UI elements under the cursor

### Notes

- **SSR-safe**: Returns `isSupported: false` and `null` element during server-side rendering. No `document` access occurs on the server.
- **Performance**: Use the `interval` option to control polling frequency. `requestAnimationFrame` provides the smoothest updates but uses more CPU.
- **Related hooks**: Combine with `useMouse` to track cursor position, and `useElementBounding` to get dimensions of the detected element.

## Usage

```tsx live noInline
function Demo() {
  const { clientX: x, clientY: y } = useMouse();
  const { element, pause, resume } = useElementByPoint({ x, y });
  const bounding = useElementBounding(element);

  useEventListener("scroll", bounding.update, null, { capture: true });
  const boxStyles = (() => {
    if (element) {
      return {
        display: "block",
        width: `${bounding.width}px`,
        height: `${bounding.height}px`,
        left: `${bounding.left}px`,
        top: `${bounding.top}px`,
        backgroundColor: "#3eaf7c44",
        transition: "all 0.05s linear",
        position: "fixed",
        pointerEvents: "none",
        zIndex: 9999,
        border: "1px solid var(--vp-c-brand)",
      };
    }
    return {
      display: "none",
    };
  })();
  const pointStyles = (() => ({
    transform: `translate(calc(${x}px - 50%), calc(${y}px - 50%))`,
    position: "fixed",
    top: 0,
    left: 0,
    pointerEvents: "none",
    width: "8px",
    height: "8px",
    borderRadius: "50%",
    backgroundColor: "#4ade80",
    boxShadow: "0 0 2px rgba(0,0,0,0.3)",
    zIndex: 999,
  }))();

  return (
    <>
      <div style={boxStyles} />
      <div style={pointStyles} />
      <div style={{ display: "flex", alignItems: "center" }}>
        <span style={{ marginRight: "16px" }}>X: {x}</span>
      </div>
      <div style={{ display: "flex", alignItems: "center" }}>
        <span style={{ marginRight: "16px" }}>Y: {y}</span>
      </div>
      <div>
        <button onClick={pause}>Pause</button>
        <button onClick={resume}>Resume</button>
      </div>
    </>
  );
};

render(<Demo />);

```

---

## useEventSource

URL: https://reactuse.com/browser/useeventsource/
Category: browser
Description: useEventSource is a React hook for Server-Sent Events (SSE) via the EventSource API — subscribe to a real-time server stream with status, data, and controls.
Import: `import { useEventSource } from '@reactuses/core'`

# useEventSource

`useEventSource` is a hook that allows you to subscribe to an EventSource and receive updates in real-time.

`useEventSource` wraps the [EventSource API](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) (Server-Sent Events) to establish a one-way connection from a server to the browser. It returns an object with `status` (connection state), `data` (the latest message), `error`, `close` (to disconnect), and `open` (to reconnect). You can listen to named events and control whether the connection opens immediately or is deferred.

### When to Use

- Receiving real-time server updates such as live feeds, notifications, or progress events
- Building dashboards that display streaming data from a server endpoint
- Implementing server-push features where the client only needs to receive (not send) data

### Notes

- **SSR-safe**: Returns a default state with no active connection during server-side rendering. No `EventSource` constructor is called on the server.
- **Reconnection**: The browser's native `EventSource` automatically reconnects on connection loss. Use the `status` field to track the current connection state.
- **Related hooks**: See also `useFetchEventSource` for SSE connections that need custom HTTP methods (e.g., POST) or headers.

## Usage

```tsx live
function Demo() {
  const { status, data, error, close, open } = useEventSource(
    "https://sse.dev/test",
    [],
    {
      immediate: false,
    }
  );

  return (
    <div>
      <div>Status: {status}</div>
      <div>Data: {JSON.stringify(data)}</div>
      <div>Error: {error}</div>
      <button onClick={open}>open</button>
      <button onClick={close}>Close</button>
    </div>
  );
};

```

---

## useEyeDropper

URL: https://reactuse.com/browser/useeyedropper/
Category: browser
Description: useEyeDropper is a React hook for the EyeDropper API — let users sample any pixel color on screen, with a support flag and an open function.
Import: `import { useEyeDropper } from '@reactuses/core'`

# useEyeDropper

Use [EyeDropper API](https://developer.mozilla.org/en-US/docs/Web/API/EyeDropper_API) to pick color

`useEyeDropper` provides access to the [EyeDropper API](https://developer.mozilla.org/en-US/docs/Web/API/EyeDropper_API), which lets users sample colors from any pixel on their screen. It returns a tuple of a boolean indicating browser support and an `open` function that launches the native color picker. The `open` function returns a promise resolving to an object with the selected color in `sRGBHex` format.

### When to Use

- Building color picker tools that let users sample colors from anywhere on screen
- Creating design or theming tools where users need to match existing colors
- Implementing accessibility contrast checkers that sample page colors

### Notes

- **SSR-safe**: Returns `false` for support and a no-op function during server-side rendering. No `window` or `EyeDropper` access occurs on the server.
- **Browser support**: The EyeDropper API is currently only supported in Chromium-based browsers. Always check the first tuple element (`isSupported`) before offering the feature.
- **User activation**: The `open` function requires a user gesture (e.g., button click) to launch the picker. You can pass an `AbortSignal` to cancel the operation.

## Usage

```tsx live
function Demo() {
  const [color, setColor] = useState("");
  const [supported, open] = useEyeDropper();

  if (supported) {
    return (
      <div style={{ padding: 40 }}>
        Supported: {supported.toString()}
        <br />
        Color: {color}
        <button
          type="button"
          onClick={async () => setColor((await open()).sRGBHex)}
        >
          Pick color
        </button>
      </div>
    );
  }

  return <span>Not Supported by Your Browser</span>;
};

```

---

## useFavicon

URL: https://reactuse.com/browser/usefavicon/
Category: browser
Description: useFavicon is a React hook to dynamically set the page favicon by updating the document's link rel=icon element — reflect app state in the browser tab.
Import: `import { useFavicon } from '@reactuses/core'`

# useFavicon

React side-effect hook sets the favicon of the page

`useFavicon` dynamically updates the page's favicon by manipulating the `<link rel="icon">` element in the document head. Pass an icon URL (and optionally a base URL and `rel` attribute) and the hook will create or update the appropriate link element. This is useful for reflecting application state visually in the browser tab.

### When to Use

- Changing the favicon to indicate unread notifications or status changes
- Switching favicons based on the current theme or branding context
- Displaying user-uploaded or dynamically generated icons in the browser tab

### Notes

- **SSR-safe**: The hook is a no-op during server-side rendering. No `document` access occurs on the server.
- **DOM manipulation**: The hook directly modifies the `<link>` element in `document.head`. Changes are reflected immediately in the browser tab.
- **Related hooks**: See also `useTitle` for dynamically setting the document title.

## Usage

```tsx live
function Demo() {
  const logo = 'https://react.dev/favicon.ico';
  const twitter = 'https://twitter.com/favicon.ico';
  const [icon, setIcon] = useState(twitter);
  useFavicon(icon);
  return (
    <div>
      <p>Change Favicon to</p>
      <button
        onClick={() => {
          setIcon(logo);
        }}
      >
        React
      </button>
      <button
        onClick={() => {
          setIcon(twitter);
        }}
      >
        Twitter
      </button>
    </div>
  );
};

```

---

## useFetchEventSource

URL: https://reactuse.com/browser/usefetcheventsource/
Category: browser
Description: useFetchEventSource is a React hook for Server-Sent Events (SSE) over fetch — subscribe to a stream with POST, custom headers, and request bodies.
Import: `import { useFetchEventSource } from '@reactuses/core'`

# useFetchEventSource

`useFetchEventSource` is a hook that allows you to subscribe to an EventSource using HTTP methods like POST and receive updates in real-time.

`useFetchEventSource` extends the standard Server-Sent Events pattern by using the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) instead of the native `EventSource` constructor. This enables custom HTTP methods (POST, PUT), request headers, and request bodies -- features not available with the standard `EventSource` API. It returns status, data, error, and control functions just like `useEventSource`, but with the flexibility of `fetch`.

### When to Use

- Streaming responses from AI/LLM APIs that require POST requests with JSON payloads
- Connecting to SSE endpoints that require authentication headers or custom content types
- Building chat interfaces, code generation UIs, or any feature that consumes server-sent events via non-GET requests

### Notes

- **SSR-safe**: Returns a default state with no active connection during server-side rendering. No fetch calls occur on the server.
- **Custom requests**: Unlike `useEventSource`, you can specify any HTTP method, headers, and body. This is essential for endpoints that accept POST requests (e.g., OpenAI streaming API).
- **Related hooks**: See also `useEventSource` for standard GET-based SSE connections that don't need custom request configuration.

:::note
This example don't work in the live editor because it requires a server to send events. You can try it in your local environment.
:::

Example Server Code:

<details>
<summary>SSE Server Implementation</summary>

```javascript
const express = require('express');
const cors = require('cors');
const bodyParser = require('body-parser');

const app = express();
const PORT = 3001;

// Store all active SSE connections
const clients = new Map();
let messageCount = 0;

app.use(cors({
  origin: 'http://localhost:3000',
  methods: ['GET', 'POST', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Cache-Control', 'Connection', 'Accept', 'Authorization'],
  exposedHeaders: ['Content-Type'],
  credentials: true,
  maxAge: 86400
}));

app.options('*', cors());

// POST /events using raw request handling
app.post('/events', async (req, res) => {
  // 1. Immediately set necessary headers
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');
  res.setHeader('X-Accel-Buffering', 'no');
  res.setHeader('Access-Control-Allow-Origin', 'http://localhost:3000');
  res.setHeader('Access-Control-Allow-Credentials', 'true');

  // 2. Read and parse request body
  let body = '';
  for await (const chunk of req) {
    body += chunk;
  }

  // 3. Parse configuration
  let config;
  try {
    config = body ? JSON.parse(body) : {};
  } catch (e) {
    config = {};
  }

  const channel = config.channel || 'default';
  const interval = parseInt(config.interval) || 3000;

  // 4. Disable request timeout
  req.socket.setTimeout(0);
  req.socket.setNoDelay(true);
  req.socket.setKeepAlive(true);

  // 5. Start sending data
  console.log(`New client connected to channel: ${channel}`);

  // 6. Add connection to the client collection of corresponding channel
  if (!clients.has(channel)) {
    clients.set(channel, new Set());
  }
  clients.get(channel).add(res);

  const totalClients = Array.from(clients.values())
    .reduce((sum, set) => sum + set.size, 0);
  console.log(`Client connected to channel ${channel}. Total clients: ${totalClients}`);

  // 7. Send connection success message
  const sendEvent = (data, eventType = null) => {
    if (eventType) {
      res.write(`event: ${eventType}\n`);
    }
    res.write(`id: ${Date.now()}\n`);
    res.write(`data: ${JSON.stringify(data)}\n\n`);
  };

  // 8. Send initial message
  try {
    sendEvent({
      message: 'Connected to SSE stream',
      channel: channel,
      time: new Date().toISOString()
    }, 'connected');

    // 9. Set up periodic message sending
    let messageCounter = 0;
    const intervalId = setInterval(() => {
      messageCounter++;
      messageCount++;

      try {
        sendEvent({
          id: messageCount,
          count: messageCounter,
          channel: channel,
          time: new Date().toISOString(),
          message: `Channel ${channel} message ${messageCounter}`
        });
      } catch (error) {
        console.error(`Error sending message to channel ${channel}:`, error);
        cleanup();
      }
    }, interval);

    // 10. Set up heartbeat
    const heartbeatId = setInterval(() => {
      try {
        res.write(':\n\n');
      } catch (error) {
        console.error(`Heartbeat error on channel ${channel}:`, error);
        cleanup();
      }
    }, 15000);

    // 11. Cleanup function
    const cleanup = () => {
      clearInterval(intervalId);
      clearInterval(heartbeatId);

      const channelClients = clients.get(channel);
      if (channelClients) {
        channelClients.delete(res);
        if (channelClients.size === 0) {
          clients.delete(channel);
        }
      }

      const remainingClients = Array.from(clients.values())
        .reduce((sum, set) => sum + set.size, 0);
      console.log(`Client disconnected from channel ${channel}. Total clients: ${remainingClients}`);

      try {
        res.end();
      } catch (error) {
        console.error('Error ending response:', error);
      }
    };

    // 12. Set up connection close handling
    req.on('close', cleanup);
    req.on('end', cleanup);
    res.on('close', cleanup);
    res.on('error', cleanup);

  } catch (error) {
    console.error(`Error in SSE connection for channel ${channel}:`, error);
    res.end();
  }
});

// GET SSE endpoint handler
function handleGETConnection(req, res, channel = 'default', interval = 3000) {
  // Set SSE headers
  res.writeHead(200, {
    'Content-Type': 'text/event-stream',
    'Cache-Control': 'no-cache',
    'Connection': 'keep-alive',
    'X-Accel-Buffering': 'no',
    'Access-Control-Allow-Origin': 'http://localhost:3000',
    'Access-Control-Allow-Credentials': 'true'
  });

  console.log(`New client connected to channel: ${channel}`);

  // Send connection success message
  const sendEvent = (data, eventType = null) => {
    if (eventType) {
      res.write(`event: ${eventType}\n`);
    }
    res.write(`id: ${Date.now()}\n`);
    res.write(`data: ${JSON.stringify(data)}\n\n`);
  };

  // Send initial connection message
  sendEvent({
    message: 'Connected to SSE stream',
    channel: channel,
    time: new Date().toISOString()
  }, 'connected');

  // Add connection to the client collection of corresponding channel
  if (!clients.has(channel)) {
    clients.set(channel, new Set());
  }
  clients.get(channel).add(res);

  const totalClients = Array.from(clients.values())
    .reduce((sum, set) => sum + set.size, 0);
  console.log(`Client connected to channel ${channel}. Total clients: ${totalClients}`);

  // Send periodic messages
  let messageCounter = 0;
  const intervalId = setInterval(() => {
    messageCounter++;
    messageCount++;
    sendEvent({
      id: messageCount,
      count: messageCounter,
      channel: channel,
      time: new Date().toISOString(),
      message: `Channel ${channel} message ${messageCounter}`
    });
  }, interval);

  // Heartbeat check
  const heartbeatId = setInterval(() => {
    res.write(':\n\n');
  }, 15000);

  // Cleanup function
  const cleanup = () => {
    clearInterval(intervalId);
    clearInterval(heartbeatId);
    const channelClients = clients.get(channel);
    if (channelClients) {
      channelClients.delete(res);
      if (channelClients.size === 0) {
        clients.delete(channel);
      }
    }
    const remainingClients = Array.from(clients.values())
      .reduce((sum, set) => sum + set.size, 0);
    console.log(`Client disconnected from channel ${channel}. Total clients: ${remainingClients}`);
    try {
      res.end();
    } catch (error) {
      console.error('Error ending response:', error);
    }
  };

  // Monitor connection closure
  req.on('close', cleanup);
  res.on('close', cleanup);
  res.on('error', cleanup);
}

// GET SSE endpoint
app.get('/events', (req, res) => {
  const channel = req.query.channel || 'default';
  const interval = parseInt(req.query.interval) || 3000;
  handleGETConnection(req, res, channel, interval);
});

// Broadcast message endpoint
app.post('/broadcast', bodyParser.json(), (req, res) => {
  const { message, channel, eventType = 'broadcast' } = req.body;

  let targetClients = new Set();
  if (channel) {
    targetClients = clients.get(channel) || new Set();
    console.log(`Broadcasting message to channel ${channel} (${targetClients.size} clients):`, message);
  } else {
    targetClients = new Set(
      Array.from(clients.values())
        .flatMap(channelClients => Array.from(channelClients))
    );
    console.log(`Broadcasting message to all channels (${targetClients.size} clients):`, message);
  }

  let successCount = 0;
  for (const client of targetClients) {
    try {
      client.write(`event: ${eventType}\n`);
      client.write(`id: ${Date.now()}\n`);
      client.write(`data: ${JSON.stringify({
        message,
        channel: channel || 'all',
        time: new Date().toISOString()
      })}\n\n`);
      successCount++;
    } catch (error) {
      console.error('Error broadcasting to client:', error);
    }
  }

  res.json({
    success: true,
    clientCount: targetClients.size,
    successfulBroadcasts: successCount,
    channel: channel || 'all',
    message: 'Broadcast sent successfully'
  });
});

// Status endpoint
app.get('/status', (req, res) => {
  const channelStats = {};
  clients.forEach((clientSet, channel) => {
    channelStats[channel] = clientSet.size;
  });

  res.json({
    activeConnections: Array.from(clients.values())
      .reduce((sum, set) => sum + set.size, 0),
    channelStats,
    messageCount,
    uptime: process.uptime()
  });
});

// Error handling middleware
app.use((err, req, res, next) => {
  console.error('Server error:', err);
  res.status(500).json({
    error: 'Internal Server Error',
    message: err.message
  });
});

// Start server
app.listen(PORT, () => {
  console.log(`SSE Server running at http://localhost:${PORT}`);
  console.log('Available endpoints:');
  console.log(`- GET  /events?channel={channel}&interval={interval} - SSE stream`);
  console.log(`- POST /events - SSE stream with body params`);
  console.log(`- POST /broadcast - Broadcast message to all clients or specific channel`);
  console.log(`- GET  /status - Server status`);
});
```

</details>

## Examples

### Basic Usage

```tsx live
function Demo() {
  const { data, status } = useFetchEventSource("https://broad-scene-1112.ploomberapp.io/stream", {
    openWhenHidden: false
  });

  return (
    <div>
      <div>Status: {status}</div>
      <div>Data: {JSON.stringify(data)}</div>
    </div>
  );
};
```

### With POST Request

```tsx live
function Demo() {
  const { status, data, error, close, open } = useFetchEventSource(
    "http://localhost:3001/events",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Accept: "text/event-stream",
        "Cache-Control": "no-cache",
        Connection: "keep-alive",
      },
      immediate: false, // Don't connect immediately
      body: JSON.stringify({
        channel: "custom-channel",
        interval: 2000
      }),
    }
  );

  return (
    <div>
      <div>Status: {status}</div>
      <div>Data: {JSON.stringify(data)}</div>
      <div>Error: {error?.message}</div>
      <button onClick={open}>Open</button>
      <button onClick={close}>Close</button>
    </div>
  );
};

```

### With Event Handlers

```tsx live
function Demo() {
  const { data, status } = useFetchEventSource("http://localhost:3001/events", {
    onOpen: () => {
      console.log("Connection established");
    },
    onMessage: (event) => {
      console.log("New message:", event.data);
    },
    onError: (error) => {
      console.error("Connection error:", error);
      return 5000; // Retry after 5 seconds
    },
    onClose: () => {
      console.log("Connection closed");
    }
  });

  return (
    <div>
      <div>Status: {status}</div>
      <div>Latest message: {JSON.stringify(data)}</div>
    </div>
  );
};

```

### With Auto Reconnect

```tsx live
function Demo() {
  const { status, data } = useFetchEventSource("http://localhost:3001/events", {
    autoReconnect: {
      retries: 3,     // Maximum retry attempts
      delay: 1000,    // Delay between retries (ms)
      onFailed: () => {
        console.log("Failed to reconnect after 3 attempts");
      }
    }
  });

  return (
    <div>
      <div>Connection status: {status}</div>
      <div>Data: {JSON.stringify(data)}</div>
    </div>
  );
};

```

### Multi Channel Example

```tsx live
function Demo() {
  const [channel, setChannel] = useState('default');

  const { data, close, open } = useFetchEventSource(
    "http://localhost:3001/events",
    {
      method: "POST",
      immediate: false,
      body: JSON.stringify({ channel }),
      onMessage: (event) => {
        console.log(`Message from ${channel}:`, event);
      }
    }
  );

  const switchChannel = (newChannel) => {
    close();
    setChannel(newChannel);
    open();
  };

  return (
    <div>
      <select
        value={channel}
        onChange={(e) => switchChannel(e.target.value)}
      >
        <option value="default">Default Channel</option>
        <option value="news">News Channel</option>
        <option value="alerts">Alerts Channel</option>
      </select>
      <div>Current Channel: {channel}</div>
      <div>Latest Message: {data?.message}</div>
    </div>
  );
};

```

---

## useFileDialog

URL: https://reactuse.com/browser/usefiledialog/
Category: browser
Description: useFileDialog is a React hook to open the browser's native file picker programmatically, with no hidden input element — returns selected files, open, and reset.
Import: `import { useFileDialog } from '@reactuses/core'`

# useFileDialog

Open file dialog with ease

`useFileDialog` provides a programmatic way to open the browser's native file picker without needing a visible `<input type="file">` element. It returns a tuple of the selected `FileList` (or `null`), an `open` function to trigger the dialog, and a `reset` function to clear the selection. You can configure accepted file types, multiple selection, and device capture (camera/microphone).

### When to Use

- Building custom-styled file upload buttons that don't rely on the default `<input>` appearance
- Implementing drag-and-drop upload areas with an optional "browse files" fallback
- Triggering file selection from any interactive element (e.g., a card, icon, or context menu item)

### Notes

- **SSR-safe**: Returns `null` for the file list and no-op functions during server-side rendering. No DOM access occurs on the server.
- **File filtering**: Use the `accept` option to restrict selectable file types (e.g., `"image/*"`, `".pdf,.doc"`), following the [HTML `accept` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#accept) syntax.
- **Capture**: Use the `capture` option to request files directly from the device camera or microphone on mobile devices.

## Usage

```tsx live
function Demo() {
  const [files, open, reset] = useFileDialog();

  return (
    <div>
      <button onClick={() => open()}> Choose files</button>
      <button
        style={{ marginLeft: 20 }}
        disabled={!files}
        onClick={() => {
          reset();
        }}
      >
        Reset
      </button>
      {files && (
        <div>
          <p>
            You have selected: <b>{files.length} files</b>
            {Array.from(files).map((file) => {
              return <li key={file.name}>{file.name}</li>;
            })}
          </p>
        </div>
      )}
    </div>
  );
};

```

---

## useFps

URL: https://reactuse.com/browser/usefps/
Category: browser
Description: useFps is a React hook that measures the current frames per second by counting requestAnimationFrame callbacks — useful for performance monitoring.
Import: `import { useFps } from '@reactuses/core'`

# useFps

React Sensor Hooks that tracks FPS (frames per second)

`useFps` measures the current frames per second by counting [`requestAnimationFrame`](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestAnimationFrame) callbacks. It returns a number representing the current FPS, calculated over a configurable number of frames (default: every 10 frames). This is useful for performance monitoring and adaptive rendering.

### When to Use

- Displaying a real-time FPS counter in development or debugging overlays
- Adaptively reducing animation complexity when frame rate drops below a threshold
- Benchmarking rendering performance of components or pages

### Notes

- **SSR-safe**: Returns `0` during server-side rendering. No `requestAnimationFrame` calls occur on the server.
- **Performance**: The hook uses `requestAnimationFrame` internally, so it has minimal overhead. Adjust the `every` option to balance accuracy and update frequency.
- **Related hooks**: See also `useIdle` for detecting user inactivity, which can complement FPS-based adaptive rendering.

## Usage

```tsx live
function Demo() {
  const fps = useFps();

  return <div>FPS: {fps}</div>;
};

```

---

## useFullscreen

URL: https://reactuse.com/browser/usefullscreen/
Category: browser
Description: useFullscreen is a React hook for the Fullscreen API — enter, exit, and toggle fullscreen for any element, with state and a browser support flag.
Import: `import { useFullscreen } from '@reactuses/core'`

# useFullscreen

Display an element full-screen

`useFullscreen` wraps the [Fullscreen API](https://developer.mozilla.org/en-US/docs/Web/API/Fullscreen_API) to manage entering and exiting fullscreen mode for a given DOM element. It returns a tuple of the current fullscreen state (boolean) and an actions object with `enterFullscreen`, `exitFullscreen`, `toggleFullscreen`, and an `isEnabled` flag indicating browser support. Callbacks for enter/exit events are available via options.

### When to Use

- Building video players, image galleries, or presentation modes that benefit from fullscreen display
- Creating immersive reading or gaming experiences that use the entire screen
- Adding a fullscreen toggle to data dashboards or visualization tools

### Notes

- **SSR-safe**: Returns `false` for fullscreen state and `isEnabled` during server-side rendering. No `document` access occurs on the server.
- **Browser support**: The Fullscreen API is supported in all modern browsers. Check `isEnabled` to confirm support before showing fullscreen controls.
- **User gesture**: Browsers require a user-initiated event (e.g., a click) to enter fullscreen. Programmatic calls without user interaction will be rejected.

## Usage

```tsx live
function Demo() {
  const ref = useRef(null);
  const [isFullscreen, { enterFullscreen, exitFullscreen, toggleFullscreen }]
    = useFullscreen(ref);
  return (
    <div ref={ref}>
      <div style={{ marginBottom: 16 }}>
        {isFullscreen ? "Fullscreen" : "Not fullscreen"}
      </div>
      <div>
        <button type="button" onClick={enterFullscreen}>
          enterFullscreen
        </button>
        <button
          type="button"
          onClick={exitFullscreen}
          style={{ margin: "0 8px" }}
        >
          exitFullscreen
        </button>
        <button type="button" onClick={toggleFullscreen}>
          toggleFullscreen
        </button>
      </div>
    </div>
  );
};

```

---

## useGeolocation

URL: https://reactuse.com/browser/usegeolocation/
Category: browser
Description: useGeolocation is a React hook for the Geolocation API — reactively track the user's position with coordinates, a timestamp, error state, and SSR-safe defaults.
Import: `import { useGeolocation } from '@reactuses/core'`

# useGeolocation

React Sensor Hooks that tracks [Geolocation](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API)

It allows the user to provide their location to web applications if they so desire. For privacy reasons, the user is asked for permission to report location information

`useGeolocation` wraps the [Geolocation API](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API) to reactively track the user's geographic position. It returns an object with `coordinates` (latitude, longitude, altitude, accuracy, etc.), a `locatedAt` timestamp, an `error` object, and an `isSupported` flag. The hook watches for position changes and updates automatically. Standard `PositionOptions` (like `enableHighAccuracy` and `timeout`) can be passed as options.

### When to Use

- Displaying the user's current location on a map or providing location-aware search results
- Building geofencing features that trigger actions when users enter or leave a geographic area
- Calculating distances or directions based on the user's real-time position

### Notes

- **SSR-safe**: Returns default coordinates and `null` values during server-side rendering. No `navigator.geolocation` access occurs on the server.
- **Permissions**: The browser prompts the user for location permission. The `error` property captures any denial or timeout. Use alongside `usePermission` with `"geolocation"` to check permission status proactively.
- **Privacy**: Location data is sensitive. Only request geolocation when genuinely needed and inform users why their location is being accessed.

## Usage

```tsx live
function Demo() {
  const { coordinates, locatedAt, error } = useGeolocation();

  return (
    <div>
      <pre lang="json">
        {JSON.stringify(
          {
            coordinates: {
              accuracy: coordinates.accuracy,
              latitude: coordinates.latitude,
              longitude: coordinates.longitude,
              altitude: coordinates.altitude,
              altitudeAccuracy: coordinates.altitudeAccuracy,
              heading: coordinates.heading,
              speed: coordinates.speed,
            },
            locatedAt,
            error: error ? error.message : error,
          },
          null,
          2,
        )}
      </pre>
    </div>
  );
};

```

---

## useIdle

URL: https://reactuse.com/browser/useidle/
Category: browser
Description: useIdle is a React hook that detects user inactivity via mouse, keyboard, touch, and scroll events, returning a boolean once the user is idle past a timeout.
Import: `import { useIdle } from '@reactuses/core'`

# useIdle

React sensor hook that tracks if user on the page is idle

`useIdle` detects user inactivity by listening to DOM events such as `mousemove`, `mousedown`, `keydown`, `touchstart`, `resize`, and `wheel`. It returns a boolean indicating whether the user has been idle for longer than a specified duration (default: 60 seconds). You can customize the timeout, initial state, and which events reset the idle timer.

### When to Use

- Auto-saving drafts or pausing expensive operations when the user steps away
- Showing "Are you still there?" prompts for security-sensitive applications
- Dimming the UI or pausing media playback after a period of inactivity

### Notes

- **SSR-safe**: Returns the `initialState` value (default: `false`) during server-side rendering. No event listeners are attached on the server.
- **Configurable events**: By default, the hook listens to mouse, keyboard, touch, resize, and wheel events on `window`. You can override the event list via the `events` parameter.
- **Related hooks**: See also `usePageLeave` for detecting when the cursor leaves the page viewport.

## Usage

```tsx live
function Demo() {
  const isIdle = useIdle(3e3);

  return (
    <div>
      <div>User is idle: {isIdle ? "Yes 😴" : "Nope"}</div>
    </div>
  );
};

```

---

## useInfiniteScroll

URL: https://reactuse.com/browser/useinfinitescroll/
Category: browser
Description: useInfiniteScroll is a React hook for infinite scrolling — triggers a load-more callback when the user scrolls near a container edge, with throttling.
Import: `import { useInfiniteScroll } from '@reactuses/core'`

# useInfiniteScroll

Infinite scrolling of the element

`useInfiniteScroll` builds on `useScroll` to automatically trigger a callback when the user scrolls near the edge of a scrollable container. Pass a target element ref, a load-more function, and optional configuration (scroll direction, distance threshold, throttle). The load-more callback receives the current scroll state so you can decide whether to fetch more data. The hook also supports preserving scroll position when prepending content.

### When to Use

- Building feeds, timelines, or product listings that load more items as the user scrolls
- Implementing chat interfaces that load older messages when scrolling to the top
- Creating horizontally scrolling galleries that fetch additional content on demand

### Notes

- **SSR-safe**: The hook is a no-op during server-side rendering. No scroll listeners are attached on the server.
- **Direction**: By default, triggers at the `bottom` edge. Use the `direction` option to trigger on `top`, `left`, or `right` edges for reverse or horizontal scrolling.
- **Related hooks**: Built on top of `useScroll`, which provides the underlying scroll position, direction, and arrived-state tracking.

## Usage

```tsx live
function Demo() {
  const ref = useRef<HTMLDivElement>(null);
  const [data, setData] = useState([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);

  useInfiniteScroll(
    ref,
    () => {
      const length = data.length + 1;
      const newData = data.slice();
      if (newData.length === 400) {
        return;
      }
      newData.push(...Array.from({ length: 5 }, (_, i) => length + i));
      setData(newData);
    },
    { distance: 10 },
  );

  return (
    <div>
      <div ref={ref} style={{ width: 300, height: 300, overflow: "scroll" }}>
        {data.map(item => (
          <div key={item} style={{ padding: 12, border: "1px solid" }}>
            item-{item}
          </div>
        ))}
      </div>
    </div>
  );
};

```

---

## useKeyModifier

URL: https://reactuse.com/browser/usekeymodifier/
Category: browser
Description: useKeyModifier is a React hook that reactively tracks whether a modifier key (Shift, Control, Alt, Meta, CapsLock) is currently pressed.
Import: `import { useKeyModifier } from '@reactuses/core'`

# useKeyModifier

React Sensor Hook that tracks state of any of the [supported modifiers](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/getModifierState#browser_compatibility) - see Browser Compatibility notes

`useKeyModifier` uses [`KeyboardEvent.getModifierState()`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/getModifierState) to reactively track whether a specific modifier key (Shift, Control, Alt, CapsLock, Meta, etc.) is currently pressed. It returns a boolean that updates on `keydown`, `keyup`, `mousedown`, and `mouseup` events. You can customize which events trigger updates and set an initial value.

### When to Use

- Building keyboard shortcut indicators that visually highlight when modifier keys are held
- Showing different tooltips or cursor styles based on active modifier keys
- Implementing modifier-aware interactions (e.g., Ctrl+Click for multi-select)

### Notes

- **SSR-safe**: Returns the `initial` value (default: `false`) during server-side rendering. No event listeners are attached on the server.
- **Supported modifiers**: Supports `Alt`, `AltGraph`, `CapsLock`, `Control`, `Fn`, `FnLock`, `Meta`, `NumLock`, `ScrollLock`, `Shift`, `Symbol`, and `SymbolLock`. Not all modifiers are available in all browsers -- see [MDN compatibility](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/getModifierState#browser_compatibility).
- **Event customization**: The default events (`mousedown`, `mouseup`, `keydown`, `keyup`) can be overridden via the `events` option.

## Usage

```tsx live
function Demo() {
  const Button = (props: { mode: boolean; name: string }) => {
    const { mode, name } = props;
    return (
      <button style={mode ? { background: "var(--c-input-border-focus)" } : {}}>
        {name}
      </button>
    );
  };

  const capsLock = useKeyModifier("CapsLock");
  const numLock = useKeyModifier("NumLock");
  const scrollLock = useKeyModifier("ScrollLock");
  const shift = useKeyModifier("Shift");
  const control = useKeyModifier("Control");
  const alt = useKeyModifier("Alt");

  return (
    <div>
      <div style={{ marginBottom: 10 }}>
        <Button mode={capsLock} name="CapsLock" />
        <Button mode={numLock} name="NumLock" />
        <Button mode={scrollLock} name="ScrollLock" />
      </div>
      <div>
        <Button mode={shift} name="Shift" />
        <Button mode={control} name="Control" />
        <Button mode={alt} name="Alt" />
      </div>
    </div>
  );
};

```

---

## useLocationSelector

URL: https://reactuse.com/browser/uselocationselector/
Category: browser
Description: useLocationSelector is a React hook to subscribe to window.location changes and select only the part you need — re-renders only when that value changes.
Import: `import { useLocationSelector } from '@reactuses/core'`

# useLocationSelector

Selectively retrieve properties from location. This hook will only re-render when the value you return is changed.
For more information, [see](https://thisweekinreact.com/articles/useSyncExternalStore-the-underrated-react-api)

`useLocationSelector` uses [`useSyncExternalStore`](https://react.dev/reference/react/useSyncExternalStore) to subscribe to `window.location` changes and lets you extract only the part of the location you care about via a selector function. The component re-renders only when the selected value actually changes, preventing unnecessary updates when other location properties change (e.g., hash changes won't re-render a component that only selects `pathname`).

### When to Use

- Reading the current pathname, hash, or search params without importing a full routing library
- Optimizing performance by subscribing to only the specific location property your component needs
- Building lightweight navigation-aware components that respond to URL changes

### Notes

- **SSR-safe**: Accepts a `fallback` parameter that is returned during server-side rendering when `window.location` is not available.
- **Selective re-renders**: Unlike reading `window.location` directly, the selector pattern ensures your component only re-renders when the derived value changes.
- **Browser events**: Listens to `popstate` events on `window` to detect back/forward navigation. Hash changes and `pushState`/`replaceState` calls are also tracked.

## Usage

```tsx live noInline
function CurrentPathname() {
  const pathname = useLocationSelector(location => location.pathname);
  const ref = useRef(0);

  useEffect(() => {
    ref.current = ref.current + 1;
  });
  return (
    <div>
      {pathname}
      <div>renderCount: {ref.current}</div>
    </div>
  );
}

function CurrentHash() {
  const hash = useLocationSelector(location => location.hash || "nohash");
  const ref = useRef(0);

  useEffect(() => {
    ref.current = ref.current + 1;
  });
  return (
    <div>
      {hash}
      <div>hashRender: {ref.current}</div>
    </div>
  );
};

function Links() {
  return (
    <div>
      <a href="#link1">#link1</a>
      <a href="#link2">#link2</a>
      <a href="#link3">#link3</a>
    </div>
  );
};

function Demo() {
  return (
    <div>
      <CurrentPathname />
      <CurrentHash />
      <Links />
    </div>
  );
};

render(<Demo/>);

```

---

## useLongPress

URL: https://reactuse.com/browser/uselongpress/
Category: browser
Description: useLongPress is a React hook that detects long-press gestures on any element across mouse and touch, firing a callback after a configurable hold delay.
Import: `import { useLongPress } from '@reactuses/core'`

# useLongPress

React sensor hook that fires a callback after long pressing

`useLongPress` detects long-press gestures on any element by tracking `mousedown`/`mouseup` and `touchstart`/`touchend` events. It returns an object of event handlers that you spread onto the target element. When the user presses and holds for the configured delay (default: 300ms), the callback fires. The hook supports both mouse and touch interactions and can optionally prevent default browser behavior.

### When to Use

- Adding context-menu-like actions triggered by long press on mobile and desktop
- Implementing "press and hold to delete" or "press and hold to confirm" interactions
- Building touch-friendly interfaces with long-press gestures for secondary actions

### Notes

- **SSR-safe**: Returns no-op event handlers during server-side rendering. No `window` or `document` access occurs on the server.
- **Touch and mouse**: Handles both pointer types. The `isPreventDefault` option (default: `true`) prevents text selection and context menus during the press.
- **Customizable delay**: Set the `delay` option in milliseconds to control how long the user must press before the callback fires.

## Usage

```tsx live
function Demo() {
  const [state, setState] = useState("No Press");
  const onLongPress = () => {
    setState("Long Pressed!");
  };

  const defaultOptions = {
    isPreventDefault: true,
    delay: 300,
  };
  const longPressEvent = useLongPress(onLongPress, defaultOptions);

  return (
    <div>
      <button {...longPressEvent}>useLongPress</button>
      <button onClick={() => setState("No Press")}>Reset</button>
      <div>Pressed: {state}</div>
    </div>
  );
};

```

---

## useMediaDevices

URL: https://reactuse.com/browser/usemediadevices/
Category: browser
Description: useMediaDevices is a React hook for the MediaDevices API — enumerate connected cameras, microphones, and speakers, with permission requests.
Import: `import { useMediaDevices } from '@reactuses/core'`

# useMediaDevices

React sensor hook that tracks connected hardware devices

`useMediaDevices` wraps the [MediaDevices API](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices) to enumerate available media input/output devices (cameras, microphones, speakers). It returns a tuple of the device list and a function to request permissions. Each device entry includes `deviceId`, `groupId`, `kind` (audioinput, audiooutput, videoinput), and `label`. The hook can automatically request permissions on mount or let you trigger them manually.

### When to Use

- Building video/audio conferencing apps that let users choose their preferred camera or microphone
- Displaying a list of available input/output devices for media settings
- Detecting when new media devices are connected or disconnected

### Notes

- **SSR-safe**: Returns an empty device list and a no-op permission function during server-side rendering. No `navigator.mediaDevices` access occurs on the server.
- **Permissions**: Device labels and IDs may be empty until the user grants media permissions. Set `requestPermissions: true` to automatically prompt, or call the returned permission function manually.
- **Related hooks**: Use alongside `usePermission` with `"camera"` or `"microphone"` to check permission status without triggering a prompt.

## Usage

```tsx live
function Demo() {
  const [state] = useMediaDevices({
    requestPermissions: true,
  });

  return <pre>{JSON.stringify(state, null, 2)}</pre>;
};

```

---

## useMediaQuery

URL: https://reactuse.com/browser/usemediaquery/
Category: browser
Description: useMediaQuery is a React hook that reactively evaluates a CSS media query via matchMedia, returning a boolean that updates when the match state changes.
Import: `import { useMediaQuery } from '@reactuses/core'`

# useMediaQuery

Ease with media query

`useMediaQuery` wraps [`window.matchMedia()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia) to reactively evaluate a CSS media query string. It returns a boolean indicating whether the document currently matches the query. The value updates automatically whenever the match state changes (e.g., when the window is resized or the system color scheme changes).

### When to Use

- Rendering different layouts or components based on screen width breakpoints
- Detecting system preferences like dark mode, reduced motion, or high contrast
- Conditionally loading heavy components or assets only on large screens

### Notes

- **SSR-safe**: Accepts a `defaultState` parameter (default: `false`) that is returned during server-side rendering when `window.matchMedia` is not available.
- **Any valid media query**: Works with any CSS media query string, including `prefers-color-scheme`, `prefers-reduced-motion`, `orientation`, and custom breakpoints.
- **Related hooks**: Several specialized hooks are built on `useMediaQuery`, including `usePreferredDark`, `usePreferredColorScheme`, `usePreferredContrast`, `useReducedMotion`, and `useMobileLandscape`.

## Usage

```tsx live
function Demo() {
  const isWide = useMediaQuery("(min-width: 480px)");

  return <div>Screen is wide: {isWide ? "Yes" : "No"}</div>;
};

```

---

## useMicrophone

URL: https://reactuse.com/browser/usemicrophone/
Category: browser
Description: useMicrophone is a React hook for the microphone — open a stream, read a real-time audio level, and record audio to a Blob with MediaRecorder.
Import: `import { useMicrophone } from '@reactuses/core'`

# useMicrophone

React hook for capturing microphone audio

`useMicrophone` wraps [`getUserMedia`](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia), the [Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API), and [`MediaRecorder`](https://developer.mozilla.org/en-US/docs/Web/API/MediaRecorder) into a single hook. It opens and closes the microphone stream, exposes a throttled audio `level` (0–1, RMS) suitable for a VU meter, and records the active stream to a `Blob` with a hook-managed object URL.

The live-stream controls (`start` / `stop`) and the recording controls (`startRecording` / `stopRecording` / `pauseRecording` / `resumeRecording`) are independent: you can show a level meter without recording, and start or stop a recording without dropping the microphone.

### When to Use

- Building voice-note or dictation UIs where the user sees a live input level before and while recording
- Adding "speak now" prompts or microphone calibration screens that need a VU meter but no capture
- Recording short audio clips to a `Blob` for upload or local playback

### Notes

- **SSR-safe**: Returns `isSupported: false` and no-op controls during server-side rendering. No `navigator.mediaDevices` access occurs on the server.
- **`start()` before `startRecording()`**: Recording captures an already-open stream. Call `start()` first; calling `startRecording()` without an active stream sets `error` instead of recording.
- **HTTPS required**: In production the microphone requires a secure context (HTTPS). The browser prompts for permission on the first `start()`.
- **Object URL lifecycle**: `audioUrl` is created and revoked by the hook — it is replaced on the next recording and revoked on unmount, so consumers do not need to call `URL.revokeObjectURL` themselves.
- **Mime type**: The recording format is auto-selected from the formats the browser supports (`audio/webm;codecs=opus`, `audio/webm`, `audio/mp4`, `audio/ogg;codecs=opus`). The resolved value is exposed as `mimeType`.
- **Related hooks**: Use `useMediaDevices` to enumerate microphones and pass a `deviceId`, or `useSpeechRecognition` for speech-to-text.

## Usage

```tsx live
function Demo() {
  const {
    isSupported,
    isActive,
    level,
    isRecording,
    isPaused,
    audioUrl,
    mimeType,
    error,
    start,
    stop,
    startRecording,
    stopRecording,
    pauseRecording,
    resumeRecording,
  } = useMicrophone();

  if (!isSupported) {
    return <div>Microphone is not supported in this browser</div>;
  }

  const levelPercent = Math.round(level * 100);

  return (
    <div>
      <div style={{ marginBottom: '16px' }}>
        <p>
          <strong>Microphone:</strong> {isActive ? 'Open' : 'Closed'}
          {' · '}
          <strong>Recording:</strong>{' '}
          {isRecording ? (isPaused ? 'Paused' : 'Recording...') : 'Idle'}
        </p>

        <div
          style={{
            height: '16px',
            width: '100%',
            borderRadius: '4px',
            backgroundColor: 'var(--ifm-color-emphasis-200)',
            overflow: 'hidden',
          }}
        >
          <div
            style={{
              height: '100%',
              width: `${levelPercent}%`,
              backgroundColor:
                levelPercent > 70
                  ? 'var(--ifm-color-danger)'
                  : 'var(--ifm-color-success)',
              transition: 'width 80ms linear',
            }}
          />
        </div>
        <p style={{ fontSize: '13px', color: 'var(--ifm-color-content-secondary)' }}>
          Input level: {levelPercent}%
        </p>
      </div>

      <div style={{ display: 'flex', gap: '8px', flexWrap: 'wrap', marginBottom: '12px' }}>
        <button onClick={() => start()} disabled={isActive}>
          Open mic
        </button>
        <button onClick={() => stop()} disabled={!isActive}>
          Close mic
        </button>
        <button onClick={() => startRecording()} disabled={!isActive || isRecording}>
          Record
        </button>
        <button onClick={() => stopRecording()} disabled={!isRecording}>
          Stop recording
        </button>
        <button onClick={() => pauseRecording()} disabled={!isRecording || isPaused}>
          Pause
        </button>
        <button onClick={() => resumeRecording()} disabled={!isPaused}>
          Resume
        </button>
      </div>

      {audioUrl && (
        <div style={{ marginBottom: '12px' }}>
          <p style={{ fontSize: '13px', color: 'var(--ifm-color-content-secondary)' }}>
            Recorded clip ({mimeType || 'default format'}):
          </p>
          <audio src={audioUrl} controls />
        </div>
      )}

      {error && (
        <p style={{ color: 'var(--ifm-color-danger)' }}>
          <strong>Error:</strong> {error.message}
        </p>
      )}
    </div>
  );
}
```

## Common Use Cases

- **Voice notes**: Open the mic so the user sees a live level, then record to a `Blob` and play it back or upload it.
- **Level metering**: Drive a VU meter or waveform from `level` without recording anything.
- **Microphone calibration**: Let users confirm the right device is picked up before they start.

---

## useMobileLandscape

URL: https://reactuse.com/browser/usemobilelandscape/
Category: browser
Description: useMobileLandscape is a React hook that returns true when the device is a mobile in landscape orientation, updating reactively on rotation.
Import: `import { useMobileLandscape } from '@reactuses/core'`

# useMobileLandscape

React hook that returns `true` if the mobile device is in landscape mode and `false` otherwise.

`useMobileLandscape` uses media queries internally to detect whether the current device is a mobile device in landscape orientation. It returns a single boolean value that updates reactively when the device is rotated. This is useful for adapting layouts or showing landscape-specific UI on phones and tablets.

### When to Use

- Showing or hiding landscape-specific UI elements (e.g., rotating a "turn your device" prompt)
- Adjusting layout or component sizing for mobile landscape orientation
- Triggering different behavior for games or media players when in landscape mode

### Notes

- **SSR-safe**: Returns `false` during server-side rendering. No `window.matchMedia` access occurs on the server.
- **Mobile-specific**: Detects landscape orientation specifically on mobile devices, not desktop. For general orientation tracking, see `useOrientation`.
- **Related hooks**: Built on `useMediaQuery`. See also `useOrientation` for more detailed orientation information including angle and lock capabilities.

## Usage

```tsx live
function Demo() {
  const isMobileLandscape = useMobileLandscape();
  return <p>isMobileLandscape: {JSON.stringify(isMobileLandscape)}</p>;
};

```

---

## useMouse

URL: https://reactuse.com/browser/usemouse/
Category: browser
Description: useMouse is a React hook that tracks the mouse cursor position across screen, viewport, page, and element coordinate systems, updating in real time.
Import: `import { useMouse } from '@reactuses/core'`

# useMouse

React sensor hooks that track cursor position

`useMouse` tracks the mouse cursor position across multiple coordinate systems by listening to [`mousemove`](https://developer.mozilla.org/en-US/docs/Web/API/Element/mousemove_event) events. It returns an object with `screenX`/`screenY` (relative to the screen), `clientX`/`clientY` (relative to the viewport), `pageX`/`pageY` (relative to the document), and `elementX`/`elementY`/`elementW`/`elementH`/`elementPosX`/`elementPosY` (relative to a target element, if provided). All values update in real time as the cursor moves.

### When to Use

- Building custom cursors, tooltips, or context menus that follow the mouse position
- Implementing drag interactions, drawing canvases, or parallax effects
- Tracking mouse position relative to a specific element for hover-based visualizations

### Notes

- **SSR-safe**: Returns all coordinates as `0` during server-side rendering. No `mousemove` listeners are attached on the server.
- **Element-relative coordinates**: Pass a ref to a DOM element to also get coordinates relative to that element, including its dimensions and position.
- **Related hooks**: See also `useMousePressed` for tracking press state, and `useElementByPoint` for detecting which element is under the cursor.

## Usage

```tsx live
function Demo() {
  const mouse = useMouse();

  return (
    <div>
      <p>
        Client - x: {mouse.clientX}, y: {mouse.clientY}
      </p>
      <p>
        Page - x: {mouse.pageX}, y: {mouse.pageY}
      </p>
      <p>
        Screen - x: {mouse.screenX}, y: {mouse.screenY}
      </p>
    </div>
  );
};

```

---

## useMousePressed

URL: https://reactuse.com/browser/usemousepressed/
Category: browser
Description: useMousePressed is a React hook that tracks whether the mouse or touch is currently pressed on a target element, with the input source type.
Import: `import { useMousePressed } from '@reactuses/core'`

# useMousePressed

React Sensor Hook that tracks mouse pressing state.

Triggered by mousedown touchstart on target element and released by mouseup mouseleave touchend touchcancel on window

`useMousePressed` returns a tuple of a boolean indicating whether the mouse (or touch) is currently pressed and a source type string (`"mouse"`, `"touch"`, or `null`). It listens for `mousedown`/`touchstart`/`dragstart` events on the target element and releases on `mouseup`/`mouseleave`/`touchend`/`touchcancel`/`dragend`/`drop` on `window`. You can configure which input types (touch, drag) to listen for.

### When to Use

- Implementing press-and-hold visual feedback (e.g., button ripple effects or scale animations)
- Building drawing or painting tools that need to know when the user is actively pressing
- Detecting whether a drag operation is in progress across the page

### Notes

- **SSR-safe**: Returns `false` for pressed state and `null` for source type during server-side rendering. No event listeners are attached on the server.
- **Input sources**: By default, mouse, touch, and drag events are all tracked. Disable touch or drag tracking via the `touch` and `drag` options.
- **Related hooks**: See also `useMouse` for tracking cursor position, and `useLongPress` for detecting extended press gestures.

## Usage

```tsx live
function Demo() {
  const [mouse, type] = useMousePressed();

  return (
    <div>
      <p>Pressed: {JSON.stringify(mouse)}</p>
      <p>SourceType: {JSON.stringify(type)}</p>
    </div>
  );
};

```

---

## useNetwork

URL: https://reactuse.com/browser/usenetwork/
Category: browser
Description: useNetwork is a React hook that tracks the browser's network connection — online status, effective type, downlink, RTT, and save-data, updating reactively.
Import: `import { useNetwork } from '@reactuses/core'`

# useNetwork

Tracks the state of browser's network connection.

As of the standard it is not guaranteed that browser connected to the Internet, it only guarantees the network connection

`useNetwork` wraps the [Network Information API](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation) and the `online`/`offline` events to provide a comprehensive view of network status. It returns an object with `online` (boolean), `previous` online state, `since` (timestamp of last change), and detailed connection info including `downlink`, `effectiveType` (2g/3g/4g), `rtt`, `type` (wifi/cellular/ethernet), and `saveData`. Values update reactively as network conditions change.

### When to Use

- Displaying online/offline status indicators and showing fallback UI when disconnected
- Adapting content quality (image resolution, video bitrate) based on connection speed
- Implementing offline-first features that queue actions and sync when connectivity returns

### Notes

- **SSR-safe**: Returns `undefined` for all values during server-side rendering. No `navigator` or `window` event access occurs on the server.
- **Network Information API**: Detailed connection properties (`downlink`, `effectiveType`, `rtt`, `type`) are only available in Chromium-based browsers. The `online` status is universally supported.
- **Related hooks**: See also `useOnline` for a simpler boolean wrapper around network connectivity status.

## Usage

```tsx live
function Demo() {
  const state = useNetwork();

  return <pre>{JSON.stringify(state, null, 2)}</pre>;
};

```

---

## useObjectUrl

URL: https://reactuse.com/browser/useobjecturl/
Category: browser
Description: useObjectUrl is a React hook that creates an object URL for a File, Blob, or MediaSource and automatically calls revokeObjectURL to prevent memory leaks.
Import: `import { useObjectUrl } from '@reactuses/core'`

# useObjectUrl

Creates an URL for the provided `File`, `Blob`, or `MediaSource` via [URL.createObjectURL()](https://developer.mozilla.org/en-US/docs/Web/API/URL/createObjectURL) and automatically releases the URL via [URL.revokeObjectURL()](https://developer.mozilla.org/en-US/docs/Web/API/URL/revokeObjectURL) when the source changes or the component is unmounted

`useObjectUrl` manages the lifecycle of object URLs created from `Blob`, `File`, or `MediaSource` objects. It calls [`URL.createObjectURL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/createObjectURL) when the source is provided and automatically revokes the URL with [`URL.revokeObjectURL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/revokeObjectURL) when the source changes or the component unmounts, preventing memory leaks.

### When to Use

- Previewing user-selected files (images, videos, PDFs) before upload
- Displaying Blob data from API responses as downloadable links or embedded media
- Creating temporary URLs for dynamically generated content (e.g., canvas exports)

### Notes

- **SSR-safe**: Returns `undefined` during server-side rendering. No `URL` API access occurs on the server.
- **Memory management**: The hook automatically revokes old object URLs when the source changes or on unmount, preventing the memory leaks that commonly occur with manual `createObjectURL` usage.
- **Related hooks**: See also `useFileDialog` for selecting files from the user's device.

## Usage

```tsx live
function Demo() {
  const [file, setFile] = useState<File>();
  const url = useObjectUrl(file);

  const onFileChange = (e: ChangeEvent<HTMLInputElement>) => {
    const target = e.target;
    const files = target.files;
    setFile(files && files.length > 0 ? files[0] : undefined);
  };
  return (
    <div>
      <p>Select File</p>
      <input type="file" onChange={onFileChange} />
      <p>Object Url</p>
      <div>{url}</div>
    </div>
  );
};

```

---

## useOnline

URL: https://reactuse.com/browser/useonline/
Category: browser
Description: useOnline is a React hook that returns a boolean for whether the browser is currently online, updating via the window online and offline events.
Import: `import { useOnline } from '@reactuses/core'`

# useOnline

A wrapper of `useNetwork`

`useOnline` is a lightweight wrapper around `useNetwork` that returns a single boolean indicating whether the browser is currently connected to the network. It listens to the [`online`](https://developer.mozilla.org/en-US/docs/Web/API/Window/online_event) and [`offline`](https://developer.mozilla.org/en-US/docs/Web/API/Window/offline_event) events on `window` and updates reactively. Use this when you only need to know if the user is online, without the detailed connection info that `useNetwork` provides.

### When to Use

- Showing a simple "You are offline" banner or toast notification
- Disabling form submissions or API calls when the user is disconnected
- Toggling between online and offline modes in an offline-first application

### Notes

- **SSR-safe**: Returns `undefined` during server-side rendering. No `navigator.onLine` or `window` event access occurs on the server.
- **Simplicity vs. detail**: If you need more information (connection type, downlink speed, etc.), use `useNetwork` instead.
- **Browser behavior**: `navigator.onLine` indicates network connection, not internet reachability. A `true` value does not guarantee the user can reach your server.

## Usage

```tsx live
function Demo() {
  const online = useOnline();
  return <div>{JSON.stringify(online)}</div>;
};

```

---

## useOrientation

URL: https://reactuse.com/browser/useorientation/
Category: browser
Description: useOrientation is a React hook for the Screen Orientation API — track the device orientation angle and type, with lock and unlock controls.
Import: `import { useOrientation } from '@reactuses/core'`

# useOrientation

React sensor hook that tracks screen orientation of user's device.

`useOrientation` wraps the [Screen Orientation API](https://developer.mozilla.org/en-US/docs/Web/API/Screen/orientation) to reactively track the device's orientation angle and type (e.g., `portrait-primary`, `landscape-secondary`). It returns a tuple of the current orientation state, a `lock` function to lock the screen to a specific orientation, and an `unlock` function. The orientation state includes the `angle` (in degrees) and `type`.

### When to Use

- Adapting UI layouts when the device is rotated between portrait and landscape
- Locking screen orientation for games, video players, or presentation modes
- Displaying orientation-dependent content or triggering layout recalculations

### Notes

- **SSR-safe**: Returns default orientation values (`angle: 0`, `type: undefined`) during server-side rendering. No `screen.orientation` access occurs on the server.
- **Orientation lock**: The `lock` function requires the page to be in fullscreen mode in most browsers. Use alongside `useFullscreen` for reliable orientation locking.
- **Related hooks**: See also `useMobileLandscape` for a simplified boolean check, and `useMediaQuery` for custom orientation-based media queries.

## Usage

```tsx live
function Demo() {
  const [state] = useOrientation();

  return <pre>{JSON.stringify(state, null, 2)}</pre>;
};

```

---

## usePageLeave

URL: https://reactuse.com/browser/usepageleave/
Category: browser
Description: usePageLeave is a React hook that detects when the mouse cursor leaves the page viewport — commonly used to trigger exit-intent actions.
Import: `import { usePageLeave } from '@reactuses/core'`

# usePageLeave

React sensor hook that tracks when mouse leaves the page

`usePageLeave` detects when the user's mouse cursor leaves the page viewport by listening to the [`mouseout`](https://developer.mozilla.org/en-US/docs/Web/API/Element/mouseout_event) event on `document`. It returns a boolean that is `true` when the cursor is outside the page and `false` when inside. This is commonly used to trigger exit-intent actions.

### When to Use

- Showing exit-intent popups or special offers when the user moves the cursor toward the browser's close button or address bar
- Pausing animations or media when the user's attention appears to be leaving the page
- Triggering auto-save or state preservation when the user seems about to navigate away

### Notes

- **SSR-safe**: Returns `false` during server-side rendering. No `document` event listeners are attached on the server.
- **Mouse only**: This hook tracks mouse cursor position, so it does not detect page leave on touch-only devices. For detecting when the user switches tabs, see the `document.visibilitychange` event.
- **Related hooks**: See also `useIdle` for detecting user inactivity within the page.

## Usage

```tsx live
function Demo() {
  const isLeft = usePageLeave();

  return <div>isLeft: {JSON.stringify(isLeft)}</div>;
};

```

---

## usePermission

URL: https://reactuse.com/browser/usepermission/
Category: browser
Description: usePermission is a React hook for the Permissions API — reactively query and track the status (granted, denied, prompt) of a browser permission.
Import: `import { usePermission } from '@reactuses/core'`

# usePermission

React side-effect hook to query permission status of browser APIs

`usePermission` wraps the [Permissions API](https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API) to reactively query and track the status of a browser permission. Pass a permission name (e.g., `"geolocation"`, `"camera"`, `"clipboard-read"`) and it returns the current state: `"granted"`, `"denied"`, `"prompt"`, or `""` (empty string when the API is unavailable). The value updates automatically if the user changes the permission.

### When to Use

- Checking permission status before attempting to use restricted APIs (clipboard, geolocation, camera, microphone)
- Displaying appropriate UI based on whether a permission has been granted, denied, or not yet requested
- Building settings pages that show the current state of all relevant permissions

### Notes

- **SSR-safe**: Returns an empty string (`""`) during server-side rendering. No `navigator.permissions` access occurs on the server.
- **Reactive**: The hook subscribes to the permission's `change` event, so the returned state updates in real time if the user revokes or grants the permission through browser settings.
- **Related hooks**: Often used alongside `useClipboard`, `useGeolocation`, `useMediaDevices`, and `useWebNotification` to check their respective permissions before use.

## Usage

```tsx live
function Demo() {
  const state = usePermission({ name: "microphone" });

  return <pre>{JSON.stringify(state, null, 2)}</pre>;
};

```

---

## usePlatform

URL: https://reactuse.com/browser/useplatform/
Category: browser
Description: usePlatform is a React hook that detects the user's device platform (iOS, Android) from the user agent, with WeChat and mini-program helpers and SSR support.
Import: `import { usePlatform } from '@reactuses/core'`

# usePlatform

React hook to tracked the platform of the user.

`usePlatform` detects the user's device platform by parsing the user agent string via [`navigator.userAgent`](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/userAgent). It returns an object with a `platform` value (`"ios"`, `"android"`, or `"unknown"`) along with helper methods: `isInMiniProgram()`, `isInWechat()`, and `isiPhoneX()`. For SSR, you can pass a `userAgent` string to enable server-side detection.

### When to Use

- Rendering platform-specific UI or behavior (e.g., different scroll handling on iOS vs. Android)
- Detecting WeChat or mini-program environments for specialized integrations
- Adjusting safe-area insets or notch handling on iPhone X and newer models

### Notes

- **SSR-safe**: Accepts an optional `userAgent` prop for server-side rendering. Without it, returns `"unknown"` as the platform on the server.
- **User agent parsing**: Detection relies on `navigator.userAgent`, which can be spoofed. Use for progressive enhancement, not security-critical decisions.
- **Related hooks**: See also `useScreenSafeArea` for safe-area inset values and `useMobileLandscape` for orientation detection on mobile devices.

## Usage

```tsx live
function Demo() {
  const {platform} = usePlatform();

  return <p>platfrom: {platform}</p>;
};

```

---

## usePreferredColorScheme

URL: https://reactuse.com/browser/usepreferredcolorscheme/
Category: browser
Description: usePreferredColorScheme is a React hook that reactively tracks the system color scheme preference — returns dark, light, or no-preference.
Import: `import { usePreferredColorScheme } from '@reactuses/core'`

# usePreferredColorScheme

[prefers-color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme) media query

`usePreferredColorScheme` uses [`window.matchMedia()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia) to reactively track the user's system color scheme preference. It returns `"dark"`, `"light"`, or `"no-preference"` based on the [`prefers-color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme) media query. The value updates automatically when the user changes their system theme settings.

### When to Use

- Detecting the user's system theme to set an initial application color scheme
- Building theme-aware components that respect OS-level dark/light mode settings
- Providing a "system" option in theme selectors that follows the OS preference

### Notes

- **SSR-safe**: Accepts a `defaultState` parameter (default: `"no-preference"`) that is returned during server-side rendering. No `window.matchMedia` access occurs on the server.
- **Reactive**: Updates in real time when the user switches their system color scheme (e.g., enabling dark mode in OS settings).
- **Related hooks**: See also `usePreferredDark` for a simpler boolean check, `useColorMode` for multi-theme management, and `useDarkMode` for dark/light toggle with persistence.

## Usage

```tsx live
function Demo() {
  const color = usePreferredColorScheme();

  return <div>PreferredColorScheme: {color}</div>;
};

```

---

## usePreferredContrast

URL: https://reactuse.com/browser/usepreferredcontrast/
Category: browser
Description: usePreferredContrast is a React hook that reactively tracks the system contrast preference — returns more, less, custom, or no-preference.
Import: `import { usePreferredContrast } from '@reactuses/core'`

# usePreferredContrast

[prefers-contrast](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-contrast) media query

`usePreferredContrast` uses [`window.matchMedia()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia) to reactively track the user's contrast preference. It returns `"more"`, `"less"`, `"custom"`, or `"no-preference"` based on the [`prefers-contrast`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-contrast) media query. The value updates automatically when the user changes their system accessibility settings.

### When to Use

- Increasing border widths, font weights, or color contrast for users who prefer more contrast
- Reducing visual intensity for users who prefer less contrast
- Building accessible interfaces that adapt to system-level contrast preferences

### Notes

- **SSR-safe**: Accepts a `defaultState` parameter (default: `"no-preference"`) that is returned during server-side rendering. No `window.matchMedia` access occurs on the server.
- **Browser support**: The `prefers-contrast` media query is supported in modern browsers, but availability varies. Check [MDN compatibility](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-contrast#browser_compatibility) for details.
- **Related hooks**: Built on `useMediaQuery`. See also `useReducedMotion` and `usePreferredColorScheme` for other accessibility-related media query hooks.

## Usage

```tsx live
function Demo() {
  const contrast = usePreferredContrast();

  return <div>PreferredContrast: {contrast}</div>;
};

```

---

## usePreferredDark

URL: https://reactuse.com/browser/usepreferreddark/
Category: browser
Description: usePreferredDark is a React hook that returns a boolean for whether the user prefers a dark color scheme, updating when system dark mode is toggled.
Import: `import { usePreferredDark } from '@reactuses/core'`

# usePreferredDark

React Hook that tracks dark theme preference

`usePreferredDark` uses [`window.matchMedia()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia) with the `(prefers-color-scheme: dark)` media query to return a boolean indicating whether the user prefers a dark color scheme. The value updates automatically when the user toggles their system dark mode setting. This is a simpler alternative to `usePreferredColorScheme` when you only need a boolean.

### When to Use

- Setting a default dark/light theme based on the user's OS preference
- Conditionally applying dark-mode styles or class names in your components
- Determining the initial value for a theme toggle in your application

### Notes

- **SSR-safe**: Accepts a `defaultState` parameter (default: `false`) that is returned during server-side rendering. No `window.matchMedia` access occurs on the server.
- **Reactive**: Updates immediately when the user changes their system dark mode preference.
- **Related hooks**: See also `usePreferredColorScheme` for `"dark"`/`"light"`/`"no-preference"` string values, `useDarkMode` for a toggle with localStorage persistence, and `useColorMode` for multi-theme support.

## Usage

```tsx live
function Demo() {
  const isDark = usePreferredDark(false);

  return <div>PreferredDark: {JSON.stringify(isDark)}</div>;
};

```

---

## usePreferredLanguages

URL: https://reactuse.com/browser/usepreferredlanguages/
Category: browser
Description: usePreferredLanguages is a React hook that reactively tracks navigator.languages, returning the user's preferred language tags as they change.
Import: `import { usePreferredLanguages } from '@reactuses/core'`

# usePreferredLanguages

`usePreferredLanguages` is a hook that returns the user's preferred languages as an array of strings. It uses the `navigator.languages`.

`usePreferredLanguages` reactively tracks [`navigator.languages`](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/languages), returning an array of BCP 47 language tags (e.g., `["en-US", "en", "fr"]`) ordered by user preference. The hook listens for the [`languagechange`](https://developer.mozilla.org/en-US/docs/Web/API/Window/languagechange_event) event and updates automatically when the user modifies their browser or system language settings.

### When to Use

- Selecting the best available locale for i18n/l10n based on the user's language preferences
- Displaying language-appropriate content, date formats, or number formats
- Building language selector UIs that highlight the user's preferred languages

### Notes

- **SSR-safe**: Accepts a `defaultLanguages` parameter that is returned during server-side rendering. No `navigator` access occurs on the server.
- **Reactive**: Automatically updates when the user changes their browser language preferences via the `languagechange` event.
- **Order matters**: The returned array is ordered by preference. The first element is the user's most preferred language.

## Usage

```tsx live
function Demo() {
  const preferredLanguages = usePreferredLanguages();
  return <div>PreferredLanguages: {JSON.stringify(preferredLanguages)}</div>;
};

```

---

## useReducedMotion

URL: https://reactuse.com/browser/usereducedmotion/
Category: browser
Description: useReducedMotion is a React hook that returns whether the user has requested reduced motion — use it to disable or simplify animations.
Import: `import { useReducedMotion } from '@reactuses/core'`

# useReducedMotion

React Hook that tracks motion preference

`useReducedMotion` uses [`window.matchMedia()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia) with the [`prefers-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) media query to return a boolean indicating whether the user has requested reduced motion. The value updates automatically when the user changes their system accessibility settings. Use this to disable or simplify animations for users who are sensitive to motion.

### When to Use

- Disabling or reducing complex CSS/JS animations for users with vestibular disorders
- Replacing animated transitions with instant state changes when reduced motion is preferred
- Choosing between animated and static versions of UI elements (e.g., carousels, parallax effects)

### Notes

- **SSR-safe**: Accepts a `defaultState` parameter (default: `false`) that is returned during server-side rendering. No `window.matchMedia` access occurs on the server.
- **Accessibility**: Respecting the `prefers-reduced-motion` preference is an important accessibility practice. Consider disabling auto-playing animations and reducing transition durations.
- **Related hooks**: Built on `useMediaQuery`. See also `usePreferredContrast` and `usePreferredColorScheme` for other accessibility-related preference hooks.

## Usage

```tsx live
function Demo() {
  const motion = useReducedMotion(false);

  return <div>ReducedMotion: {JSON.stringify(motion)}</div>;
};

```

---

## useScratch

URL: https://reactuse.com/browser/usescratch/
Category: browser
Description: useScratch is a React hook that tracks scratch and drag gestures on an element across mouse and touch — returns position, deltas, and timing.
Import: `import { useScratch } from '@reactuses/core'`

# useScratch

React sensor hook that tracks scratching/dragging gestures on an element with mouse and touch support.

`useScratch` tracks mouse and touch drag gestures on a target element, returning detailed state including `isScratching`, position coordinates (`x`, `y`), deltas (`dx`, `dy`), document-level coordinates (`docX`, `docY`), element dimensions, and timing information. It supports callbacks for scratch start, ongoing scratch, and scratch end events. This is useful for building drawing, swiping, or gesture-driven interactions.

### When to Use

- Building drawing or signature pads that track pointer movement within an element
- Implementing swipe gestures for cards, carousels, or dismissible elements
- Creating interactive scratch-off or reveal-on-drag effects

### Notes

- **SSR-safe**: Returns a default state with `isScratching: false` and undefined coordinates during server-side rendering. No event listeners are attached on the server.
- **Mouse and touch**: Handles both `mousedown`/`mousemove`/`mouseup` and `touchstart`/`touchmove`/`touchend` events for cross-device compatibility.
- **Related hooks**: See also `useMouse` for general cursor tracking and `useLongPress` for press-and-hold detection.

## Usage

```tsx live
function Demo() {
  const elementRef = useRef(null);
  const state = useScratch(elementRef, {
    onScratchStart: (s) => {
      console.log('Scratch started:', s);
    },
    onScratch: (s) => {
      console.log('Scratching:', s);
    },
    onScratchEnd: (s) => {
      console.log('Scratch ended:', s);
    },
  });

  return (
    <div style={{ padding: '20px' }}>
      <div
        ref={elementRef}
        style={{
          width: '300px',
          height: '200px',
          border: '1px solid var(--ifm-color-emphasis-300)',
          borderRadius: '8px',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
          backgroundColor: state.isScratching ? 'var(--ifm-color-emphasis-200)' : 'var(--ifm-background-surface-color)',
          color: 'var(--ifm-color-content)',
          cursor: 'pointer',
          userSelect: 'none',
        }}
      >
        {state.isScratching ? 'Scratching...' : 'Click and drag to scratch'}
      </div>
      <div style={{ marginTop: '20px', fontFamily: 'monospace', fontSize: '12px', color: 'var(--ifm-color-content)' }}>
        <div><strong>isScratching:</strong> {state.isScratching ? 'true' : 'false'}</div>
        {state.x !== undefined && <div><strong>x:</strong> {Math.round(state.x)}</div>}
        {state.y !== undefined && <div><strong>y:</strong> {Math.round(state.y)}</div>}
        {state.dx !== undefined && <div><strong>dx:</strong> {Math.round(state.dx)}</div>}
        {state.dy !== undefined && <div><strong>dy:</strong> {Math.round(state.dy)}</div>}
      </div>
    </div>
  );
};

```

---

## useScreenSafeArea

URL: https://reactuse.com/browser/usescreensafearea/
Category: browser
Description: useScreenSafeArea is a React hook that reads CSS env(safe-area-inset-*) values — get the safe area insets for devices with notches or system bars.
Import: `import { useScreenSafeArea } from '@reactuses/core'`

# useScreenSafeArea

React sensor hook that tracks `env(safe-area-inset-*)`

`useScreenSafeArea` reads the CSS [`env(safe-area-inset-*)`](https://developer.mozilla.org/en-US/docs/Web/CSS/env) values to determine the safe area insets on devices with notches, rounded corners, or software navigation bars. It returns a tuple of four strings (`top`, `right`, `bottom`, `left`) representing the inset values, plus a debounced `update` function for manual refresh. These values are useful for positioning content to avoid being obscured by device hardware or system UI.

### When to Use

- Positioning fixed or sticky elements (headers, footers, FABs) to avoid overlap with device notches or home indicators
- Adjusting layout padding on iOS devices with notches or Android devices with gesture navigation bars
- Building full-viewport experiences (games, maps) that need to account for hardware obstructions

### Notes

- **SSR-safe**: Returns `"0px"` for all insets during server-side rendering. No DOM or CSS computation occurs on the server.
- **CSS `env()` function**: Requires the page to include `<meta name="viewport" content="viewport-fit=cover">` for the safe area insets to be non-zero.
- **Related hooks**: See also `usePlatform` for detecting the device platform and `useMobileLandscape` for orientation detection.

## Usage

```tsx live
function Demo() {
  const [top, right, bottom, left] = useScreenSafeArea();
  return (
    <div>
      <div>
        top: <>{top}</>
      </div>
      <div>
        bottom: <>{bottom}</>
      </div>
      <div>
        left: <>{left}</>
      </div>
      <div>
        right: <>{right}</>
      </div>
    </div>
  );
};

```

---

## useScriptTag

URL: https://reactuse.com/browser/usescripttag/
Category: browser
Description: useScriptTag is a React hook that dynamically injects a script tag and manages its lifecycle — returns load status plus load and unload controls.
Import: `import { useScriptTag } from '@reactuses/core'`

# useScriptTag

Script tag injecting

`useScriptTag` dynamically injects a `<script>` tag into the document and manages its lifecycle. It returns a tuple of the script element, a loading status (`"idle"`, `"loading"`, `"ready"`, or `"error"`), a `load` function, and an `unload` function. The hook supports options for `async`, `defer`, `type`, `crossOrigin`, `referrerPolicy`, custom attributes, and manual load/unload control.

### When to Use

- Loading third-party libraries (analytics, widgets, maps) on demand rather than at build time
- Deferring heavy scripts until a component mounts or a user interaction occurs
- Dynamically loading different script versions or configurations based on runtime conditions

### Notes

- **SSR-safe**: The hook is a no-op during server-side rendering. No `<script>` elements are created on the server. The status will be `"idle"` until the component mounts in the browser.
- **Lifecycle management**: The script is automatically removed from the DOM when the component unmounts (unless `manual` is set to `true`). Use `load` and `unload` for fine-grained control.
- **Deduplication**: If a script with the same `src` already exists in the document, the hook will reuse it rather than creating a duplicate.

## Usage

```tsx live
// it's an example, use your types instead

// Add this if you are using TypeScript
// declare const jQuery: any;
function Demo() {
  const [, status] = useScriptTag(
    "https://code.jquery.com/jquery-3.5.1.min.js",
  );

  const [version, setVersion] = useState(0);
  useEffect(() => {
    if (typeof jQuery !== "undefined") {
      setVersion(jQuery.fn.jquery);
    }
  }, [status]);

  return <div>jQuery version: {version}</div>;
};

```

---

## useScroll

URL: https://reactuse.com/browser/usescroll/
Category: browser
Description: useScroll is a React hook that reactively tracks an element or window's scroll position and state — x, y, isScrolling, arrived edges, and direction.
Import: `import { useScroll } from '@reactuses/core'`

# useScroll

React Sensor Hook that tracks scroll position and state

`useScroll` reactively tracks the scroll position and state of a target element (or `window`/`document`). It returns a tuple of `x` position, `y` position, `isScrolling` boolean, an `arrivedState` object (`{ top, bottom, left, right }` booleans indicating edge arrival), and a `directions` object indicating the current scroll direction. The hook supports throttling, offset configuration, and callbacks for scroll and scroll-end events.

### When to Use

- Implementing scroll-dependent UI such as sticky headers, scroll progress bars, or "back to top" buttons
- Detecting when the user has scrolled to the top or bottom of a container (e.g., for loading more content)
- Tracking scroll direction to show or hide navigation elements

### Notes

- **SSR-safe**: Returns `0` for positions, `false` for `isScrolling`, and default arrived/direction states during server-side rendering. No scroll listeners are attached on the server.
- **Throttling**: Use the `throttle` option to limit how often the scroll handler fires, improving performance for complex scroll-based UI updates.
- **Related hooks**: See also `useInfiniteScroll` for automatic load-more triggers, `useScrollLock` for disabling scroll, and `useScrollIntoView` for programmatic scrolling.

## Usage

```tsx live
function Demo() {
  const elementRef = useRef<HTMLDivElement>(null);
  const [x, y, isScrolling, arrivedState, directions] = useScroll(elementRef);
  const { left, right, top, bottom } = useMemo(
    () => arrivedState,
    [arrivedState],
  );
  const {
    left: toLeft,
    right: toRight,
    top: toTop,
    bottom: toBottom,
  } = useMemo(() => directions, [directions]);

  const absoluteStyle: CSSProperties = {
    paddingTop: "0.25rem",
    paddingBottom: "0.25rem",
    paddingLeft: "0.5rem",
    paddingRight: "0.5rem",
    position: "absolute",
  };
  return (
    <div style={{ display: "flex" }}>
      <div
        ref={elementRef}
        style={{
          width: 300,
          height: 300,
          margin: "auto",
          borderRadius: "0.25rem",
          overflow: "scroll",
        }}
      >
        <div style={{ width: 500, height: 400, position: "relative" }}>
          <div
            style={{
              ...absoluteStyle,
              top: "0rem",
              left: "0rem",
            }}
          >
            TopLeft
          </div>
          <div
            style={{
              ...absoluteStyle,
              bottom: "0rem",
              left: "0rem",
            }}
          >
            BottomLeft
          </div>
          <div
            style={{
              ...absoluteStyle,
              top: "0rem",
              right: "0rem",
            }}
          >
            TopRight
          </div>
          <div
            style={{
              ...absoluteStyle,
              bottom: "0rem",
              right: "0rem",
            }}
          >
            BottomRight
          </div>
          <div
            style={{
              ...absoluteStyle,
              top: "33.33333%",
              left: "33.33333%",
            }}
          >
            Scroll Me
          </div>
        </div>
      </div>
      <div
        style={{
          width: 280,
          margin: "auto",
          paddingLeft: "1rem",
          display: "flex",
          flexDirection: "column",
          gap: 5,
        }}
      >
        <div>
          Position: {x.toFixed(1)}, {y.toFixed(1)}
        </div>
        <div>isScrolling: {JSON.stringify(isScrolling)}</div>
        <div>Top Arrived: {JSON.stringify(top)}</div>
        <div>Right Arrived: {JSON.stringify(right)}</div>
        <div>Bottom Arrived: {JSON.stringify(bottom)}</div>
        <div>Left Arrived: {JSON.stringify(left)}</div>
        <div>Scrolling Up: {JSON.stringify(toTop)}</div>
        <div>Scrolling Right: {JSON.stringify(toRight)}</div>
        <div>Scrolling Down: {JSON.stringify(toBottom)}</div>
        <div>Scrolling Left: {JSON.stringify(toLeft)}</div>
      </div>
    </div>
  );
};

```

---

## useScrollIntoView

URL: https://reactuse.com/browser/usescrollintoview/
Category: browser
Description: useScrollIntoView is a React hook for smooth animated scrolling to a target element ref — like Element.scrollIntoView but with axis, duration, and easing control.
Import: `import { useScrollIntoView } from '@reactuses/core'`

# useScrollIntoView

React sensor hook works like `element.scrollIntoView()`

`useScrollIntoView` provides a smooth, animated scroll to a target element, similar to [`Element.scrollIntoView()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView) but with more control. It returns an object with `scrollIntoView` (accepting alignment options like `"start"`, `"end"`, `"center"`) and `cancel` functions. You can configure the scroll axis, duration, easing function, offset, and whether the user can interrupt the animation by scrolling.

### When to Use

- Scrolling to anchored sections with smooth, customizable animation (e.g., table of contents navigation)
- Focusing on newly added content, error messages, or form fields after validation
- Building scrollable lists where selecting an item scrolls it into the visible area

### Notes

- **SSR-safe**: Returns no-op functions during server-side rendering. No DOM scrolling occurs on the server.
- **Cancelable**: Set `cancelable: true` (default) to allow the user to interrupt the scroll animation by manually scrolling. Set `isList: true` to prevent content jumping in lists.
- **Related hooks**: See also `useScroll` for tracking scroll position and state, and `useScrollLock` for preventing scroll entirely.

## Usage

```tsx live
function Demo() {
  const targetRef = useRef<HTMLParagraphElement>(null);
  const { scrollIntoView } = useScrollIntoView(targetRef, {
    offset: 60,
  });

  return (
    <div>
      <button onClick={() => scrollIntoView({ alignment: "center" })}>
        Scroll to target
      </button>
      <div style={{ height: "50vh" }} />
      <p ref={targetRef}>Hello there</p>
    </div>
  );
};

```

---

## useScrollLock

URL: https://reactuse.com/browser/usescrolllock/
Category: browser
Description: useScrollLock is a React hook that locks scrolling on an element while preserving scroll inside nested containers — ideal for modals and overlays.
Import: `import { useScrollLock } from '@reactuses/core'`

# useScrollLock

Lock scrolling of the element while preserving scrolling within nested scrollable containers.

`useScrollLock` prevents scrolling on a target element by setting `overflow: hidden` on the element's style. It returns a tuple of the current lock state (boolean) and a setter function to toggle the lock. Crucially, it preserves scrolling within nested scrollable containers inside the locked element, so inner content remains interactive. The lock is automatically released when the component unmounts.

### When to Use

- Preventing background scroll when a modal, dialog, or drawer is open
- Locking scroll on the body while displaying a fullscreen overlay or lightbox
- Disabling scroll temporarily during drag-and-drop operations to prevent accidental scrolling

### Notes

- **SSR-safe**: Returns `false` for the lock state and a no-op setter during server-side rendering. No DOM style manipulation occurs on the server.
- **Nested scrolling**: Unlike naive `overflow: hidden` approaches, this hook preserves scrolling within child scrollable containers, making it suitable for dialogs with scrollable content.
- **Related hooks**: See also `useScroll` for tracking scroll position, `useScrollIntoView` for programmatic scrolling, and `useFullscreen` for immersive display modes.

## Usage

```tsx live
function Demo() {
  const elementRef = useRef<HTMLDivElement>(null);
  const [locked, setLocked] = useScrollLock(elementRef);

  const absoluteStyle: CSSProperties = {
    paddingTop: "0.25rem",
    paddingBottom: "0.25rem",
    paddingLeft: "0.5rem",
    paddingRight: "0.5rem",
    position: "absolute",
  };
  return (
    <div style={{ display: "flex" }}>
      <div
        ref={elementRef}
        style={{
          width: 300,
          height: 300,
          margin: "auto",
          borderRadius: "0.25rem",
          overflow: "scroll",
          border: "1px solid var(--ifm-color-emphasis-200)",
        }}
      >
        <div style={{ width: 500, height: 400, position: "relative" }}>
          <div
            style={{
              ...absoluteStyle,
              top: "0rem",
              left: "0rem",
            }}
          >
            TopLeft
          </div>
          <div
            style={{
              ...absoluteStyle,
              bottom: "0rem",
              left: "0rem",
            }}
          >
            BottomLeft
          </div>
          <div
            style={{
              ...absoluteStyle,
              top: "0rem",
              right: "0rem",
            }}
          >
            TopRight
          </div>
          <div
            style={{
              ...absoluteStyle,
              bottom: "0rem",
              right: "0rem",
            }}
          >
            BottomRight
          </div>
          <div
            style={{
              ...absoluteStyle,
              top: "33.33333%",
              left: "33.33333%",
            }}
          >
            Scroll Me
          </div>
        </div>
      </div>
      <div
        style={{
          width: 280,
          margin: "auto",
          paddingLeft: "1rem",
          display: "flex",
          flexDirection: "column",
          gap: 5,
        }}
      >
        <div>Locked: {JSON.stringify(locked)}</div>
        <button
          onClick={() => {
            setLocked(!locked);
          }}
          style={{
            padding: "8px 16px",
            border: "1px solid var(--ifm-color-emphasis-300)",
            backgroundColor: "var(--ifm-background-color)",
            color: "var(--ifm-color-content)",
            borderRadius: "4px",
            cursor: "pointer",
          }}
        >
          {locked ? "Unlock" : "Lock"}
        </button>
      </div>
    </div>
  );
};

```

## Dialog Example

```tsx live
function DialogDemo() {
  const { cloneElement, ReactElement, useRef, useState } = React;
  
  const Dialog = ({ trigger }: { trigger: ReactElement }) => {
    const dialogRef = useRef<HTMLDialogElement>(null);
    const boxRef = useRef(null);
    const [isOpen, setIsOpen] = useState(false);
    const [, setLock] = useScrollLock(document.body);

    const open = () => {
      setIsOpen(true);
      dialogRef.current?.showModal();
      setLock(true);
    };

    const close = () => {
      setIsOpen(false);
      dialogRef.current?.close();
      setLock(false);
    };

    useEventListener("close", () => setIsOpen(false), dialogRef);
    useClickOutside(boxRef, close);

    return (
      <>
        {cloneElement(trigger, { onClick: open })}

        <dialog 
          ref={dialogRef}
          style={{
            padding: 0,
            border: "none",
            borderRadius: "8px",
            boxShadow: "0 10px 25px rgba(0, 0, 0, 0.1)",
            maxWidth: "500px",
            width: "90vw",
          }}
        >
          <div 
            ref={boxRef}
            style={{
              padding: "24px",
              maxHeight: "70vh",
              overflow: "auto",
              backgroundColor: "var(--ifm-background-color)",
              borderRadius: "8px",
            }}
          >
            <h3 style={{ margin: "0 0 16px 0", color: "var(--ifm-color-content)" }}>
              Dialog with Scrollable Content
            </h3>
            <p style={{ lineHeight: "1.6", color: "var(--ifm-color-content-secondary)", margin: "16px 0" }}>
              This dialog demonstrates how useScrollLock works. 
              The background scrolling is locked, but you can still scroll within this dialog content.
            </p>
            <p style={{ lineHeight: "1.6", color: "var(--ifm-color-content-secondary)", margin: "16px 0" }}>
              Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque
              faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi
              pretium tellus duis convallis. Tempus leo eu aenean sed diam urna
              tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas.
              Iaculis massa nisl malesuada lacinia integer nunc posuere.
            </p>
            <p style={{ lineHeight: "1.6", color: "var(--ifm-color-content-secondary)", margin: "16px 0" }}>
              Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora
              torquent per conubia nostra inceptos himenaeos. Lorem ipsum dolor 
              sit amet consectetur adipiscing elit. Quisque faucibus ex sapien 
              vitae pellentesque sem placerat.
            </p>
            <p style={{ lineHeight: "1.6", color: "var(--ifm-color-content-secondary)", margin: "16px 0" }}>
              In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean 
              sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus 
              bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere.
            </p>
            <p style={{ lineHeight: "1.6", color: "var(--ifm-color-content-secondary)", margin: "16px 0" }}>
              Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora
              torquent per conubia nostra inceptos himenaeos. Sed cursus turpis 
              a purus aliquam condimentum. Nam bibendum cursus dolor.
            </p>
            <div style={{ 
              display: "flex", 
              justifyContent: "flex-end", 
              marginTop: "24px",
              gap: "12px"
            }}>
              <button
                onClick={close}
                style={{
                  padding: "8px 16px",
                  border: "1px solid var(--ifm-color-emphasis-300)",
                  backgroundColor: "var(--ifm-background-color)",
                  color: "var(--ifm-color-content)",
                  borderRadius: "4px",
                  cursor: "pointer",
                }}
              >
                Close
              </button>
            </div>
          </div>
        </dialog>
      </>
    );
  };

  return (
    <div style={{ padding: "20px", textAlign: "center" }}>
      <Dialog 
        trigger={
          <button
            style={{
              padding: "12px 24px",
              border: "1px solid var(--ifm-color-primary)",
              backgroundColor: "var(--ifm-color-primary)",
              color: "var(--ifm-color-white)",
              borderRadius: "4px",
              cursor: "pointer",
              fontSize: "16px",
            }}
          >
            Open Dialog
          </button>
        } 
      />
      <p style={{ 
        marginTop: "16px", 
        color: "var(--ifm-color-content-secondary)", 
        fontSize: "14px",
        maxWidth: "400px",
        margin: "16px auto 0"
      }}>
        Open the dialog and try scrolling. You'll be able to scroll 
        within the dialog content while background scrolling remains locked.
      </p>
    </div>
  );
}

```

---

## useSpeechRecognition

URL: https://reactuse.com/browser/usespeechrecognition/
Category: browser
Description: useSpeechRecognition is a React hook for the Web Speech API — real-time speech-to-text with language options, interim results, and start/stop controls.
Import: `import { useSpeechRecognition } from '@reactuses/core'`

# useSpeechRecognition

Reactive SpeechRecognition API for React

Real-time speech recognition with configurable options, cross-browser compatibility, and TypeScript support. Perfect for voice-controlled applications, dictation features, and accessibility enhancements.

`useSpeechRecognition` wraps the [Web Speech API's SpeechRecognition interface](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition) to provide real-time speech-to-text in React. It returns an object with `isSupported`, `isListening`, `isFinal`, the `result` text, `error` info, and `start`/`stop`/`toggle` functions. Options include language, continuous mode, interim results, and max alternatives. You can pass different options to each `start` call for dynamic configuration.

### When to Use

- Building voice command interfaces for hands-free application control
- Adding dictation/speech-to-text input to forms, editors, or note-taking apps
- Implementing accessibility features that allow voice input for users with mobility impairments

### Notes

- **SSR-safe**: Returns `isSupported: false` and no-op functions during server-side rendering. No `SpeechRecognition` constructor is called on the server.
- **Browser support**: The Web Speech API is primarily supported in Chromium-based browsers. Always check `isSupported` before displaying speech recognition UI.
- **HTTPS required**: In production, speech recognition requires a secure context (HTTPS). Microphone permission will be requested on first use.

## Usage

```tsx live
function Demo() {
  const {
    isSupported,
    isListening,
    isFinal,
    result,
    error,
    start,
    stop,
    toggle,
  } = useSpeechRecognition();

  if (!isSupported) {
    return <div>Speech recognition is not supported in this browser</div>;
  }

  return (
    <div>
      <div style={{ marginBottom: '20px' }}>
        <p><strong>Status:</strong> {isListening ? 'Listening...' : 'Stopped'}</p>
        <p><strong>Result:</strong> {result || 'No speech detected'}</p>
        <p><strong>Final:</strong> {isFinal ? 'Yes' : 'No'}</p>
        {error && <p style={{ color: 'var(--ifm-color-danger)' }}><strong>Error:</strong> {error.error}</p>}
      </div>
      
      <div style={{ display: 'flex', gap: '10px' }}>
        <button onClick={start} disabled={isListening}>
          Start
        </button>
        <button onClick={stop} disabled={!isListening}>
          Stop
        </button>
        <button onClick={() => toggle()}>
          Toggle
        </button>
      </div>
    </div>
  );
}
```

## With Custom Options

```tsx live
function Demo() {
  const {
    isSupported,
    isListening,
    result,
    start,
    stop,
  } = useSpeechRecognition({
    continuous: true,
    interimResults: true,
    lang: 'en-US',
    maxAlternatives: 1,
  });

  if (!isSupported) {
    return <div>Speech recognition is not supported</div>;
  }

  return (
    <div>
      <div style={{ marginBottom: '20px' }}>
        <p><strong>Recognition Result:</strong></p>
        <div style={{ 
          padding: '10px', 
          border: '1px solid var(--ifm-color-emphasis-200)', 
          borderRadius: '4px',
          minHeight: '60px',
          backgroundColor: 'var(--ifm-background-surface-color)'
        }}>
          {result || 'Start speaking...'}
        </div>
      </div>
      
      <div style={{ display: 'flex', gap: '10px' }}>
        <button 
          onClick={start} 
          disabled={isListening}
          style={{ 
            backgroundColor: isListening ? 'var(--ifm-color-emphasis-300)' : 'var(--ifm-color-primary)',
            color: 'var(--ifm-color-white)',
            border: 'none',
            padding: '8px 16px',
            borderRadius: '4px',
            cursor: 'pointer'
          }}
        >
          {isListening ? 'Listening...' : 'Start Recognition'}
        </button>
        <button 
          onClick={stop} 
          disabled={!isListening}
          style={{ 
            backgroundColor: !isListening ? 'var(--ifm-color-emphasis-300)' : 'var(--ifm-color-danger)',
            color: 'var(--ifm-color-white)',
            border: 'none',
            padding: '8px 16px',
            borderRadius: '4px',
            cursor: 'pointer'
          }}
        >
          Stop
        </button>
      </div>
    </div>
  );
}
```

## Multi-language Support

```tsx live
function Demo() {
  const [selectedLang, setSelectedLang] = React.useState('en-US');
  
  const {
    isSupported,
    isListening,
    result,
    start,
    stop,
  } = useSpeechRecognition({
    lang: selectedLang,
    continuous: true,
    interimResults: true,
  });

  const languages = [
    { code: 'en-US', name: 'English (US)' },
    { code: 'zh-CN', name: '中文 (简体)' },
    { code: 'ja-JP', name: '日本語' },
    { code: 'ko-KR', name: '한국어' },
    { code: 'es-ES', name: 'Español' },
    { code: 'fr-FR', name: 'Français' },
  ];

  if (!isSupported) {
    return <div>Speech recognition is not supported</div>;
  }

  return (
    <div>
      <div style={{ marginBottom: '20px' }}>
        <label>
          <strong>Language:</strong>
          <select 
            value={selectedLang} 
            onChange={(e) => setSelectedLang(e.target.value)}
            style={{ 
              marginLeft: '10px', 
              padding: '4px',
              backgroundColor: 'var(--ifm-background-color)',
              color: 'var(--ifm-color-content)',
              border: '1px solid var(--ifm-color-emphasis-300)',
              borderRadius: '4px'
            }}
            disabled={isListening}
          >
            {languages.map(lang => (
              <option key={lang.code} value={lang.code}>
                {lang.name}
              </option>
            ))}
          </select>
        </label>
      </div>
      
      <div style={{ marginBottom: '20px' }}>
        <div style={{ 
          padding: '10px', 
          border: '1px solid var(--ifm-color-emphasis-200)', 
          borderRadius: '4px',
          minHeight: '80px',
          backgroundColor: 'var(--ifm-background-surface-color)',
          color: 'var(--ifm-color-content)'
        }}>
          {result || `Start speaking in ${languages.find(l => l.code === selectedLang)?.name}...`}
        </div>
      </div>
      
      <div style={{ display: 'flex', gap: '10px' }}>
        <button onClick={() => start({ lang: selectedLang })} disabled={isListening}>
          Start ({selectedLang})
        </button>
        <button onClick={stop} disabled={!isListening}>
          Stop
        </button>
      </div>
    </div>
  );
}
```

## Dynamic Language and Mode Switching

```tsx live
function DynamicOptionsDemo() {
  const {
    isSupported,
    isListening,
    result,
    start,
    stop,
  } = useSpeechRecognition();

  const quickOptions = [
    { 
      language: 'en-US', 
      name: 'English (Continuous)', 
      flag: '🇺🇸', 
      continuous: true,
      color: 'var(--ifm-color-primary)'
    },
    { 
      language: 'en-US', 
      name: 'English (Single)', 
      flag: '🇺🇸', 
      continuous: false,
      color: 'var(--ifm-color-secondary)'
    },
    { 
      language: 'zh-CN', 
      name: '中文 (连续)', 
      flag: '🇨🇳', 
      continuous: true,
      color: 'var(--ifm-color-success)'
    },
    { 
      language: 'zh-CN', 
      name: '中文 (单次)', 
      flag: '🇨🇳', 
      continuous: false,
      color: 'var(--ifm-color-warning)'
    },
  ];

  if (!isSupported) {
    return <div>Speech recognition is not supported</div>;
  }

  return (
    <div>
      <div style={{ marginBottom: '20px' }}>
        <p><strong>Quick Start with Different Languages and Modes:</strong></p>
        <div style={{ 
          display: 'grid', 
          gridTemplateColumns: 'repeat(auto-fit, minmax(180px, 1fr))',
          gap: '10px',
          marginBottom: '16px'
        }}>
          {quickOptions.map((option, index) => (
            <button
              key={index}
              onClick={() => start({ lang: option.language, continuous: option.continuous })}
              disabled={isListening}
              style={{
                padding: '12px 8px',
                border: '1px solid var(--ifm-color-emphasis-300)',
                backgroundColor: isListening ? 'var(--ifm-color-emphasis-300)' : option.color,
                color: 'var(--ifm-color-white)',
                borderRadius: '6px',
                cursor: isListening ? 'not-allowed' : 'pointer',
                fontSize: '13px',
                display: 'flex',
                flexDirection: 'column',
                alignItems: 'center',
                gap: '4px',
                textAlign: 'center'
              }}
            >
              <span style={{ fontSize: '18px' }}>{option.flag}</span>
              <span>{option.name}</span>
            </button>
          ))}
        </div>
        
        {isListening && (
          <button
            onClick={stop}
            style={{
              padding: '8px 16px',
              border: 'none',
              backgroundColor: 'var(--ifm-color-danger)',
              color: 'var(--ifm-color-white)',
              borderRadius: '4px',
              cursor: 'pointer',
              width: '100%'
            }}
          >
            Stop Listening
          </button>
        )}
      </div>
      
      <div style={{ 
        padding: '16px', 
        border: '1px solid var(--ifm-color-emphasis-200)', 
        borderRadius: '6px',
        minHeight: '80px',
        backgroundColor: 'var(--ifm-background-surface-color)',
        color: 'var(--ifm-color-content)'
      }}>
        <strong>Result:</strong> {result || 'Click any button to start speaking...'}
      </div>
      
      <div style={{ 
        marginTop: '12px',
        padding: '12px',
        backgroundColor: 'var(--ifm-background-surface-color)',
        borderRadius: '4px',
        fontSize: '14px',
        color: 'var(--ifm-color-content-secondary)'
      }}>
        <strong>Tip:</strong> Continuous mode keeps listening until you stop it, 
        while single mode stops after detecting one phrase.
      </div>
    </div>
  );
}
```

## Notes

- **HTTPS Required**: This API requires HTTPS in production environments
- **User Interaction**: Some browsers may require user interaction before starting speech recognition
- **Permissions**: The browser will request microphone permissions when first used
- **Privacy**: Speech data may be sent to cloud services for processing
- **Accuracy**: Results may vary based on microphone quality, ambient noise, and accent

## Common Use Cases

- **Voice Commands**: Implement voice-controlled interfaces
- **Dictation**: Add speech-to-text functionality to forms
- **Accessibility**: Provide voice input for users with mobility impairments
- **Search**: Enable voice search functionality
- **Note Taking**: Create voice memo applications

---

## useTextDirection

URL: https://reactuse.com/browser/usetextdirection/
Category: browser
Description: useTextDirection is a React hook that reads and updates the dir attribute on an element — control ltr and rtl text direction for right-to-left layouts.
Import: `import { useTextDirection } from '@reactuses/core'`

# useTextDirection

change [dir](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir) of the element's text

`useTextDirection` reads and updates the [`dir`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir) attribute on a target element (default: `<html>`), controlling the text direction. It returns a tuple of the current direction value (`"ltr"`, `"rtl"`, or `"auto"`) and a setter function. This is essential for building internationalized applications that support right-to-left languages like Arabic, Hebrew, and Persian.

### When to Use

- Supporting bidirectional (BiDi) content in multilingual applications
- Building language switchers that toggle between LTR and RTL layouts
- Dynamically adjusting text direction based on user input or content language

### Notes

- **SSR-safe**: Returns the `initialValue` (default: `"ltr"`) and a no-op setter during server-side rendering. No `document` access occurs on the server.
- **Target selector**: By default, the hook sets `dir` on the `<html>` element. Use the `selector` option to target a specific element for scoped direction changes.
- **Related hooks**: See also `usePreferredLanguages` for detecting the user's language preferences, which can inform the text direction choice.

## Usage

```tsx live noInline
function Demo() {
  const [dir, setDir] = useTextDirection({
    selector: "#_useTextDirectionDemo",
  });

  const text = useMemo(
    () =>
      dir === "ltr"
        ? "This paragraph is in English and correctly goes left to right."
        : "This paragraph is in English but incorrectly goes right to left.",
    [dir],
  );

  const handleOnClick = () => {
    const value = dir === "rtl" ? "ltr" : "rtl";
    setDir(value);
  };

  return (
    <div id="_useTextDirectionDemo">
      <p>{text}</p>
      <button onClick={handleOnClick}>
        <span>{dir.toUpperCase()}</span>
      </button>
      <span>Click to change the direction</span>
    </div>
  );
};

render(<Demo/>);

```

---

## useTitle

URL: https://reactuse.com/browser/usetitle/
Category: browser
Description: useTitle is a React hook that sets document.title reactively — keep the browser tab title in sync with component state, with no head library needed.
Import: `import { useTitle } from '@reactuses/core'`

# useTitle

set document title.

`useTitle` is a side-effect hook that sets [`document.title`](https://developer.mozilla.org/en-US/docs/Web/API/Document/title) to the provided string. When the title value changes, the document title updates immediately. This is the simplest way to keep the browser tab title in sync with your component state, without needing a head management library.

### When to Use

- Setting the page title based on the current route or page content
- Displaying dynamic information in the tab (e.g., unread message count, current document name)
- Updating the title in response to user actions or data loading

### Notes

- **SSR-safe**: The hook is a no-op during server-side rendering. No `document.title` access occurs on the server. For SSR, set the title in your HTML template or use a head management solution.
- **Simple API**: This hook is a fire-and-forget side effect -- it takes a title string and sets it. For more complex scenarios (e.g., restoring the previous title on unmount), wrap it accordingly.
- **Related hooks**: See also `useFavicon` for dynamically changing the page's favicon icon.

## Usage

```tsx live
function Demo() {
  const [title, setTitle] = useState("title");

  useTitle(title);

  return (
    <div>
      <button onClick={() => setTitle("newTitle")}>Change Title</button>
    </div>
  );
};

```

---

## useWakeLock

URL: https://reactuse.com/browser/usewakelock/
Category: browser
Description: useWakeLock is a React hook for the Screen Wake Lock API — prevent the device screen from dimming or locking while your app is active.
Import: `import { useWakeLock } from '@reactuses/core'`

# useWakeLock

Reactive Screen Wake Lock API. Prevent the screen from dimming or locking.

`useWakeLock` wraps the [Screen Wake Lock API](https://developer.mozilla.org/en-US/docs/Web/API/Screen_Wake_Lock_API) to prevent the device screen from dimming or locking while your application is active. It returns an object with `isSupported`, `isActive` (whether a wake lock is currently held), `request` (acquires the lock when the page is visible, deferred if hidden), `forceRequest` (acquires regardless of visibility), and `release`. Callbacks for request, release, and error events can be provided via options.

### When to Use

- Keeping the screen awake during video playback, presentations, or recipe displays
- Preventing screen lock during long-running tasks like file uploads or real-time monitoring dashboards
- Building kiosk-mode applications that must keep the display on at all times

### Notes

- **SSR-safe**: Returns `isSupported: false` and `isActive: false` with no-op functions during server-side rendering. No `navigator.wakeLock` access occurs on the server.
- **Page visibility**: The standard `request` method defers wake lock acquisition until the page becomes visible. Use `forceRequest` to bypass this safety check when needed.
- **Auto-release**: Wake locks are automatically released by the browser when the page becomes hidden (tab switch, minimize). The hook re-acquires the lock when the page becomes visible again if it was active.

## Usage

```tsx live
function Demo() {
  const { isSupported, isActive, request, forceRequest, release } = useWakeLock({
    onRequest: () => console.log("Wake lock acquired"),
    onRelease: () => console.log("Wake lock released"),
    onError: (e) => console.error("Wake lock error:", e),
  });

  if (!isSupported) {
    return <div>Wake Lock API is not supported in your browser.</div>;
  }

  return (
    <div>
      <div style={{ marginBottom: 16 }}>
        Wake Lock: <b>{isActive ? "Active" : "Inactive"}</b>
      </div>
      <div>
        <button type="button" onClick={request}>
          Request
        </button>
        <button
          type="button"
          onClick={forceRequest}
          style={{ margin: "0 8px" }}
        >
          Force Request
        </button>
        <button type="button" onClick={release}>
          Release
        </button>
      </div>
    </div>
  );
};

```

---

## useWebNotification

URL: https://reactuse.com/browser/usewebnotification/
Category: browser
Description: useWebNotification is a React hook for the Notifications API — configure and display desktop notifications, with permission handling and event callbacks.
Import: `import { useWebNotification } from '@reactuses/core'`

# useWebNotification

The Web Notification interface of the Notifications API is used to configure and display desktop notifications to the user.

:::warning
Attention: For users on the Mac system, it is necessary for them to have enabled notifications for Chrome in their system settings. Without enabling notifications for Chrome in the system, even if the front-end page requests permission, notifications will not be displayed.
:::

`useWebNotification` wraps the [Notifications API](https://developer.mozilla.org/en-US/docs/Web/API/Notifications_API) to display native desktop/mobile notifications. It returns an object with `isSupported`, a `show` function (accepting a title and `NotificationOptions`), a `close` function, an `ensurePermissions` function, and a `permissionGranted` ref. Pass `true` to auto-request notification permission on mount.

### When to Use

- Alerting users about new messages, updates, or events even when the browser tab is not focused
- Sending reminders for scheduled tasks, timers, or calendar events
- Notifying users about completed background operations (uploads, downloads, builds)

### Notes

- **SSR-safe**: Returns `isSupported: false` and no-op functions during server-side rendering. No `Notification` constructor or permission requests occur on the server.
- **Permissions**: Notifications require explicit user permission. Use `ensurePermissions()` or pass `requestPermissions: true` to prompt the user. The `permissionGranted` ref tracks the current permission state.
- **Related hooks**: Use alongside `usePermission` with `"notifications"` to proactively check notification permission status without triggering a prompt.

## Usage

```tsx live
function Demo() {
  const { isSupported, show, close }
    = useWebNotification(true);
  return (
    <div>
      <p>Supported: {JSON.stringify(isSupported)}</p>
      {isSupported
        ? (
          <div>
            <button
              onClick={() => {
                show("Hello, world from ReactUse!");
              }}
            >
              Show Notification
            </button>
            <button onClick={close}>Close</button>
          </div>
          )
        : (
          <div>The Notification Web API is not supported in your browser.</div>
          )}
    </div>
  );
};

```

---

# Integrations hooks (1)

## useQRCode

URL: https://reactuse.com/integrations/useqrcode/
Category: integrations
Description: useQRCode is a React hook that generates a QR code data URL from a string — reactively regenerates on input change, with error state.
Import: `import { useQRCode } from '@reactuses/core'`

# useQRCode

The `useQRCode` hook is a hook that generates a QR code for a given string. It is useful for generating QR codes for things like URLs, email addresses, and more.

`useQRCode` takes a string and optional `QRCodeToDataURLOptions` and returns an object with `qrCode` (a data URL string for the generated QR code image) and `error` (any error that occurred during generation). The QR code is regenerated reactively whenever the input text changes. This hook depends on the [`qrcode`](https://www.npmjs.com/package/qrcode) library.

### When to Use

- Generating shareable QR codes for URLs, contact information, or deep links
- Building payment or authentication flows that display scannable QR codes
- Creating printable labels, tickets, or marketing materials with embedded QR codes

### Notes

- **External dependency**: Requires `qrcode@^1` to be installed separately (`npm i qrcode@^1`). The hook will not work without it.
- **Error handling**: If the input text is invalid or QR code generation fails, the `error` field will contain the error details and `qrCode` will be an empty string.
- **Customization**: Pass `QRCodeToDataURLOptions` to control output format (e.g., PNG or SVG data URL), error correction level, margin, color, and scale.

## Install

```shell
npm i qrcode@^1
```

## Usage

```tsx live
// import { useQRCode } from "@reactuses/core/useQRCode";

function Demo() {
  const [text, setText] = useState("https://reactuse.com/");
  const { qrCode, error } = useQRCode(text);

  return (
    <div>
      <input
        value={text}
        onChange={(e) => setText(e.target.value)}
        placeholder="Enter text to generate QR code"
      />
      <br />
      <br />
      {error && <div style={{ color: "red" }}>{error}</div>}
      {qrCode && <img src={qrCode} alt="QR Code" />}
    </div>
  );
};

```

---


Generated: 2026-09-04T06:26:05.186Z | Total hooks: 114