@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 | | 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 | | 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.