Docs
useStateValidator

Validate state updates in React components with the useStateValidator hook, providing a way to ensure state changes meet specific criteria before being applied.

Installation

pnpm dlx shadcn@latest add https://usekit.kiron.dev/k/use-state-validator

Usage

"use client"
 
import { useStateValidator } from "@/hooks/use-state-validator"
 
export function Component() {
  const { state, setState, result } = useStateValidator({
    initialValue: 0,
    validator: (value) => value >= 0,
    onInvalid: () => console.warn("Invalid state value"),
    onValid: () => console.log("State value is valid"),
    throwOnInvalid: false,
    asyncDebounceMs: 300,
  })
 
  return (
    <div style={{ padding: "20px", maxWidth: "600px", margin: "0 auto" }}>
      <h1>State Validator Example</h1>
      <p>Current State: {state}</p>
      <button onClick={() => setState((prev) => prev + 1)}>Increment</button>
      <button onClick={() => setState((prev) => prev - 1)}>Decrement</button>
      {result.isPending && <p>Validating...</p>}
      {!result.isValid && <p style={{ color: "red" }}>Error: {result.error}</p>}
    </div>
  )
}

API Reference

Parameters

NameTypeDescriptionDefault ValueOptional
initialValueT | (() => T)`The initial value of the state. Can be a value or a function that returns a value.undefinedYes
validator(value: T) => booleanA function that validates the new state value. It should return true if the value is valid, or false if it is not.-No
onInvalid() => voidA callback function that is called when the new state value is invalid.-Yes
onValid() => voidA callback function that is called when the new state value is valid.-Yes
throwOnInvalidbooleanIf true, an error will be thrown when the new state value is invalid. If false, the state will not be updated.falseYes
asyncDebounceMsnumberThe debounce time in milliseconds for asynchronous validation. If set, the validation will be debounced by this amount of time.0Yes

Return Values

NameTypeDescription
stateTThe current state value.
setState(value: T | ((prevState: T) => T)) => voidA function to update the state. It accepts a new value or a function that receives the previous state and returns the new state.
result{isValid: boolean, error?: string, isPending: boolean}An object containing the validation result. isValid indicates if the current state is valid, error contains an error message if the state is invalid, and isPending indicates if the validation is still in progress.
useSpeakupuseStep