ui/hooks/form-reset

Form Reset

hookformresetuncontrolled

Keeps custom controls aligned with native form reset semantics without reporting uncontrolled resets as user changes.

tsx

1 const inputRef = useRef<HTMLInputElement>(null);2 const [value, setValue, , resetValue] = useControllableState({3   defaultValue,4   onChange: props.onChange,5 });6 7 const invalidatePendingReset = useFormReset(inputRef, defaultValue, resetValue);8 9 const handleChange = (nextValue: string) => {10   invalidatePendingReset();11   setValue(nextValue);12 };

Installation

$pnpm exec dgadd add ui/form-reset

[Installs to]src/hooks/use-form-reset.ts[Item]ui/form-reset

dgadd ships in @diffgazer/add on npm: pnpm add -D @diffgazer/add puts it on pnpm exec, and npx @diffgazer/add runs it without the install.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS from the installed package.

Parameters

Name	Type	Default	Description
refrequired	RefObject<HTMLElement \| null>	—	Element ref used to find the closest parent form.
resetValuerequired	T	—	Value passed to onReset when the parent form dispatches a native reset event.
onResetrequired	(value: T) => void	—	Called with resetValue when the parent form resets.
isUncontrolled	boolean	true	Set to false for controlled components. Controlled reset behavior can be provided separately.
controlled	{ syncResetBaseline: () => void; onReset: () => void } \| undefined	—	Optional handlers for custom controls that mirror native form state while externally controlled.

Returns

() => voidInvalidates a queued reset before a later user or programmatic value mutation.

Examples

Resettable Input

Preview

tsx

1 "use client";2 3 import { useRef } from "react";4 import { useControllableState } from "@/hooks/use-controllable-state";5 import { useFormReset } from "@/hooks/use-form-reset";6 7 export default function FormResetInputExample() {8   const inputRef = useRef<HTMLInputElement>(null);9   const defaultValue = "Initial value";10   const [value, setValue, , resetValue] = useControllableState({ defaultValue });11 12   const invalidatePendingReset = useFormReset(inputRef, defaultValue, resetValue);13 14   return (15     <form className="flex max-w-sm flex-col gap-3">16       <label className="flex flex-col gap-1.5 text-sm text-muted-foreground">17         Display name18         <input19           ref={inputRef}20           className="border border-border bg-background px-3 py-2 text-sm text-foreground"21           value={value}22           onChange={(event) => {23             invalidatePendingReset();24             setValue(event.currentTarget.value);25           }}26         />27       </label>28       <button29         type="reset"30         className="w-fit border border-border bg-muted px-3 py-1.5 font-mono text-sm text-foreground transition-colors hover:bg-background"31       >32         Reset33       </button>34     </form>35   );36 }37

Notes

Uncontrolled custom controls

Pair this hook with useControllableState's resetValue setter. It restores the default internal value without calling the public onChange callback.

Latest reset value

The reset listener stays stable while reading the latest resetValue and onReset callback.

Last mutation wins

Call the returned invalidation function immediately before changing the control value so an older queued reset cannot overwrite the newer mutation.

Source

Highlighted source loads after this disclosure opens. Browse the source repository.