@usegrand/react-hokss

A collection of unique and useful React hooks that enhance your development experience with modern browser APIs and common functionality patterns.

🚀 Installation

npm install @usegrand/react-hokss

📋 Requirements

• React 16.8.0 or higher
• TypeScript support included

🎯 Features

• 13 Unique Hooks - Carefully crafted hooks for modern web development
• TypeScript First - Full TypeScript support with comprehensive type definitions
• Modern Browser APIs - Leverage cutting-edge browser capabilities
• Tree Shakeable - Import only what you need
• SSR Safe - Server-side rendering compatible
• Lightweight - Minimal bundle impact

📚 Available Hooks

Clipboard & User Input

• useCopyToClipboard - Copy text to clipboard with history tracking
• useDetectCapsLock - Detect Caps Lock key state
• useTextSelection - Track and manage text selection

Document & Navigation

• useDocumentTitle - Dynamically manage document title
• useFavicon - Change page favicon dynamically
• usePageLeave - Detect when user is about to leave the page

Visual & Theming

• usePreferredColorScheme - Detect and manage color scheme preferences
• useScreenBlur - Apply blur effects to screen or elements
• useEyeDropper - Access browser's native color picker

File System & Storage

• useFileSystemAccess - Read and write files using File System Access API

Scroll & Position

• useScrollPosition - Track scroll position and direction

State Management

• useTristate - Manage three-state values (true/false/indeterminate)
• useUndoRedo - Add undo/redo functionality to any state

🔧 Usage Examples

Quick Start

import {
  useCopyToClipboard,
  usePreferredColorScheme,
} from "@usegrand/react-hokss";

function MyComponent() {
  const { copy, copied } = useCopyToClipboard();
  const { colorScheme, toggleColorScheme } = usePreferredColorScheme();

  return (
    <div>
      <button onClick={() => copy("Hello World!")}>
        {copied ? "Copied!" : "Copy Text"}
      </button>

      <button onClick={toggleColorScheme}>Current theme: {colorScheme}</button>
    </div>
  );
}

📖 Hook Documentation

useCopyToClipboard

Copy text to clipboard with optional history tracking and fallback support.

import { useCopyToClipboard } from "@usegrand/react-hokss";

function CopyExample() {
  const { copy, copied, error, history, clearHistory } = useCopyToClipboard({
    trackHistory: true,
    maxHistorySize: 10,
  });

  return (
    <div>
      <button onClick={() => copy("Hello World!")}>
        {copied ? "Copied!" : "Copy Text"}
      </button>
      {error && <p>Error: {error}</p>}
      <ul>
        {history.map((item, i) => (
          <li key={i}>{item}</li>
        ))}
      </ul>
    </div>
  );
}

useDetectCapsLock

Detect if Caps Lock is currently enabled during keyboard input.

import { useDetectCapsLock } from "@usegrand/react-hokss";

function CapsLockExample() {
  const { isCapsLockEnabled, isSupported } = useDetectCapsLock({
    onCapsLockChange: (enabled) => console.log("Caps Lock:", enabled),
  });

  if (!isSupported) return <p>Caps Lock detection not supported</p>;

  return (
    <div>
      <input placeholder="Type here to detect Caps Lock" />
      {isCapsLockEnabled && <p>⚠️ Caps Lock is ON</p>}
    </div>
  );
}

useDocumentTitle

Dynamically manage the browser document title with templates and restoration.

import { useDocumentTitle } from "@usegrand/react-hokss";

function TitleExample() {
  const { setTitle, addPrefix } = useDocumentTitle("My App", {
    template: "{title} | My Website",
    restoreOnUnmount: true,
  });

  return (
    <div>
      <button onClick={() => setTitle("New Page")}>Change Title</button>
      <button onClick={() => addPrefix("🔥 ")}>Add Prefix</button>
    </div>
  );
}

useEyeDropper

Access the browser's native EyeDropper API for color picking.

import { useEyeDropper } from "@usegrand/react-hokss";

function ColorPickerExample() {
  const { isSupported, isOpen, color, error, open } = useEyeDropper();

  if (!isSupported) {
    return <p>EyeDropper not supported in this browser</p>;
  }

  return (
    <div>
      <button onClick={open} disabled={isOpen}>
        {isOpen ? "Picking..." : "Pick Color"}
      </button>
      {color && (
        <div style={{ backgroundColor: color, padding: "10px" }}>
          Selected: {color}
        </div>
      )}
      {error && <p>Error: {error}</p>}
    </div>
  );
}

useFavicon

Dynamically change the page favicon.

import { useFavicon } from "@usegrand/react-hokss";

function FaviconExample() {
  const { setFavicon, setFaviconByStatus, restoreOriginal } = useFavicon();

  return (
    <div>
      <button onClick={() => setFavicon("/icon-success.ico")}>
        Success Icon
      </button>
      <button onClick={() => setFaviconByStatus("error")}>Error Icon</button>
      <button onClick={restoreOriginal}>Restore Original</button>
    </div>
  );
}

useFileSystemAccess

Read and write files using the File System Access API.

import { useFileSystemAccess } from "@usegrand/react-hokss";

function FileSystemExample() {
  const { isSupported, hasPermission, isLoading, openFile, saveFile } =
    useFileSystemAccess();

  if (!isSupported) {
    return <p>File System Access not supported</p>;
  }

  return (
    <div>
      <button
        onClick={() => openFile({ types: [".txt"] })}
        disabled={isLoading}
      >
        Open File
      </button>
      <button onClick={() => saveFile("Hello World!", "hello.txt")}>
        Save File
      </button>
      <p>Permission: {hasPermission ? "Granted" : "Not granted"}</p>
    </div>
  );
}

usePageLeave

Detect when user is about to leave the page (exit-intent detection).

import { usePageLeave } from "@usegrand/react-hokss";

function PageLeaveExample() {
  const { hasLeft, isVisible, resetPageLeave } = usePageLeave({
    onPageLeave: () => {
      console.log("User is leaving!");
      // Show exit-intent modal, save data, etc.
    },
    sensitivity: 20,
  });

  return (
    <div>
      <p>Page visible: {isVisible ? "Yes" : "No"}</p>
      <p>Has left: {hasLeft ? "Yes" : "No"}</p>
      <button onClick={resetPageLeave}>Reset</button>
    </div>
  );
}

usePreferredColorScheme

Detect and manage user's preferred color scheme (light/dark mode).

import { usePreferredColorScheme } from "@usegrand/react-hokss";

function ThemeExample() {
  const { colorScheme, toggleColorScheme, isPreferred } =
    usePreferredColorScheme({
      autoApply: true,
      classNames: { light: "light-theme", dark: "dark-theme" },
    });

  return (
    <div>
      <p>Current scheme: {colorScheme}</p>
      <p>From user preference: {isPreferred ? "Yes" : "No"}</p>
      <button onClick={toggleColorScheme}>
        Switch to {colorScheme === "light" ? "dark" : "light"} mode
      </button>
    </div>
  );
}

useScreenBlur

Apply blur effects to the entire screen or specific elements.

import { useScreenBlur } from "@usegrand/react-hokss";

function BlurExample() {
  const { isBlurred, blur, unblur, toggle } = useScreenBlur();

  return (
    <div>
      <button onClick={() => blur({ blurAmount: 10 })}>Blur Screen</button>
      <button onClick={unblur}>Unblur</button>
      <button onClick={toggle}>Toggle</button>
      <p>Screen is {isBlurred ? "blurred" : "normal"}</p>
    </div>
  );
}

useScrollPosition

Track scroll position, direction, and provides scroll control utilities.

import { useScrollPosition } from "@usegrand/react-hokss";

function ScrollExample() {
  const {
    position,
    direction,
    isScrolling,
    scrollToTop,
    getScrollPercentage,
    isAtBottom,
  } = useScrollPosition({
    trackDirection: true,
    throttle: 100,
  });

  const percentage = getScrollPercentage();

  return (
    <div>
      <p>
        Position: {position.x}, {position.y}
      </p>
      <p>Direction: {direction.y}</p>
      <p>Scrolling: {isScrolling ? "Yes" : "No"}</p>
      <p>Progress: {percentage.y.toFixed(1)}%</p>
      <button onClick={scrollToTop}>Scroll to Top</button>
      {isAtBottom && <p>🎉 You reached the bottom!</p>}
    </div>
  );
}

useTextSelection

Track and manage text selection on the page.

import { useTextSelection } from "@usegrand/react-hokss";

function TextSelectionExample() {
  const { text, isSelected, rect, clearSelection } = useTextSelection();

  return (
    <div>
      <p>Select this text to see the hook in action!</p>
      {isSelected && (
        <div>
          <p>Selected: "{text}"</p>
          <p>
            Position: {rect?.top}, {rect?.left}
          </p>
          <button onClick={clearSelection}>Clear Selection</button>
        </div>
      )}
    </div>
  );
}

useTristate

Manage a three-state value (true, false, indeterminate).

import { useTristate } from "@usegrand/react-hokss";

function TristateExample() {
  const { value, setTrue, setFalse, setIndeterminate, cycle } =
    useTristate("indeterminate");

  return (
    <div>
      <p>Current value: {String(value)}</p>
      <button onClick={setTrue}>Set True</button>
      <button onClick={setFalse}>Set False</button>
      <button onClick={setIndeterminate}>Set Indeterminate</button>
      <button onClick={cycle}>Cycle</button>

      <input
        type="checkbox"
        checked={value === true}
        ref={(el) => {
          if (el) el.indeterminate = value === "indeterminate";
        }}
        readOnly
      />
    </div>
  );
}

useUndoRedo

Add undo/redo functionality to any state.

import { useUndoRedo } from "@usegrand/react-hokss";

function UndoRedoExample() {
  const { state, setState, undo, redo, canUndo, canRedo, clearHistory } =
    useUndoRedo("Initial text", { maxHistorySize: 20 });

  return (
    <div>
      <input value={state} onChange={(e) => setState(e.target.value)} />
      <button onClick={undo} disabled={!canUndo}>
        Undo
      </button>
      <button onClick={redo} disabled={!canRedo}>
        Redo
      </button>
      <button onClick={clearHistory}>Clear History</button>
    </div>
  );
}

🌐 Browser Compatibility

| Hook | Chrome | Firefox | Safari | Edge | Notes | | --------------------- | ------ | ------- | ------ | ------ | ----------------------- | | Most hooks | ✅ | ✅ | ✅ | ✅ | Universal compatibility | | useEyeDropper | ✅ 95+ | ❌ | ❌ | ✅ 95+ | Chromium only | | useFileSystemAccess | ✅ 86+ | ❌ | ❌ | ✅ 86+ | Chromium only |

Hooks that depend on modern APIs include isSupported flags for degradation.

📄 License

MIT © @usegrand/react-hokss

🔗 Links

• Documentation
• NPM Package