@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

Direct Import (Recommended)

Import individual hooks for optimal tree-shaking and minimal bundle size:

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

Barrel Import (Not Recommended)

While supported, barrel imports increase bundle size and should be avoided in production:

// ⚠️ AVOID: Imports entire library, defeats tree-shaking
import { useBoolean, useLocalStorage, useMediaQuery } from '@opensite/hooks';

CDN Usage (UMD)

For legacy browser environments only:

<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
useScreen	Viewport dimensions with Tailwind breakpoint and screen type detection	View
Utilities
useCopyToClipboard	Copy text to clipboard with feedback state	View
usePlatformFromUrl	Resolve a social platform name from a URL	View
useIsClient	Detect client-side vs server-side rendering	View
useIsTouchDevice	Detect touch-primary input with dynamic hybrid device updates	View
useIsomorphicLayoutEffect	SSR-safe useLayoutEffect	View
Website Extractors
useOpenGraphExtractor	Fetch and normalize Open Graph data with debouncing and caching	View
useWebsiteSchemaExtractor	Extract Schema.org data from a website	View
useWebsiteLinksExtractor	Extract outbound and internal link data from a webpage	View
useWebsiteMetaExtractor	Extract title, description, and meta tags from a webpage	View
useWebsiteRssExtractor	Extract RSS feed information from a website	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) for optimal tree-shaking.

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.