# @shopify/react-hooks
> A collection of primitive React hooks
Latest version **4.1.2** (published 2024-08-01) · MIT license · 0 weekly downloads
> **Deprecated.** This package is deprecated.
## Install
```sh
npm install @shopify/react-hooks
pnpm add @shopify/react-hooks
yarn add @shopify/react-hooks
bun add @shopify/react-hooks
```
## Health
**Score 10/100 (F)** — status: deprecated.
Negative: deprecated.
## Facts
| | |
|---|---|
| Version | 4.1.2 |
| Published | 2024-08-01 |
| First published | 2019-04-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18.12.0 |
| Dependencies | 0 |
| Unpacked size | 37.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1681 |
| Author | Shopify Inc. |
| Maintainers | jaimie.rockburn, blittle, shopify-admin, maryharte, crisfmb, pmoloney89, netlohan, st999999, justin-irl, megswim, wcandillon, nathanpjf, shopify-dep, goodforonefare, lemonmade, vsumner, wizardlyhel, antoine.grant, tsov, andyw8-shopify, henrytao, hannachen, vividviolet, bpscott |
## Links
- npm: https://www.npmjs.com/package/@shopify/react-hooks
- Repository: https://github.com/Shopify/quilt
- Homepage: https://github.com/Shopify/quilt/blob/main/packages/react-hooks/README.md
- Issues: https://github.com/Shopify/quilt/issues
- npm.io page: https://npm.io/package/@shopify/react-hooks
## Recent versions
- 4.1.2 (latest) — 2024-08-01
- 0.0.0-snapshot-20240620045713 (snapshot) — 2024-06-20
- 3.0.1-react-18-react-testing-beta.10.0 (next) — 2022-06-08
- 2.0.1-address-mocks-minified-beta.0 (beta) — 2021-06-02
- 4.1.1 — 2024-07-18
- 4.1.0 — 2024-07-17
- 4.0.0 — 2024-07-16
- 3.2.0 — 2024-06-10
- 3.1.1 — 2024-04-29
- 3.1.0 — 2024-03-18
- 0.0.0-snapshot-20240308174203 — 2024-03-08
- 3.0.5 — 2023-04-28
- 0.0.0-snapshot-20230428103020 — 2023-04-28
- 0.0.0-snapshot-20230426140136 — 2023-04-26
- 0.0.0-snapshot-20230425154318 — 2023-04-25
- … 83 more at https://npm.io/package/@shopify/react-hooks/versions
## README
# `@shopify/react-hooks`
[](https://github.com/Shopify/quilt/actions?query=workflow%3ANode-CI)
[](https://github.com/Shopify/quilt/actions?query=workflow%3ARuby-CI)
[](LICENSE.md) [](https://badge.fury.io/js/%40shopify%2Freact-hooks.svg) [](https://img.shields.io/bundlephobia/minzip/@shopify/react-hooks.svg)
A collection of primitive React hooks.
## Installation
```bash
yarn add @shopify/react-hooks
```
## List of hooks
- [useDebouncedValue()](#usedebouncedvalue)
- [useDelayedCallback()](#usedelayedcallback)
- [useForceUpdate()](#useforceupdate)
- [useInterval()](#useinterval)
- [useIsomorphicLayoutEffect()](#useisomorphiclayouteffect)
- [useLazyRef()](#uselazyref)
- [useMedia() & useMediaLayout()](#usemedia--usemedialayout)
- [useMountedRef()](#usemountedref)
- [useOnValueChange()](#useonvaluechange)
- [usePrevious()](#useprevious)
- [useTimeout()](#usetimeout)
- [useToggle()](#usetoggle)
## Usage
### `useDebouncedValue()`
This hook provides a debounced value.
```tsx
function MyComponent() {
const [searchValue, setSearchValue] = useState('');
const debouncedSearch = useDebouncedValue(searchValue);
const {data, loading} = useQuery(SomeQuery, {
variables: {
query: debouncedSearch,
},
});
function handleSearchTextChange(evt: React.KeyboardEvent) {
setSearchValue(evt.currentTarget.value);
}
return ;
}
```
### `useDelayedCallback()`
This hook provides a delayed callback function. It takes a callback and a delay in milliseconds. This might be useful when you want to invoke a callback after a certain delay.
```tsx
function MyComponent() {
const delay = 300;
const callback = () => {
console.log(
`Oh, you KNOW I'm calling that callback after ${delay} milliseconds!`,
);
};
const callbackWithDelay = useDelayedCallback(callback, delay);
const onClick = () => {
callbackWithDelay();
};
return ;
}
```
### `useForceUpdate()`
This hook provides a `forceUpdate` function which will force a component to re-render. This might be useful when you want to re-render after a mutable object gets updated.
```tsx
const mutableObject = {foo: 'bar'};
export default function ResourceListFiltersExample() {
const forceUpdate = useForceUpdate();
const onClick = () => {
mutableObject.foo = 'bar' + new Date().getTime();
forceUpdate();
};
return ;
}
```
### `useOnValueChange()`
This hook tracks a given value and invokes a callback when it has changed.
```tsx
function MyComponent({foo}: {foo: string}) {
useOnValueChange(foo, (newValue, oldValue) => {
console.log(`foo changed from ${oldValue} to ${newValue}`);
});
return null;
}
```
### `useTimeout()`
This hook provides a declarative version of [`setTimeout()`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout). The first argument is a callback that will be invoked after the given delay (number of milliseconds) as the second argument. Optionally, the timeout can be disabled by passing `null` as the delay.
```tsx
function MyComponent() {
const [status, setStatus] = React.useState('Pending');
const pending = status === 'Pending';
const buttonLabel = pending ? 'Cancel' : 'Reset';
const handleClick = () => setStatus(pending ? 'Cancelled' : 'Pending');
const delay = pending ? 1000 : null;
useTimeout(() => setStatus('Fired'), delay);
return (
{status}
);
}
```
### `useInterval()`
This hook provides a declarative version of [`setInterval`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setInterval). The first argument is a callback that will be invoked successively after the given delay (number of milliseconds) as the second argument. Optionally, the interval can be disabled by passing `null` as the delay.
```tsx
function MyComponent() {
const [counter, setCounter] = React.useState(0);
const [enabled, setEnabled] = React.useState(true);
const delay = enabled ? 1000 : null;
const label = enabled ? 'Disable' : 'Enable';
const toggle = () => setEnabled(!enabled);
useInterval(() => setCounter(counter + 1), delay);
return (
{counter}
);
}
```
This is a TypeScript implementation of @gaeron's `useInterval` hook from the [Overreacted blog post](https://overreacted.io/making-setinterval-declarative-with-react-hooks/#just-show-me-the-code).
### `useIsomorphicLayoutEffect()`
This hook is a drop-in replacement for `useLayoutEffect` that can be used safely in a server-side rendered app. It resolves to `useEffect` on the server and `useLayoutEffect` on the client (since `useLayoutEffect` cannot be used in a server-side environment).
Refer to the [`useLayoutEffect` documentation to learn more](https://reactjs.org/docs/hooks-reference.html#uselayouteffect).
### `useLazyRef()`
This hook creates a ref object like React’s `useRef`, but instead of providing it the value directly, you provide a function that returns the value. The first time the hook is run, it will call the function and use the returned value as the initial `ref.current` value. Afterwards, the function is never invoked. You can use this for creating refs to values that are expensive to initialize.
```tsx
function MyComponent() {
const ref = useLazyRef(() => someExpensiveOperation());
React.useEffect(() => {
console.log('Initialized expensive ref', ref.current);
});
return null;
}
```
### `useMedia()` & `useMediaLayout()`
This hook listens to a [MediaQueryList](https://developer.mozilla.org/en-US/docs/Web/API/MediaQueryList) created via [matchMedia](https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia) and returns true or false if it matches the media query string.
`useMediaLayout` is similar to `useMedia` but it uses `useLayoutEffect` internally to re-render synchronously.
```tsx
function MyComponent() {
const isSmallScreen = useMedia('(max-width: 640px)');
return (
{isSmallScreen ? 'This is a small screen' : 'This is not a small screen'}
);
}
```
### `useMountedRef()`
This hook keeps track of a component's mounted / un-mounted status and returns a ref object like React’s [`useRef`](https://reactjs.org/docs/hooks-reference.html#useref) with a boolean value representing said status. This is often used when a component contains an async task that sets state after the task has resolved.
```tsx
import React from 'react';
import {useMountedRef} from '@shopify/react-hooks';
function MockComponent() {
const [result, setResult] = React.useState();
const mounted = useMountedRef();
async function handleOnClick() {
const result = await fetchData();
if (mounted.current) {
setData(result);
}
}
return (
);
}
```
### `usePrevious()`
This hook stores the previous value of a given variable.
```tsx
function Score({value}) {
const previousValue = usePrevious(value);
const newRecord = value > previousValue ?
We have a new record!
: null;
return (
<>
Current score: {value}
{newRecord}
);
}
```
### `useToggle()`
This hook provides an object that contains a boolean state value and a set of memoised callbacks to toggle it, force it to true, and force it to false. It accepts one argument that is the initial value of the state or an initializer function returning the initial value. This is useful for toggling the active state of modals and popovers.
```tsx
function MyComponent() {
const {
value: isActive,
toggle: toggleIsActive,
setTrue: setIsActiveTrue,
setFalse: setIsActiveFalse,
} = useToggle(false);
const activeText = isActive ? 'true' : 'false';
return (
<>
Value: {activeText}
);
}
```
---
_Source: https://npm.io/package/@shopify/react-hooks · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._