# UtilityJS | useOnChange A React hook that invokes a callback anytime a value changes.
## Features - **Change Detection**: Automatically detects when a value changes - **Callback Stability**: Uses stable callback references to prevent unnecessary re-renders - **Type Safety**: Full TypeScript support with generic typing - **Performance Optimized**: Efficient comparison using previous value tracking - **Side Effect Management**: Perfect for triggering side effects on value changes ## Installation ```bash npm install @utilityjs/use-on-change ``` or ```bash pnpm add @utilityjs/use-on-change ``` ## Usage ### Basic Usage ```tsx import { useOnChange } from "@utilityjs/use-on-change"; import { useState } from "react"; function Counter() { const [count, setCount] = useState(0); useOnChange(count, newCount => { console.log(`Count changed to: ${newCount}`); }); return (

Count: {count}

); } ``` ### User Analytics ```tsx import { useOnChange } from "@utilityjs/use-on-change"; import { useState } from "react"; function UserDashboard() { const [currentPage, setCurrentPage] = useState("home"); useOnChange(currentPage, page => { // Track page views analytics.track("page_view", { page }); }); return ( ); } ``` ### API Data Fetching ```tsx import { useOnChange } from "@utilityjs/use-on-change"; import { useState, useEffect } from "react"; function UserProfile() { const [userId, setUserId] = useState(1); const [userData, setUserData] = useState(null); const [loading, setLoading] = useState(false); useOnChange(userId, async newUserId => { setLoading(true); try { const response = await fetch(`/api/users/${newUserId}`); const data = await response.json(); setUserData(data); } catch (error) { console.error("Failed to fetch user:", error); } finally { setLoading(false); } }); return (
{loading ? (

Loading...

) : userData ? (

{userData.name}

{userData.email}

) : null}
); } ``` ### Form Validation ```tsx import { useOnChange } from "@utilityjs/use-on-change"; import { useState } from "react"; function EmailForm() { const [email, setEmail] = useState(""); const [isValid, setIsValid] = useState(true); const [errorMessage, setErrorMessage] = useState(""); useOnChange(email, newEmail => { if (newEmail === "") { setIsValid(true); setErrorMessage(""); return; } const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/; const valid = emailRegex.test(newEmail); setIsValid(valid); setErrorMessage(valid ? "" : "Please enter a valid email address"); }); return (
setEmail(e.target.value)} placeholder="Enter your email" style={{ borderColor: isValid ? "#ccc" : "#ff0000", }} /> {!isValid &&

{errorMessage}

}
); } ``` ### Local Storage Sync ```tsx import { useOnChange } from "@utilityjs/use-on-change"; import { useState, useEffect } from "react"; function Settings() { const [theme, setTheme] = useState("light"); const [language, setLanguage] = useState("en"); // Load from localStorage on mount useEffect(() => { const savedTheme = localStorage.getItem("theme"); const savedLanguage = localStorage.getItem("language"); if (savedTheme) setTheme(savedTheme); if (savedLanguage) setLanguage(savedLanguage); }, []); // Save to localStorage when values change useOnChange(theme, newTheme => { localStorage.setItem("theme", newTheme); document.body.className = `theme-${newTheme}`; }); useOnChange(language, newLanguage => { localStorage.setItem("language", newLanguage); // Update i18n or trigger language change }); return (
); } ``` ### Complex Object Changes ```tsx import { useOnChange } from "@utilityjs/use-on-change"; import { useState } from "react"; type FilterState = { category: string; priceRange: [number, number]; sortBy: string; }; function ProductFilter() { const [filters, setFilters] = useState({ category: "all", priceRange: [0, 1000], sortBy: "name", }); useOnChange(filters, newFilters => { console.log("Filters changed:", newFilters); // Trigger API call to fetch filtered products fetchProducts(newFilters); }); const updateFilter = (key: keyof FilterState, value: any) => { setFilters(prev => ({ ...prev, [key]: value })); }; return (
updateFilter("priceRange", [0, Number(e.target.value)])} />
); } ``` ## API ### `useOnChange(value, onChange)` A React hook that monitors a value and executes a callback when it changes. #### Parameters - `value: T` - The value to monitor for changes - `onChange: (current: T) => void` - Callback function invoked when the value changes #### Returns - `void` - This hook doesn't return anything #### Behavior - **Change Detection**: Uses strict equality (`!==`) to detect changes - **Callback Timing**: The callback is invoked after the component re-renders with the new value - **Initial Render**: The callback is not invoked on the initial render, only on subsequent changes - **Stable References**: Uses `useGetLatest` to ensure the callback reference is always current ### Dependencies This hook depends on: - `@utilityjs/use-previous-value` - For tracking previous values ## Use Cases - **Analytics Tracking**: Track user interactions and state changes - **API Calls**: Trigger data fetching when parameters change - **Form Validation**: Validate fields as users type - **Local Storage**: Sync state changes to localStorage - **Side Effects**: Execute any side effect in response to value changes - **Logging**: Log state changes for debugging purposes ## Contributing Read the [contributing guide](https://github.com/mimshins/utilityjs/blob/main/CONTRIBUTING.md) to learn about our development process, how to propose bug fixes and improvements, and how to build and test your changes. ## License This project is licensed under the terms of the [MIT license](https://github.com/mimshins/utilityjs/blob/main/LICENSE).