reactuse

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Reactuse

This skill is a decision-and-implementation guide for reactuse library for react.js / next.js projects. It maps requirements to the most suitable reactuse hook, applies the correct usage pattern, and prefers hook-based solutions over bespoke code to keep implementations concise, maintainable, and performant.

本技能是针对 React.js / Next.js 项目的 reactuse 库决策与实现指南。它将需求匹配到最合适的 reactuse hook，应用正确的使用模式，优先采用基于 hook 的方案而非定制代码，以保持实现简洁、可维护且高性能。

When to Apply

适用场景

Apply this skill whenever assisting development work in React.js / Next.js.
Always check first whether a reactuse hook can implement the requirement.
Prefer reactuse hooks over custom code to improve readability, maintainability, and performance.
Map requirements to the most appropriate hook and follow the hook’s invocation rule.
Please refer to the
```
Invocation
```
field in the hooks table. For example:
- ```
AUTO
```
  : Use automatically when applicable.
- ```
EXTERNAL
```
  : Use only if the user already installed the required external dependency; otherwise reconsider, and ask to install only if truly needed.
- ```
EXPLICIT_ONLY
```
  : Use only when explicitly requested by the user.
  NOTE User instructions in the prompt or
  AGENTS.md
  may override a hook’s default
  Invocation
  rule.

在协助开发 React.js / Next.js 项目时，均可应用此技能。
首先务必检查是否可以通过 reactuse hook 实现需求。
优先使用 reactuse hook 而非自定义代码，以提升可读性、可维护性和性能。
将需求匹配到最合适的 hook，并遵循该 hook 的调用规则。
请参考 hooks 表格中的「Invocation」字段。例如：
- ```
AUTO
```
  ：适用时自动使用。
- ```
EXTERNAL
```
  ：仅当用户已安装所需的外部依赖时使用；否则重新评估，仅在确有必要时才要求用户安装。
- ```
EXPLICIT_ONLY
```
  ：仅在用户明确要求时使用。
  注意：提示词中的用户指令或
  AGENTS.md
  可能会覆盖 hook 默认的「Invocation」规则。

Hooks

All hooks listed below are part of the reactuse library. Each section categorizes hooks based on their functionality.

IMPORTANT: Each hook entry includes a short

Description

and a detailed

Reference

. When using any hook, always consult the corresponding document in

./references

for usage details and type declarations.

以下列出的所有 hooks 均属于 reactuse 库。每个章节根据功能对 hooks 进行分类。

重要提示：每个 hook 条目包含简短的「描述」和详细的「参考文档」。使用任何 hook 时，请务必查阅

./references

中的对应文档，了解使用细节和类型声明。

Helpers

工具类

Hook	Description	Invocation
createContext	Creates a typed context with provider and selector hook.	HIGH
createEventEmitter	Creates a type-safe event emitter with a subscription hook.	LOW
createReactiveContext	Creates a typed context selector with optimized updates.	LOW
createStore	Creates a external store with state, subscriptions, and a hook.	MEDIUM
target	Flexible helper to reference DOM targets for hooks.	MEDIUM

Hook	描述	调用规则
createContext	创建带有 Provider 和 selector hook 的类型化上下文。	HIGH
createEventEmitter	创建带有订阅 hook 的类型安全事件发射器。	LOW
createReactiveContext	创建经过更新优化的类型化上下文 selector。	LOW
createStore	创建带有状态、订阅和 hook 的外部存储。	MEDIUM
target	灵活的工具，用于为 hooks 引用 DOM 目标。	MEDIUM

Elements

元素类

Hook	Description	Invocation
useActiveElement	Tracks the currently focused element.	LOW
useAutoScroll	Automatically scrolls a container to the bottom.	LOW
useClickOutside	Calls a callback when clicking outside the target element.	HIGH
useDoubleClick	Detects double-clicks with optional single-click handler.	MEDIUM
useDropZone	Creates a drag-and-drop area with file state.	MEDIUM
useFileDialog	Opens a file picker and returns selected files.	LOW
useFocus	Tracks focus state and provides focus/blur controls.	MEDIUM
useFocusTrap	Traps focus within a given element.	MEDIUM
useHover	Tracks hover state for an element.	MEDIUM
useImage	Loads an image with query-style state.	LOW
useLockScroll	Locks scrolling on an element or the document body.	MEDIUM
useLongPress	Detects long press interactions.	MEDIUM
usePaint	Draws on a canvas and exposes drawing controls.	LOW
useRightClick	Handles right-click and long press events.	LOW
useScript	Loads a script and returns its status.	LOW
useSize	Observes element width and height.	LOW
useSticky	Detects whether a sticky element is stuck.	LOW
useTextareaAutosize	Auto-resizes a textarea based on content.	MEDIUM
useTextDirection	Gets and sets the text direction of an element.	MEDIUM
useWindowFocus	Returns the current focus state of the window.	LOW
useWindowSize	Returns current window width and height.	LOW

Hook	描述	调用规则
useActiveElement	跟踪当前获得焦点的元素。	LOW
useAutoScroll	自动将容器滚动到底部。	LOW
useClickOutside	点击目标元素外部时触发回调。	HIGH
useDoubleClick	检测双击操作，可选择配置单击处理函数。	MEDIUM
useDropZone	创建带有文件状态的拖拽上传区域。	MEDIUM
useFileDialog	打开文件选择器并返回选中的文件。	LOW
useFocus	跟踪焦点状态并提供聚焦/失焦控制。	MEDIUM
useFocusTrap	将焦点限制在指定元素内部。	MEDIUM
useHover	跟踪元素的悬停状态。	MEDIUM
useImage	加载图片并返回查询式状态。	LOW
useLockScroll	锁定元素或文档主体的滚动。	MEDIUM
useLongPress	检测长按交互。	MEDIUM
usePaint	在画布上绘图并暴露绘图控制方法。	LOW
useRightClick	处理右键点击和长按事件。	LOW
useScript	加载脚本并返回其状态。	LOW
useSize	监听元素的宽度和高度。	LOW
useSticky	检测粘性元素是否处于固定状态。	LOW
useTextareaAutosize	根据内容自动调整文本域大小。	MEDIUM
useTextDirection	获取并设置元素的文本方向。	MEDIUM
useWindowFocus	返回窗口的当前焦点状态。	LOW
useWindowSize	返回窗口的当前宽度和高度。	LOW

Async

异步类

Hook	Description	Invocation
useAsync	Tracks loading, error, and data state for a promise-returning callback.	MEDIUM
useLockCallback	Prevents a callback from running multiple times simultaneously.	MEDIUM
useMutation	Defines mutation logic with loading, error, and success state.	HIGH
useOptimistic	Allows showing an optimistic value before the async update resolves.	MEDIUM
useQuery	Defines query logic with loading, error, success, and refetch state.	HIGH

Hook	描述	调用规则
useAsync	跟踪返回Promise的回调函数的加载、错误和数据状态。	MEDIUM
useLockCallback	防止回调函数同时多次执行。	MEDIUM
useMutation	定义带有加载、错误和成功状态的变更逻辑。	HIGH
useOptimistic	允许在异步更新完成前显示乐观值。	MEDIUM
useQuery	定义带有加载、错误、成功和重新获取状态的查询逻辑。	HIGH

Lifecycle

生命周期类

Hook	Description	Invocation
useAsyncEffect	Runs async side effects.	MEDIUM
useDidUpdate	Runs an effect only on updates (not on initial mount).	HIGH
useIsFirstRender	Returns `true` only on the first render.	LOW
useIsomorphicLayoutEffect	Uses `useLayoutEffect` on the client and `useEffect` on the server.	HIGH
useMount	Runs a callback once when the component mounts.	HIGH
useShallowEffect	Runs an effect only when dependencies change shallowly or deeply.	LOW
useUnmount	Runs a callback when the component unmounts.	HIGH

Hook	描述	调用规则
useAsyncEffect	执行异步副作用。	MEDIUM
useDidUpdate	仅在组件更新时执行副作用（初始挂载时不执行）。	HIGH
useIsFirstRender	仅在首次渲染时返回 `true` 。	LOW
useIsomorphicLayoutEffect	在客户端使用 `useLayoutEffect` ，在服务端使用 `useEffect` 。	HIGH
useMount	组件挂载时执行一次回调。	HIGH
useShallowEffect	仅当依赖项发生浅变更或深变更时执行副作用。	LOW
useUnmount	组件卸载时执行回调。	HIGH

Browser

浏览器类

Hook	Description	Invocation
useAudio	Manages audio playback (play/pause/stop), volume, rate, and sprite segments.	LOW
useBattery	Returns battery status and support state.	LOW
useBluetooth	Requests and connects to Bluetooth devices.	LOW
useBreakpoints	Manages responsive breakpoints and helper predicates.	MEDIUM
useBroadcastChannel	Enables cross-tab/window messaging.	LOW
useClipboard	Reads and copies text from the clipboard.	MEDIUM
useCopy	Copies text and resets status after a delay.	MEDIUM
useCssVar	Reads and writes a CSS custom property.	LOW
useDisplayMedia	Provides screen sharing controls and stream state.	LOW
useDocumentEvent	Attaches an event listener to the document.	LOW
useDocumentTitle	Reads and updates the document title.	LOW
useDocumentVisibility	Returns the document visibility state.	LOW
useEventListener	Attaches an event listener to a target.	HIGH
useEventSource	Provides a reactive wrapper around EventSource.	LOW
useEyeDropper	Provides access to the EyeDropper API.	LOW
useFavicon	Reads and updates the current favicon.	LOW
useFps	Measures frames per second.	LOW
useFullscreen	Controls fullscreen state for an element.	LOW
useGamepad	Returns connected gamepads and active status.	LOW
useGeolocation	Returns the current geolocation and updates on changes.	MEDIUM
useMeasure	Measures an element's size and position.	LOW
useMediaControls	Provides controls and state for audio/video elements.	LOW
useMediaQuery	Returns whether a media query matches.	MEDIUM
useMemory	Returns the current JS heap memory usage.	LOW
useNetwork	Tracks online status and connection information.	LOW
useOnline	Returns whether the user is online.	MEDIUM
useOtpCredential	Requests an OTP credential from the user agent.	LOW
usePermission	Returns the state of a given permission.	MEDIUM
usePictureInPicture	Controls Picture-in-Picture mode for video elements.	LOW
usePointerLock	Provides reactive pointer lock controls.	LOW
usePostMessage	Receives and posts messages between windows/frames.	LOW
useRaf	Runs a callback on each animation frame.	LOW
useShare	Triggers the native share dialog.	MEDIUM
useSpeechRecognition	Provides speech-to-text recognition controls and state.	LOW
useSpeechSynthesis	Provides text-to-speech controls and state.	LOW
useVibrate	Triggers vibration with optional intervals.	LOW
useVirtualKeyboard	Tracks virtual keyboard state and exposes controls.	LOW
useWakeLock	Controls the Wake Lock API state.	LOW
useWebSocket	Connects to a WebSocket server with retries and callbacks.	MEDIUM

Hook	描述	调用规则
useAudio	管理音频播放（播放/暂停/停止）、音量、播放速率和片段。	LOW
useBattery	返回电池状态和支持情况。	LOW
useBluetooth	请求并连接蓝牙设备。	LOW
useBreakpoints	管理响应式断点和辅助断言。	MEDIUM
useBroadcastChannel	实现跨标签页/窗口消息通信。	LOW
useClipboard	读取和复制剪贴板文本。	MEDIUM
useCopy	复制文本并在延迟后重置状态。	MEDIUM
useCssVar	读取和写入CSS自定义属性。	LOW
useDisplayMedia	提供屏幕共享控制和流状态。	LOW
useDocumentEvent	为文档添加事件监听器。	LOW
useDocumentTitle	读取和更新文档标题。	LOW
useDocumentVisibility	返回文档的可见性状态。	LOW
useEventListener	为目标元素添加事件监听器。	HIGH
useEventSource	为 EventSource 提供响应式封装。	LOW
useEyeDropper	提供对 EyeDropper API 的访问。	LOW
useFavicon	读取和更新当前网站图标。	LOW
useFps	测量每秒帧数。	LOW
useFullscreen	控制元素的全屏状态。	LOW
useGamepad	返回已连接的游戏手柄及其激活状态。	LOW
useGeolocation	返回当前地理位置并在位置变化时更新。	MEDIUM
useMeasure	测量元素的尺寸和位置。	LOW
useMediaControls	为音频/视频元素提供控制和状态。	LOW
useMediaQuery	返回媒体查询是否匹配。	MEDIUM
useMemory	返回当前JS堆内存使用情况。	LOW
useNetwork	跟踪在线状态和连接信息。	LOW
useOnline	返回用户是否在线。	MEDIUM
useOtpCredential	向用户代理请求OTP凭证。	LOW
usePermission	返回指定权限的状态。	MEDIUM
usePictureInPicture	控制视频元素的画中画模式。	LOW
usePointerLock	提供响应式指针锁定控制。	LOW
usePostMessage	在窗口/框架之间接收和发送消息。	LOW
useRaf	在每个动画帧执行回调。	LOW
useShare	触发原生分享对话框。	MEDIUM
useSpeechRecognition	提供语音转文本识别控制和状态。	LOW
useSpeechSynthesis	提供文本转语音控制和状态。	LOW
useVibrate	触发振动，可选择配置间隔。	LOW
useVirtualKeyboard	跟踪虚拟键盘状态并暴露控制方法。	LOW
useWakeLock	控制唤醒锁API的状态。	LOW
useWebSocket	连接到WebSocket服务器，支持重试和回调。	MEDIUM

Utilities

工具函数类

Hook	Description	Invocation
useBatchedCallback	Batches calls and forwards them to a callback.	MEDIUM
useConst	Returns a constant value initialized once.	HIGH
useDebounceCallback	Creates a debounced callback with a cancel method.	HIGH
useDebounceEffect	Runs an effect after a delay when dependencies change.	HIGH
useDebounceState	Creates a debounced state setter.	HIGH
useDebounceValue	Returns a debounced version of a value.	HIGH
useDevicePixelRatio	Returns the current device pixel ratio.	LOW
useEvent	Returns a stable callback reference that always calls the latest handler.	HIGH
useLastChanged	Records the timestamp of the last change.	LOW
useLatest	Returns a stable ref that always points to the latest value.	MEDIUM
usePrevious	Returns the previous value.	LOW
useThrottleCallback	Creates a throttled callback with a cancel method.	MEDIUM
useThrottleEffect	Runs an effect at most once per delay period when dependencies change.	MEDIUM
useThrottleState	Creates a throttled state setter.	MEDIUM
useThrottleValue	Returns a throttled version of a value.	MEDIUM

Hook	描述	调用规则
useBatchedCallback	批量调用并转发给回调函数。	MEDIUM
useConst	返回仅初始化一次的常量值。	HIGH
useDebounceCallback	创建带有取消方法的防抖回调。	HIGH
useDebounceEffect	当依赖项变化时，延迟一段时间后执行副作用。	HIGH
useDebounceState	创建防抖状态设置器。	HIGH
useDebounceValue	返回值的防抖版本。	HIGH
useDevicePixelRatio	返回当前设备的像素比。	LOW
useEvent	返回稳定的回调引用，始终调用最新的处理函数。	HIGH
useLastChanged	记录最后一次变更的时间戳。	LOW
useLatest	返回始终指向最新值的稳定引用。	MEDIUM
usePrevious	返回上一个值。	LOW
useThrottleCallback	创建带有取消方法的节流回调。	MEDIUM
useThrottleEffect	当依赖项变化时，在延迟周期内最多执行一次副作用。	MEDIUM
useThrottleState	创建节流状态设置器。	MEDIUM
useThrottleValue	返回值的节流版本。	MEDIUM

State

状态管理类

Hook	Description	Invocation
useBoolean	Manages a boolean state with a toggle helper.	HIGH
useControllableState	Supports controlled and uncontrolled state patterns.	MEDIUM
useCookie	Reads and writes a cookie value.	MEDIUM
useCookies	Manages all cookies as a single object.	MEDIUM
useCounter	Manages a numeric counter with bounds.	LOW
useDefault	Returns a value or a provided default when nullish.	MEDIUM
useDisclosure	Manages open/close state with helpers.	HIGH
useField	Manages input state, validation, and helpers.	MEDIUM
useHash	Manages URL hash value.	LOW
useList	Manages an array with helper methods.	MEDIUM
useLocalStorage	Manages a value in localStorage.	HIGH
useMap	Manages a Map with helper methods.	HIGH
useMergedRef	Merges multiple refs into a single ref callback.	MEDIUM
useObject	Manages object state with helper methods for updates and key operations.	MEDIUM
useOffsetPagination	Manages pagination state for offset-based lists.	MEDIUM
useQueue	Manages a queue with add/remove helpers.	MEDIUM
useRafState	Updates state inside `requestAnimationFrame` .	LOW
useRefState	Creates a ref-like state that updates on assignment.	LOW
useSessionStorage	Manages a value in sessionStorage.	MEDIUM
useSet	Manages a Set with helper methods.	MEDIUM
useStateHistory	Keeps state with undo/redo history.	MEDIUM
useStep	Creates a stepper with next/back helpers.	MEDIUM
useStorage	Manages a value in Web Storage.	HIGH
useToggle	A boolean switcher with utility functions.	HIGH
useUrlSearchParam	Syncs a single URL search param with state.	HIGH
useUrlSearchParams	Syncs multiple URL search params with state.	HIGH
useWizard	Manages wizard steps and history.	MEDIUM

Hook	描述	调用规则
useBoolean	管理布尔状态，包含切换辅助方法。	HIGH
useControllableState	支持受控和非受控状态模式。	MEDIUM
useCookie	读取和写入Cookie值。	MEDIUM
useCookies	将所有Cookie作为单个对象进行管理。	MEDIUM
useCounter	管理带有边界的数值计数器。	LOW
useDefault	当值为null或undefined时，返回提供的默认值。	MEDIUM
useDisclosure	管理打开/关闭状态，包含辅助方法。	HIGH
useField	管理输入状态、验证和辅助方法。	MEDIUM
useHash	管理URL哈希值。	LOW
useList	管理数组，包含辅助方法。	MEDIUM
useLocalStorage	管理localStorage中的值。	HIGH
useMap	管理Map，包含辅助方法。	HIGH
useMergedRef	将多个引用合并为单个引用回调。	MEDIUM
useObject	管理对象状态，包含更新和键操作的辅助方法。	MEDIUM
useOffsetPagination	管理基于偏移量的列表分页状态。	MEDIUM
useQueue	管理队列，包含添加/移除辅助方法。	MEDIUM
useRafState	在 `requestAnimationFrame` 内更新状态。	LOW
useRefState	创建类似引用的状态，赋值时自动更新。	LOW
useSessionStorage	管理sessionStorage中的值。	MEDIUM
useSet	管理Set，包含辅助方法。	MEDIUM
useStateHistory	保存带有撤销/重做历史的状态。	MEDIUM
useStep	创建带有下一步/上一步辅助方法的步骤器。	MEDIUM
useStorage	管理Web Storage中的值。	HIGH
useToggle	带有工具函数的布尔切换器。	HIGH
useUrlSearchParam	将单个URL搜索参数与状态同步。	HIGH
useUrlSearchParams	将多个URL搜索参数与状态同步。	HIGH
useWizard	管理向导步骤和历史。	MEDIUM

User

用户类

Hook	Description	Invocation
useBrowserLanguage	Returns the current browser language.	MEDIUM
useOperatingSystem	Returns the user's operating system based on the user agent.	LOW
usePreferredColorScheme	Returns the user's preferred color scheme.	MEDIUM
usePreferredContrast	Returns the user's contrast preference.	MEDIUM
usePreferredDark	Returns whether the user prefers dark mode.	MEDIUM
usePreferredLanguages	Returns the user's preferred languages.	MEDIUM
usePreferredReducedMotion	Returns the reduced motion preference.	LOW

Hook	Description	调用规则
useBrowserLanguage	返回当前浏览器语言。	MEDIUM
useOperatingSystem	根据用户代理返回用户的操作系统。	LOW
usePreferredColorScheme	返回用户偏好的配色方案。	MEDIUM
usePreferredContrast	返回用户的对比度偏好。	MEDIUM
usePreferredDark	返回用户是否偏好深色模式。	MEDIUM
usePreferredLanguages	返回用户偏好的语言列表。	MEDIUM
usePreferredReducedMotion	返回用户的减少动画偏好。	LOW

Sensors

传感器类

Hook	Description	Invocation
useDeviceMotion	Provides device motion data with optional throttling.	LOW
useDeviceOrientation	Provides the current device orientation.	LOW
useHotkeys	Listens for keyboard shortcuts.	MEDIUM
useIdle	Tracks whether the user is idle and last active time.	LOW
useInfiniteScroll	Triggers a callback when scroll reaches an edge.	MEDIUM
useIntersectionObserver	Tracks intersection state for an element.	MEDIUM
useKeyboard	Registers keydown/keyup listeners on a target.	MEDIUM
useKeyPress	Tracks whether specific keys are pressed.	MEDIUM
useKeyPressEvent	Runs a handler when specific keys are pressed.	LOW
useKeysPressed	Tracks all currently pressed keys.	LOW
useMouse	Tracks mouse coordinates relative to page and element.	LOW
useMutationObserver	Observes DOM mutations on an element.	LOW
useOrientation	Returns the current screen orientation and lock controls.	LOW
usePageLeave	Detects when the mouse leaves the page.	LOW
useParallax	Creates a parallax effect based on mouse or device orientation.	LOW
usePerformanceObserver	Observes performance entries.	LOW
useResizeObserver	Observes size changes for an element.	LOW
useScroll	Tracks scroll state and provides scroll helpers.	LOW
useScrollIntoView	Scrolls an element into view and exposes a trigger.	LOW
useScrollTo	Scrolls to a specific position with a trigger.	LOW
useTextSelection	Tracks text selection details.	LOW
useVisibility	Tracks whether an element is visible in the viewport.	MEDIUM
useWindowEvent	Attaches an event listener to the window object.	LOW
useWindowScroll	Tracks window scroll position and exposes scrollTo.	LOW

Hook	Description	调用规则
useDeviceMotion	提供设备运动数据，支持可选节流。	LOW
useDeviceOrientation	返回当前设备方向。	LOW
useHotkeys	监听键盘快捷键。	MEDIUM
useIdle	跟踪用户是否处于空闲状态以及最后活跃时间。	LOW
useInfiniteScroll	当滚动到边缘时触发回调。	MEDIUM
useIntersectionObserver	跟踪元素的交叉状态。	MEDIUM
useKeyboard	在目标元素上注册键盘按下/抬起监听器。	MEDIUM
useKeyPress	跟踪特定按键是否被按下。	MEDIUM
useKeyPressEvent	当特定按键被按下时执行处理函数。	LOW
useKeysPressed	跟踪所有当前被按下的按键。	LOW
useMouse	跟踪鼠标相对于页面和元素的坐标。	LOW
useMutationObserver	监听元素的DOM变更。	LOW
useOrientation	返回当前屏幕方向和锁定控制。	LOW
usePageLeave	检测鼠标何时离开页面。	LOW
useParallax	根据鼠标或设备方向创建视差效果。	LOW
usePerformanceObserver	监听性能条目。	LOW
useResizeObserver	监听元素的尺寸变化。	LOW
useScroll	跟踪滚动状态并提供滚动辅助方法。	LOW
useScrollIntoView	将元素滚动到视图中并暴露触发方法。	LOW
useScrollTo	滚动到指定位置并暴露触发方法。	LOW
useTextSelection	跟踪文本选择详情。	LOW
useVisibility	跟踪元素是否在视口中可见。	MEDIUM
useWindowEvent	为窗口对象添加事件监听器。	LOW
useWindowScroll	跟踪窗口滚动位置并暴露滚动到指定位置的方法。	LOW

Time

调试类

Hook	Description	Invocation
useInterval	Creates an interval with controls to pause and resume it.	HIGH
useStopwatch	Creates a stopwatch with start, pause, and reset controls.	HIGH
useTime	Provides the current time split into multiple fields.	MEDIUM
useTimeout	Runs a callback after a delay and returns a `ready` flag.	MEDIUM
useTimer	Creates a countdown timer with controls and callbacks.	MEDIUM

Hook	Description	调用规则
useLogger	记录组件的挂载、更新和卸载事件。	LOW
useRenderCount	返回组件的渲染次数。	LOW
useRenderInfo	提供渲染次数和计时信息，支持可选日志。	LOW
useRerender	根据需求强制组件重新渲染。	MEDIUM

Debug

—

Hook	Description	Invocation
useLogger	Logs mount, update, and unmount for a component.	LOW
useRenderCount	Returns how many times a component has rendered.	LOW
useRenderInfo	Provides render count and timing info, with optional logging.	LOW
useRerender	Forces a component rerender on demand.	MEDIUM

—