URL State Management

Cubitt components can mirror their state to TanStack Router search params through Cubitt's shared URL-state hooks. This gives you shareable URLs, bookmarkable states, and browser navigation that stays aligned with the UI without wiring every component manually.

Requirements

Cubitt URL state requires TanStack Router context. If your app already uses TanStack Start or TanStack Router, there is no extra adapter to install.

app/root.tsx

import { RouterProvider } from "@tanstack/react-router";
import { router } from "./router";

export function App() {
  return <RouterProvider router={router} />;
}

Type-safe `paramName` keys

Cubitt narrows paramName from your registered TanStack Router route tree.

TanStack Start / file-based routing: route generation usually handles this automatically.
Effect in Cubitt: built-in URL-state components can validate paramName at compile time, offer autocomplete for known keys, and stay safe through route refactors.

That means this:

<Input paramName="search" />

is not just a string prop in a properly registered app. TypeScript can:

suggest known search keys in autocomplete
reject invalid param names at compile time
keep those usages in sync if you rename a search key in the route tree

If paramName is only typed as plain string in your app, the usual cause is missing TanStack Router registration. In TanStack Start/file-based apps, check that your generated route types are present. In manual router setups, add the standard TanStack Router Register declaration once in your app.

Escape hatch for unregistered keys

If you intentionally need a query key that is not part of your registered route tree, wrap it with untypedUrlStateParamName(...).

import {
  Input,
  untypedUrlStateParamName,
} from "@tilt-legal/cubitt-components";

<Input paramName={untypedUrlStateParamName("debug-panel")} />;

Lost type safety

untypedUrlStateParamName(...) opts that callsite out of TanStack Router key checking. You lose autocomplete for known keys and TypeScript can no longer catch typos or route-search refactors for that parameter. Prefer fixing router registration first and use this only for deliberate exceptions.

Validation model

Cubitt intentionally splits URL-state responsibilities:

Cubitt codecs parse and serialize the individual URL parameter value.
Your route validateSearch owns full-object validation, transforms, and defaults.

That keeps Cubitt route-agnostic while still giving strong typing and app-level search validation.

Basic usage

Add URL state to any supported component by providing a paramName:

<Input paramName="search" placeholder="Search..." />

When the user types, the URL updates to ?search=hello and the input value stays synchronized with that parameter.

Option	Type	Description	Default
`paramName`	`string`	URL parameter name. Narrows to known search keys when your router is registered.	-
`paramMatchValue`	`string`	Open only when the URL value matches this string	-
`onUrlValueChange`	`function`	Callback when the parameter value changes	-
`paramClearOnDefault`	`boolean`	Remove the parameter when the component returns to default	`true`
`paramThrottle`	`number`	Throttle URL writes in milliseconds	-
`paramDebounce`	`number`	Debounce URL writes in milliseconds	-

Option	Type	Description	Default
`paramName`	`string`	URL parameter name. Narrows to known search keys when your router is registered.	-
`paramSetValue`	`string`	Value to set in the URL when triggered	-
`paramThrottle`	`number`	Throttle URL writes in milliseconds	-
`paramDebounce`	`number`	Debounce URL writes in milliseconds	-

Option	Type	Description	Default
`paramName`	`string`	URL parameter name. Narrows to known search keys when your router is registered.	-
`paramValue`	`T`	Controlled value for the URL parameter	-
`paramCodec`	`UrlStateCodec<T>`	Custom codec for advanced values or custom parsing	auto
`onUrlValueChange`	`function`	Callback when the parameter value changes	-
`paramClearOnDefault`	`boolean`	Remove the parameter when the value equals default	`true`
`paramThrottle`	`number`	Throttle URL writes in milliseconds	-
`paramDebounce`	`number`	Debounce URL writes in milliseconds	-

Custom value shapes

Most primitives auto-select a codec from the value type:

string → stringCodec
boolean → booleanCodec
number → numberCodec
string[] → stringArrayCodec
number[] → numberArrayCodec

For custom payloads, pass paramCodec with createJsonCodec.

import { createJsonCodec } from "@tilt-legal/cubitt-components/utilities/hooks";

const filtersCodec = createJsonCodec<MyFilterState>((value) =>
  isValidFilterState(value) ? value : null
);

<SomeCustomComponent paramName="filters" paramCodec={filtersCodec} />;

Custom components

If you're building your own primitives or wrappers, use the shared hooks directly:

URL State Management

Dialog

Sheet

AlertDialog

Button

MenuItem

Input

Textarea

TagInput

Select

Combobox

RadioGroup

Tabs

Accordion

Pagination

Stepper

Checkbox

Switch

Toggle

ToggleGroup

Slider

DataTable Search

DataTable Column Visibility

On this page