Hooks

A collection of reusable React hooks for common UI patterns and state management.

Installation

pnpm add @akinon/hooks

useDebounce

Debounces a value that changes over time. Delays updating the value until after a specified wait time has elapsed since the last change.

Usage

import { useDebounce } from '@akinon/hooks';

const SearchInput = () => {
  const [searchTerm, setSearchTerm] = useState('');
  const debouncedSearchTerm = useDebounce(searchTerm, 500);

  useEffect(() => {
    if (debouncedSearchTerm) {
      // API call only fires 500ms after user stops typing
      searchProducts(debouncedSearchTerm);
    }
  }, [debouncedSearchTerm]);

  return (
    <Input
      value={searchTerm}
      onChange={(e) => setSearchTerm(e.target.value)}
      placeholder="Search products..."
    />
  );
};

Parameters

Parameter	Type	Description
value	T	The value to debounce
delay	number	Delay in milliseconds

Returns

Type	Description
T	The debounced value

---

useThrottle

Throttles a value that changes over time. Limits how frequently the value can update.

Usage

import { useThrottle } from '@akinon/hooks';

const ScrollTracker = () => {
  const [scrollY, setScrollY] = useState(0);
  const throttledScrollY = useThrottle(scrollY, 100);

  useEffect(() => {
    const handleScroll = () => setScrollY(window.scrollY);
    window.addEventListener('scroll', handleScroll);
    return () => window.removeEventListener('scroll', handleScroll);
  }, []);

  // Only updates every 100ms, preventing performance issues
  return <div>Scroll position: {throttledScrollY}px</div>;
};

Parameters

Parameter	Type	Description
value	T	The value to throttle
delay	number	Throttle interval in milliseconds

Returns

Type	Description
T	The throttled value

---

useLocalStorage

Persists state to localStorage with automatic serialization/deserialization.

Usage

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

const ThemeSettings = () => {
  const [theme, setTheme, removeTheme] = useLocalStorage('theme', 'light');

  return (
    <div>
      <p>Current theme: {theme}</p>
      <Button onClick={() => setTheme('dark')}>Dark Mode</Button>
      <Button onClick={() => setTheme('light')}>Light Mode</Button>
      <Button onClick={removeTheme}>Reset</Button>
    </div>
  );
};

With Objects

interface UserPreferences {
  language: string;
  notifications: boolean;
}

const [preferences, setPreferences] = useLocalStorage<UserPreferences>(
  'user-preferences',
  { language: 'en', notifications: true }
);

// Update nested values
setPreferences(prev => ({
  ...prev,
  notifications: false
}));

Raw Mode

// Store value as raw string without JSON serialization
const [token, setToken] = useLocalStorage('auth-token', '', { raw: true });

Parameters

Parameter	Type	Description
key	string	localStorage key
initialValue	T	Initial value if key doesn't exist
options	ParserOptions	Serialization options

Returns

Index	Type	Description
0	T | undefined	Current value
1	Dispatch<SetStateAction<T>>	Setter function
2	() => void	Remove function

---

useSessionStorage

Persists state to sessionStorage. Similar to useLocalStorage but data is cleared when the browser session ends.

Usage

import { useSessionStorage } from '@akinon/hooks';

const WizardForm = () => {
  const [step, setStep] = useSessionStorage('wizard-step', 1);
  const [formData, setFormData] = useSessionStorage('wizard-data', {});

  // State persists across page reloads within the same session
  return (
    <div>
      <p>Step {step} of 3</p>
      <Button onClick={() => setStep(step + 1)}>Next</Button>
    </div>
  );
};

Parameters

Parameter	Type	Description
key	string	sessionStorage key
initialValue	T	Initial value if key doesn't exist
raw	boolean	Store as raw string (default: false)

Returns

Index	Type	Description
0	T	Current value
1	(value: T) => void	Setter function

---

useToggle

Toggles a boolean state. Useful for UI states like open/close, show/hide, enabled/disabled.

Usage

import { useToggle } from '@akinon/hooks';

const Accordion = () => {
  const [isOpen, toggle] = useToggle(false);

  return (
    <div>
      <Button onClick={toggle}>
        {isOpen ? 'Collapse' : 'Expand'}
      </Button>
      {isOpen && <div>Accordion content</div>}
    </div>
  );
};

Multiple Toggles

const SettingsPanel = () => {
  const [showAdvanced, toggleAdvanced] = useToggle(false);
  const [darkMode, toggleDarkMode] = useToggle(false);
  const [notifications, toggleNotifications] = useToggle(true);

  return (
    <div>
      <Switch checked={darkMode} onChange={toggleDarkMode} />
      <Switch checked={notifications} onChange={toggleNotifications} />
      <Button onClick={toggleAdvanced}>
        {showAdvanced ? 'Hide' : 'Show'} Advanced
      </Button>
    </div>
  );
};

Parameters

Parameter	Type	Default	Description
initialValue	boolean	false	Initial toggle state

Returns

Index	Type	Description
0	boolean	Current value
1	() => void	Toggle function

---

useMount

Runs a function when the component mounts. A cleaner alternative to useEffect with empty dependency array.

Usage

import { useMount } from '@akinon/hooks';

const Dashboard = () => {
  useMount(() => {
    // Runs once when component mounts
    analytics.trackPageView('dashboard');
    fetchInitialData();
  });

  return <div>Dashboard content</div>;
};

Parameters

Parameter	Type	Description
fn	() => void	Function to run on mount

---

usePrevious

Returns the previous value of a state or prop. Useful for comparing values between renders.

Usage

import { usePrevious } from '@akinon/hooks';

const Counter = () => {
  const [count, setCount] = useState(0);
  const previousCount = usePrevious(count);

  return (
    <div>
      <p>Current: {count}</p>
      <p>Previous: {previousCount}</p>
      <Button onClick={() => setCount(count + 1)}>Increment</Button>
    </div>
  );
};

Detecting Changes

const ProfilePage = ({ userId }: { userId: string }) => {
  const previousUserId = usePrevious(userId);

  useEffect(() => {
    if (previousUserId !== userId) {
      // User changed, fetch new profile
      fetchUserProfile(userId);
    }
  }, [userId, previousUserId]);

  return <div>Profile for user {userId}</div>;
};

Parameters

Parameter	Type	Description
value	T	Value to track

Returns

Type	Description
T | undefined	Previous value (undefined on first render)

---

useWindowSize

Returns the current window dimensions and updates on resize.

Usage

import { useWindowSize } from '@akinon/hooks';

const ResponsiveComponent = () => {
  const { width, height } = useWindowSize();

  const isMobile = width < 768;
  const isTablet = width >= 768 && width < 1024;
  const isDesktop = width >= 1024;

  return (
    <div>
      <p>Window: {width}x{height}</p>
      {isMobile && <MobileLayout />}
      {isTablet && <TabletLayout />}
      {isDesktop && <DesktopLayout />}
    </div>
  );
};

Responsive Grid

const ProductGrid = () => {
  const { width } = useWindowSize();
  
  const columns = width < 768 ? 1 : width < 1024 ? 2 : width < 1440 ? 3 : 4;

  return (
    <div style={{ display: 'grid', gridTemplateColumns: `repeat(${columns}, 1fr)` }}>
      {products.map(product => (
        <ProductCard key={product.id} {...product} />
      ))}
    </div>
  );
};

Returns

Property	Type	Description
width	number	Window inner width
height	number	Window inner height

---

Best Practices

1. Use debounce for input - Debounce search inputs and form fields to reduce API calls

2. Use throttle for scroll/resize - Throttle scroll and resize handlers for better performance

3. Prefer useLocalStorage for persistence - Use for user preferences that should persist

4. Use useSessionStorage for temporary data - Wizard forms, multi-step processes

5. Use useToggle for boolean states - Cleaner than managing boolean state manually