Runed Documentation

For advanced control over how values are converted between URL strings and JavaScript types, use Zod codecs (Zod v4.1.0+). Codecs allow you to define bidirectional transformations via decode (URL string $\rightarrow$ JS type) and encode (JS type $\rightarrow$ URL string).

Common Use Cases:

• Compact IDs: Storing numbers as base36 strings.
• Unix Timestamps: Storing dates as integers for smaller URLs.
• Custom Date Formats: Any non-standard string format.
• Complex Conversions: Mapping IDs to full objects or vice-versa.

Codecs work automatically with both useSearchParams on the client and validateSearchParams on the server.

import { z } from "zod";

// Example: Unix timestamp codec
const unixTimestampCodec = z.codec(
	z.coerce.number(), // Input: number from URL string
	z.date(), // Output: Date object in your app
	{
		decode: (timestamp) => new Date(timestamp * 1000),
		encode: (date) => Math.floor(date.getTime() / 1000)
	}
);

// Using it in a schema
const searchSchema = z.object({
	createdAfter: unixTimestampCodec.default(new Date("2024-01-01")),
});

The onClickOutside function returns a control object that allows you to programmatically enable or disable the listener. This is useful for components like <dialog> elements where you only want to listen for outside clicks while the component is visible.

Control Methods

• start(): Enables the listener.
• stop(): Disables the listener.
• enabled: A reactive, read-only property indicating the current status of the listener.

To use controlled mode, set the immediate option to false in the configuration object.

<script lang="ts">
	import { onClickOutside } from "runed";

	let dialog = $state<HTMLDialogElement>()!;

	const clickOutside = onClickOutside(
		() => dialog,
		() => {
			dialog.close();
			clickOutside.stop();
		},
		{ immediate: false }
	);

	function openDialog() {
		dialog.showModal();
		clickOutside.start();
	}

	function closeDialog() {
		dialog.close();
		clickOutside.stop();
	}
</script>

<button onclick={openDialog}>Open Dialog</button>
<dialog bind:this={dialog}>
	<div>
		<button onclick={closeDialog}>Close Dialog</button>
	</div>
</dialog>

useSearchParams provides top-level reactivity only. This means that while direct property assignments trigger URL updates, nested mutations do not.

✅ What works (Direct assignment)

Directly assigning a value to a property on the returned object will trigger a URL update:

<script>
	const params = useSearchParams(schema);

	// These trigger URL updates
	params.page = 2;
	params.filter = "active";
	params.config = { theme: "dark", size: "large" };
	params.items = [...params.items, newItem];
</script>

❌ What doesn't work (Nested mutations)

Mutating properties inside objects or arrays, or using array methods, will not trigger URL updates:

<script>
	const params = useSearchParams(schema);

	// These DON'T trigger URL updates
	params.config.theme = "dark"; // Nested object property
	params.items.push(newItem); // Array method
	params.items[0].name = "updated"; // Array item property
	delete params.config.oldProp; // Property deletion
</script>

You can control how Date parameters are serialized in URLs using two methods:

Method 1: Using dateFormat in createSearchParamsSchema Set dateFormat to 'date' for YYYY-MM-DD or 'datetime' (default) for full ISO8601.

Method 2: Using dateFormats option in useSearchParams This works with any validation library (Zod, Valibot, etc.). Pass an object mapping field names to 'date' or 'datetime'.

• 'date' format: Serializes as YYYY-MM-DD. Parsed as a Date object with time set to midnight UTC.
• 'datetime' format: Serializes as full ISO8601. Preserves exact time information.

// Option 1: In schema
const schema = createSearchParamsSchema({
	birthDate: { type: "date", default: new Date("1990-01-15"), dateFormat: "date" }
});

// Option 2: In useSearchParams options
const params = useSearchParams(zodSchema, {
	dateFormats: {
		birthDate: "date",
		createdAt: "datetime"
	}
});

When using PersistedState with complex objects, only plain structures are deeply reactive. This includes arrays, plain objects, and primitive values.

Note: Class instances are not deeply reactive. Modifying a property on a class instance will NOT persist the change. To persist changes to a class instance, you must re-assign the entire instance to .current.

const persistedArray = new PersistedState("foo", ["a", "b"]);
persistedArray.current.push("c"); // This will persist the change

const persistedObject = new PersistedState("bar", { name: "Bob" });
persistedObject.current.name = "JG"; // This will persist the change

class Person {
	name: string;
	constructor(name: string) {
		this.name = name;
	}
}
const persistedComplexObject = new PersistedState("baz", new Person("Bob"));
// The following will NOT persist:
persistedComplexObject.current.name = "JG"; 
// The following WILL persist:
persistedComplexObject.current = new Person("JG");