useUrlControlledString
Controlled string inputs mirrored in the URL.
Use useUrlControlledString for search bars and toolbars where the value is controlled but should still mirror URL state.
This hook is useful when a component already owns a controlled string value, but you still want that value reflected in TanStack Router search params.
Usage
import { useUrlControlledString } from "@tilt-legal/cubitt-components/utilities/hooks";
export function ToolbarSearch() {
const [value, setValue] = useUrlControlledString({
paramName: "files-search",
defaultValue: "",
});
return (
<input
value={value}
onChange={(event) => setValue(event.target.value)}
/>
);
}Router registration
When your app registers its TanStack Router, paramName narrows to known search keys from the route tree. TanStack Start/file-based apps usually get this automatically. Without registration, it remains a plain string.
API
| Option | Type | Description | Default |
|---|---|---|---|
paramName | string | URL parameter name. Narrows to known search keys when your router is registered. | - |
value | string | Controlled value (overrides internal and URL state) | - |
defaultValue | string | Default value when uncontrolled | "" |
onChange | (value: string) => void | Callback when the value changes | - |
paramDefaultValue | string | URL default value (defaults to defaultValue) | - |
paramClearOnDefault | boolean | Remove the parameter when value equals default | true |
paramThrottle | number | Throttle URL writes in milliseconds | - |
paramDebounce | number | Debounce URL writes in milliseconds | - |
onUrlValueChange | (value: string | null) => void | Callback when the URL value changes | - |