SKILL.md
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.
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
Invocationfield 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. - EXPLICITONLY: 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.
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.
Blocked upstream category: Reactuse also exports Humor hooks (useFul, useLess, useOnce) in recent releases. This skill intentionally does not support or recommend them because upstream marks them as jokes or non-production utilities.
Helpers
| Hook | Description | Invocation |
|---|---|---|
| cn | Normalizes conditional class names for React className. |
HIGH |
| createContext | Creates a typed context with provider and selector hook. | HIGH |
| createContextHook | Scopes one hook result to a React subtree. | LOW |
| createEventEmitter | Creates a type-safe event emitter with a subscription hook. | LOW |
| createReactiveContext | Creates a typed context selector with optimized updates. | LOW |
| createSharedHook | Shares one hook instance across consumers. | LOW |
| createStore | Creates a external store with state, subscriptions, and a hook. | MEDIUM |
| makeDestructurable | Supports object and tuple consumption from one value. | LOW |
| target | Wraps DOM targets in the shape Reactuse hooks expect. | 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 |
| useContextMenu | Converts secondary-click and long-press gestures to menu state. | LOW |
| useDoubleClick | Detects double-clicks with optional single-click handler. | MEDIUM |
| useDraggable | Converts pointer movement into drag position state. | LOW |
| 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 in the browser and returns image-specific loading 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 |
| 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 |
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 | Wraps abortable async reads in query state and refresh controls. | 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 |
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 |
| useBrowserLocation | Returns reactive location state and history navigation controls. | MEDIUM |
| 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 |
| useDeviceList | Groups available media input and output devices for pickers. | MEDIUM |
| useDisplayMedia | Connects a video element to a screen-capture stream. | 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 |
| useFileSystemAccess | Reads and writes local files via the File System Access API. | LOW |
| useFps | Measures frames per second. | LOW |
| useFullscreen | Controls fullscreen state for an element. | LOW |
| useGamepad | Returns connected gamepads and active status. | LOW |
| useGeolocation | Keeps the latest browser geolocation reading in React state. | MEDIUM |
| useMeasure | Measures an element's size and position. | LOW |
| useMediaControls | Provides controls and state for audio/video elements. | LOW |
| useMediaStream | Connects camera or microphone capture to a media element. | MEDIUM |
| 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 |
| useNotification | Manages notification permission and the latest notification. | MEDIUM |
| useOnline | Returns whether the user is online. | MEDIUM |
| useObjectUrl | Creates and revokes an object URL | LOW |
| useOtpCredential | Requests an OTP credential from the user agent. | LOW |
| usePermission | Tracks browser permission query state. | 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 | Turns browser speech recognition into transcript state. | LOW |
| useSpeechSynthesis | Turns text into spoken output with playback 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 | Keeps a component connected to a WebSocket endpoint. | MEDIUM |
| useWebWorker | Connects a Web Worker to React data and lifecycle state. | LOW |
| useWebWorkerCallback | Runs a self-contained function off the main thread. | LOW |
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 |
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 |
| useCycleList | Models ordered choices as a current value plus navigation helpers. | MEDIUM |
| useDefault | Returns a value or a provided default when nullish. | MEDIUM |
| useDisclosure | Manages open/close state with helpers. | HIGH |
| useField | Connects one uncontrolled field to validation and helper state. | MEDIUM |
| useForm | Coordinates typed uncontrolled form values and validation. | 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 |
| useMask | Keeps masked, raw, display, and cursor state aligned. | MEDIUM |
| 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 |
| useValidatedState | Keeps a value together with validity and last valid value. | MEDIUM |
| useWizard | Manages wizard steps and history. | 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 |
Sensors
| Hook | Description | Invocation |
|---|---|---|
| useDeviceMotion | Provides device motion data via snapshot and watch(). |
LOW |
| useDeviceOrientation | Provides the current device orientation. | LOW |
| useHotkeys | Scopes keyboard shortcuts to a target or returned ref. | MEDIUM |
| useIdle | Tracks whether the user is idle and last active time. | LOW |
| useInfiniteScroll | Triggers guarded loading near a scroll 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 |
| 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 |
| useSwipe | Converts touch and pointer movement into swipe state. | 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 |
Time
| Hook | Description | Invocation |
|---|---|---|
| useInterval | Creates an interval with controls to pause and resume it. | HIGH |
| useProgress | Creates progress state with auto-incrementing controls. | MEDIUM |
| 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 |
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 |