Stable

Hooks & Utilities

A collection of framework-agnostic hooks and TypeScript utilities designed to accelerate UI development, handle responsive layouts, manage component lifecycles, and simplify common frontend patterns.

💡 Note: All hooks are compatible with React, Preact, and Vue (via adapter). Utilities work standalone in any environment.

Installation

Terminal

npm install @webui/hooks @webui/utils

Core Hook

useTheme()

Manages theme context, color mode (light/dark), and design token overrides. Automatically persists user preference to localStorage and respects system settings.

Signature

TypeScript

function useTheme(): {
  mode: 'light' | 'dark' | 'system';
  tokens: DesignTokens;
  setMode: (mode: 'light' | 'dark' | 'system') => void;
  toggle: () => void;
}

Example

React

import { useTheme } from '@webui/hooks';

export function ThemeSwitcher() {
  const { mode, toggle, tokens } = useTheme();
  return (
    <button onClick={toggle} style={{ color: tokens.colors.primary }}>
      Switch to {mode === 'dark' ? 'Light' : 'Dark'} Mode
    </button>
  );
}

Core Hook

useBreakpoint()

Reactive breakpoint detection with fallback to CSS media queries. Returns the current active breakpoint and boolean flags for all defined breakpoints.

Parameters

Parameter	Type	Default	Description
`breakpoints`	Record<string, number>	Webui defaults	Custom breakpoint thresholds in px
`fallback`	string	`'desktop'`	Initial value before mount

Example

React

import { useBreakpoint } from '@webui/hooks';

export function ResponsiveGrid() {
  const { current, isMobile, isTablet, isDesktop } = useBreakpoint();
  return <div style={{ gridTemplateColumns: isMobile ? '1fr' : 'repeat(3, 1fr)' }} />;
}

Beta

useAnimation()

Declarative animation controller. Triggers CSS/JS animations on mount, visibility change, or manual invocation. Integrates with IntersectionObserver for scroll-triggered effects.

TypeScript

function useAnimation(config: {
  trigger: 'mount' | 'view' | 'manual';
  keyframes?: Keyframe[];
  duration?: number;
  easing?: string;
}): { ref: RefObject<HTMLElement>; play: () => void; isPlaying: boolean };

Utility

cn()

Smart class name merger. Combines arbitrary CSS classes, conditional arrays, and Tailwind-style syntax. Handles duplicate removal and conflict resolution.

Signature

TypeScript

function cn(...classes: (string | boolean | undefined | null | Record<string, boolean>)[]): string

Example

JavaScript

import { cn } from '@webui/utils';

const classes = cn(
  'px-4 py-2 rounded-lg font-medium',
  isActive && 'bg-indigo-600 text-white',
  !isActive && 'bg-gray-100 text-gray-700',
  { 'opacity-50': isDisabled }
);
// Output: 'px-4 py-2 rounded-lg font-medium bg-indigo-600 text-white'

Utility

debounce()

Function debouncer with configurable delay and leading/trailing edge options. Automatically cancels previous executions for high-frequency events.

Parameters

Parameter	Type	Description
`fn`	Function	Function to debounce
`delay`	number	Delay in milliseconds (default: 300)
`options`	{ leading?: boolean, trailing?: boolean }	Execution edge control

Example

JavaScript

import { debounce } from '@webui/utils';

const handleSearch = debounce((query) => {
  api.search(query).then(results => setResults(results));
}, 400);

// Usage in event handler
onChange={(e) => handleSearch(e.target.value)}

Utility

validateEmail()

Strict RFC 5322 compliant email validation. Rejects malformed addresses, disposable domains, and malformed TLDs.

JavaScript

import { validateEmail } from '@webui/utils';

console.log(validateEmail('user@example.com')); // true
console.log(validateEmail('invalid@'));          // false

Utility

formatCurrency()

Localized currency formatter with symbol placement, precision control, and accounting style support. Uses Intl.NumberFormat under the hood with sensible defaults.

Parameters

Parameter	Type	Default	Description
`value`	number	-	Currency amount
`options`	{ currency?: string, locale?: string, style?: 'standard'\|'accounting' }	USD / en-US / standard	Formatting configuration

JavaScript

import { formatCurrency } from '@webui/utils';

formatCurrency(1299.95, { currency: 'EUR', locale: 'de-DE' });
// → '1.299,95 €'

formatCurrency(-450, { style: 'accounting' });
// → '($450.00)'

⚠️ Migration Note: In v2.5, useAnimation will adopt a Web Animations API backend. Existing CSS-based configs will be auto-converted during runtime.