@opensite/hooks

@opensite/hooks

Performance-first React hooks for UI state, storage, events, and responsive behavior.

Overview

@opensite/hooks provides a suite of zero-dependency, tree-shakable React hooks designed for high-performance marketing sites and web applications. All hooks are SSR-safe and optimized for Core Web Vitals.

Key Features:

• 🚀 Zero dependencies – Only React as a peer dependency
• 🌳 Tree-shakable – Import only what you use with flat exports
• 🔒 SSR-safe – All hooks handle server-side rendering correctly
• ⚡ Performance-first – Memoized callbacks, minimal re-renders
• 📦 Multiple formats – ESM, CJS, and UMD builds included

Installation

# npm
npm install @opensite/hooks

# pnpm
pnpm add @opensite/hooks

# yarn
yarn add @opensite/hooks

Requirements

• React 17.0.0 or higher
• React DOM 17.0.0 or higher

Quick Start

Barrel Import

Import multiple hooks from the main entry point:

import { useBoolean, useLocalStorage, useMediaQuery } from '@opensite/hooks';

Direct Import (Recommended for Bundle Size)

Import individual hooks for optimal tree-shaking:

import { useBoolean } from '@opensite/hooks/useBoolean';
import { useLocalStorage } from '@opensite/hooks/useLocalStorage';
import { useMediaQuery } from '@opensite/hooks/useMediaQuery';

CDN Usage (UMD)

<script src="https://cdn.jsdelivr.net/npm/@opensite/hooks/dist/browser/opensite-hooks.umd.js"></script>
<script>
  const { useBoolean, useDebounceValue } = window.OpensiteHooks;
</script>

Available Hooks

Hook	Description	Docs
State Management
useBoolean	Boolean state with toggle, setTrue, setFalse helpers	View
useMap	Map state with set, remove, clear helpers	View
usePrevious	Access the previous value of a state or prop	View
Storage
useLocalStorage	Synchronized state with localStorage + cross-tab sync	View
useSessionStorage	Synchronized state with sessionStorage	View
Timing
useDebounceValue	Debounce value changes with configurable delay	View
useDebounceCallback	Debounce callbacks with cancel/flush controls	View
useThrottle	Throttle value changes with leading/trailing options	View
DOM & Events
useEventListener	Attach event listeners with automatic cleanup	View
useOnClickOutside	Detect clicks outside specified elements	View
useHover	Detect hover state using pointer events	View
useResizeObserver	Observe element size changes	View
Responsive
useMediaQuery	Reactive CSS media query matching	View
Utilities
useCopyToClipboard	Copy text to clipboard with feedback state	View
useIsClient	Detect client-side vs server-side rendering	View
useIsomorphicLayoutEffect	SSR-safe useLayoutEffect	View

Examples

useBoolean

import { useBoolean } from '@opensite/hooks/useBoolean';

function Modal() {
  const { value: isOpen, setTrue: open, setFalse: close, toggle } = useBoolean(false);

  return (
    <>
      <button onClick={open}>Open Modal</button>
      {isOpen && (
        <dialog open>
          <p>Modal content</p>
          <button onClick={close}>Close</button>
        </dialog>
      )}
    </>
  );
}

useDebounceValue

import { useState } from 'react';
import { useDebounceValue } from '@opensite/hooks/useDebounceValue';

function SearchInput() {
  const [query, setQuery] = useState('');
  const debouncedQuery = useDebounceValue(query, 300);

  // API call only triggers when debouncedQuery changes
  useEffect(() => {
    if (debouncedQuery) {
      searchAPI(debouncedQuery);
    }
  }, [debouncedQuery]);

  return <input value={query} onChange={(e) => setQuery(e.target.value)} />;
}

useMediaQuery

import { useMediaQuery } from '@opensite/hooks/useMediaQuery';

function ResponsiveComponent() {
  const isMobile = useMediaQuery('(max-width: 768px)');
  const prefersDark = useMediaQuery('(prefers-color-scheme: dark)');

  return (
    <div className={prefersDark ? 'dark' : 'light'}>
      {isMobile ? <MobileNav /> : <DesktopNav />}
    </div>
  );
}

useLocalStorage

import { useLocalStorage } from '@opensite/hooks/useLocalStorage';

function ThemeToggle() {
  const [theme, setTheme] = useLocalStorage('theme', 'light');

  return (
    <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
      Current: {theme}
    </button>
  );
}

Migration from v1.x

Version 2.0.0 simplifies import paths. Update your imports:

- import { useBoolean } from '@opensite/hooks/core/useBoolean';
- import { useBoolean } from '@opensite/hooks/hooks/useBoolean';
+ import { useBoolean } from '@opensite/hooks/useBoolean';

The /core/* and /hooks/* paths have been removed. Use flat paths (/useBoolean) or barrel imports (@opensite/hooks) instead.

TypeScript

All hooks are written in TypeScript and include full type definitions. Types are exported alongside hooks:

import { useBoolean, type UseBooleanResult } from '@opensite/hooks/useBoolean';
import { useLocalStorage, type StorageOptions } from '@opensite/hooks/useLocalStorage';

Contributing

We welcome contributions! Please see our Contributing Guide for details.

# Clone the repo
git clone https://github.com/opensite-ai/opensite-hooks.git
cd opensite-hooks

# Install dependencies
pnpm install

# Run tests
pnpm test

# Build
pnpm build

License

BSD-3-Clause © OpenSite AI

Related Projects

• @opensite/ui – React component library for OpenSite
• @opensite/blocks – Semantic page blocks for site builders
• @page-speed/forms – Framework-agnostic form handling

Visit OpenSite AI for more projects and information.