ui/hooks/controllable-state

Controllable State

hookstatecontrolleduncontrolled

Generic controlled/uncontrolled state hook. Manages value, defaultValue, and onChange, with a separate silent setter for restoring uncontrolled native form state.

tsx

1 const [value, setValue, isControlled, resetValue] = useControllableState({2   value: props.value,3   defaultValue: props.defaultValue ?? "",4   onChange: props.onChange,5 });

Installation

$pnpm exec dgadd add ui/controllable-state

[Installs to]src/hooks/use-controllable-state.ts[Item]ui/controllable-state

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
value	T \| undefined	—	Controlled value. When provided, the component is in controlled mode.
defaultValuerequired	T	—	Initial value for uncontrolled mode.
onChange	(value: T) => void	—	Called when the value changes, in both controlled and uncontrolled modes.
controlled	boolean	—	Forces controlled-mode detection when value can be undefined but the consumer still owns state.

Returns

[T, (next: T | ((prev: T) => T)) => void, boolean, (next: T) => void]Tuple of [currentValue, setValue, isControlled, resetValue]. The public setter accepts direct values and updater functions; resetValue silently restores uncontrolled internal state.

Name	Type	Default	Description
currentValuerequired	T	—	The current value, whether controlled or uncontrolled.
setValuerequired	(next: T \| ((prev: T) => T)) => void	—	State setter that works in both modes. Supports functional updates.
isControlledrequired	boolean	—	Whether the consumer is driving the value externally.
resetValuerequired	(next: T) => void	—	Updates uncontrolled internal state without calling onChange. It is a no-op in controlled mode.

Examples

Basic Input

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { useControllableState } from "@/hooks/use-controllable-state";5 6 function CustomInput({7   id,8   name,9   value,10   defaultValue = "",11   onChange,12 }: {13   id: string;14   name: string;15   value?: string;16   defaultValue?: string;17   onChange?: (value: string) => void;18 }) {19   const [current, setCurrent] = useControllableState({20     value,21     defaultValue,22     onChange,23   });24 25   return (26     <input27       id={id}28       name={name}29       className="border border-border bg-background px-3 py-1.5 text-sm text-foreground"30       value={current}31       onChange={(e) => setCurrent(e.target.value)}32     />33   );34 }35 36 export default function ControllableStateBasic() {37   const [controlled, setControlled] = useState("hello");38 39   return (40     <div className="flex flex-col gap-6">41       <div className="flex flex-col gap-1.5">42         <label className="text-xs text-muted-foreground" htmlFor="uncontrolled-input">43           Uncontrolled44         </label>45         <CustomInput id="uncontrolled-input" name="uncontrolled" defaultValue="type here…" />46       </div>47 48       <div className="flex flex-col gap-1.5">49         <label className="text-xs text-muted-foreground" htmlFor="controlled-input">50           Controlled: {controlled}51         </label>52         <CustomInput53           id="controlled-input"54           name="controlled"55           value={controlled}56           onChange={setControlled}57         />58       </div>59     </div>60   );61 }62

Toggle

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { useControllableState } from "@/hooks/use-controllable-state";5 6 function Toggle({7   pressed,8   defaultPressed = false,9   onPressedChange,10   children,11 }: {12   pressed?: boolean;13   defaultPressed?: boolean;14   onPressedChange?: (pressed: boolean) => void;15   children: React.ReactNode;16 }) {17   const [isPressed, setIsPressed] = useControllableState({18     value: pressed,19     defaultValue: defaultPressed,20     onChange: onPressedChange,21   });22 23   return (24     <button25       type="button"26       role="switch"27       aria-checked={isPressed}28       className={`inline-flex items-center gap-2 border px-3 py-1.5 text-sm transition-colors ${29         isPressed30           ? "border-success-border bg-success-subtle text-success-text"31           : "border-border bg-background text-muted-foreground"32       }`}33       onClick={() => setIsPressed((prev) => !prev)}34     >35       <span aria-hidden="true" className="text-xs">36         {isPressed ? "ON" : "OFF"}37       </span>38       {children}39     </button>40   );41 }42 43 export default function ControllableStateToggle() {44   const [enabled, setEnabled] = useState(false);45 46   return (47     <div className="flex flex-col gap-6">48       <div className="flex flex-col gap-1.5">49         <span className="text-xs text-muted-foreground">Uncontrolled</span>50         <Toggle>Notifications</Toggle>51       </div>52 53       <div className="flex flex-col gap-1.5">54         <span className="text-xs text-muted-foreground">Controlled: {enabled ? "on" : "off"}</span>55         <Toggle pressed={enabled} onPressedChange={setEnabled}>56           Dark mode57         </Toggle>58       </div>59     </div>60   );61 }62

Notes

When to Use

Use when building a component that should work both as controlled (value + onChange) and uncontrolled (defaultValue). It handles the state switching logic so the component doesn't need to.

Return Value

The isControlled flag reports external ownership. Use resetValue only for synchronization such as native form reset, where restoring an uncontrolled baseline must not emit a user change.

Source

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