shadcn-hooks

shadcn-hooks

此技能是 React 项目中使用 shadcn-hooks 的决策与实现指南。它将需求映射到最合适的 Hook，应用正确的使用模式，并优先采用基于 Hook 的解决方案，而非定制代码，以保持实现简洁、易于维护且高效。

适用场景

• 在协助用户进行 React / Next.js 开发时，应用此技能。
• 务必先检查 shadcn-hooks 中的函数是否能满足需求。
• 优先使用 shadcn-hooks，而非自定义代码，以提升可读性、可维护性和性能。
• 将需求映射到最合适的 Hook，并遵循该 Hook 的调用规则。
• 请参阅下方函数表中的 Invocation 字段。例如：
  • AUTO：适用时自动使用。
  • EXTERNAL：仅当用户已安装所需的外部依赖时使用；否则重新考虑，并且只有在确实需要时才询问用户是否安装。

安装

优先使用 shadcn CLI——它只会将你需要的 Hook 复制到项目中（无需额外的运行时依赖，且利于摇树优化）：

# Install a single hook (recommended)
npx shadcn@latest add @shadcnhooks/use-boolean

# Install multiple hooks at once
npx shadcn@latest add @shadcnhooks/use-boolean @shadcnhooks/use-mount @shadcnhooks/use-debounce

或者，安装完整的 npm 包（包含所有 Hook）：

npm install shadcn-hooks

使用 shadcn CLI 时，从本地路径导入（例如，import { useBoolean } from "@/hooks/use-boolean"）。 使用 npm 包时，从 "shadcn-hooks" 导入（例如，import { useBoolean } from "shadcn-hooks"）。

函数

下方列出的所有函数都属于 shadcn-hooks。每个部分按函数功能分类。

重要：每个函数条目都包含简短的 Description 和详细的 Reference。使用任何函数时，请务必查阅 ./references 中对应的文档，了解用法和类型声明。

状态

Function	Description	Invocation
useBoolean	布尔状态，提供 set、setTrue、setFalse、toggle 辅助函数	AUTO
useControllableValue	同时支持受控和非受控组件模式	AUTO
useCounter	计数器，提供 inc、dec、set、reset 辅助函数	AUTO
useDebounce	防抖的响应式值	AUTO
useResetState	状态附带 reset 函数，可恢复初始值	AUTO
useThrottle	节流的响应式值	AUTO
useToggle	在两个值之间切换，并提供实用操作	AUTO

高级

函数	描述	调用方式
useCreation	使用深度依赖比较的记忆化工厂函数	AUTO
useCustomCompareEffect	使用自定义依赖比较器的 useEffect	AUTO
useLatest	始终保存最新值的 Ref	AUTO
useLockFn	防止异步函数并发执行	AUTO
useMemoizedFn	引用稳定、标识永不改变的函数	AUTO
usePrevious	返回状态的上一个值	AUTO

生命周期

函数	描述	调用方式
useDebounceEffect	防抖的 useEffect	AUTO
useDebounceFn	带有 run、cancel、flush 控制项的防抖函数	AUTO
useDeepCompareEffect	使用深度依赖比较的 useEffect	AUTO
useDeepCompareLayoutEffect	使用深度依赖比较的 useLayoutEffect	AUTO
useEffectEvent	React 19 的 useEffectEvent 补充实现	AUTO
useEffectWithTarget	支持将目标 DOM 元素作为依赖项的 useEffect	AUTO
useInterval	自动清理的间隔计时器	AUTO
useIsHydrated	客户端水合完成后返回 true	AUTO
useIsomorphicLayoutEffect	在客户端使用 useLayoutEffect，在服务端使用 useEffect	AUTO
useMount	仅在组件挂载时运行回调	AUTO
useThrottleEffect	节流的 useEffect	AUTO
useThrottleFn	带有 run、cancel、flush 控制项的节流函数	AUTO
useTimeout	自动清理的超时计时器	AUTO
useUnmount	在组件卸载时运行清理操作	AUTO
useUpdate	返回一个强制组件重新渲染的函数	AUTO
useUpdateEffect	跳过首次渲染的 useEffect	AUTO

浏览器

函数	描述	调用方式
useActiveElement	跟踪当前获得焦点的元素	AUTO
useBattery	响应式电量和充电信息	AUTO
useClickAnyWhere	监听文档任意位置的点击事件	AUTO
useClickAway	检测目标元素之外的点击	AUTO
useClipboard	支持读取和写入的响应式 Clipboard API	AUTO
useDocumentVisibility	响应式文档可见性状态	AUTO
useElementSize	通过 ResizeObserver 获取响应式元素尺寸	AUTO
useEventListener	声明式事件监听器，自动清理	AUTO
useFps	响应式 FPS（每秒帧数）测量	AUTO
useFullscreen	响应式 Fullscreen API	AUTO
useHash	响应式 window.location.hash	AUTO
useHover	响应式元素悬停状态	AUTO
useInViewport	通过 IntersectionObserver 跟踪元素可见性	AUTO
useIsMatchMedia	响应式 CSS 媒体查询匹配状态	AUTO
useIsOnline	响应式网络在线/离线状态	AUTO
useMouse	响应式鼠标/触摸指针坐标	AUTO
useNetwork	响应式网络连接信息	AUTO
useOs	响应式浏览器操作系统检测	AUTO
useScrollLock	锁定/解锁目标元素的滚动	AUTO
useTextSelection	响应式文本选择状态及其边界矩形	AUTO
useTitle	响应式文档标题管理	AUTO

开发

函数	描述	调用方式
useWhyDidYouUpdate	记录两次渲染之间哪些 props 发生了变化（仅用于调试）	AUTO

外部

函数	描述	调用方式
useMcp	来自 use-mcp 的 Model Context Protocol 客户端 Hook	EXTERNAL
useQuery	来自 @tanstack/react-query 的数据获取 Hook	EXTERNAL
useStickToBottom	来自 use-stick-to-bottom 的滚动跟随行为	EXTERNAL
useSWR	来自 swr 的数据获取 Hook	EXTERNAL