sveltekit-search-params

You can pass a configuration object to customize the behavior of your search parameter stores.

Note on placement:

• For queryParam, pass the config as the third argument.
• For queryParameters, pass the config as the second argument.

Available Options:

• debounceHistory (number): Milliseconds to delay writing to history. Useful for text inputs to avoid a history entry for every keystroke. Defaults to 0.
• pushHistory (boolean): If false, the URL updates but no new entries are added to the browser history stack (user cannot use 'Back').
• sort (boolean): Whether to sort search parameters in the URL for better cache-ability. Defaults to true. This is per-store.
• showDefaults (boolean): If true (default), the library redirects to the URL containing the default value immediately on load. If false, the store holds the default value but the URL remains clean.
• equalityFn (function): A custom function (current, next) => boolean to prevent unnecessary reactivity for complex objects/arrays. It is not used for primitive values. By default, it uses JSON.stringify.

<script lang="ts">
	import { ssp, queryParameters, queryParam } from 'sveltekit-search-params';

	// Using queryParam with config (3rd argument)
	const name = queryParam('name', ssp.string(), {
		debounceHistory: 500,
	});

	const count = queryParam('count', ssp.number(), {
		debounceHistory: 1500,
	});

	// Using queryParameters with config (2nd argument)
	const store = queryParameters(
		{
			username: true,
			isCool: ssp.boolean(true),
		},
		{
			pushHistory: false,
		},
	);
</script>

The queryParameters function accepts a configuration object as its second argument to control how URL updates interact with the browser history and how default values are displayed.

Options

• debounceHistory (number): The delay in milliseconds before writing to history. Useful for text inputs to prevent every keystroke from creating a new history entry. Defaults to 0.
• pushHistory (boolean): If false, the URL updates but no new entries are added to the browser's history stack (the user cannot use the 'Back' button to undo the change).
• sort (boolean | false): By default, search parameters are sorted to improve cache-ability. Set to false to disable sorting. Note that this setting is per-object; interacting with a non-sorting object and then a sorting object will still result in a sorted URL.
• showDefaults (boolean): If true (default), the library immediately navigates to the URL containing default values if they are missing. If false, the parameter will hold the default value in state, but the URL will not be updated to show it.

<script lang="ts">
	import { ssp, queryParameters } from 'sveltekit-search-params';
	const params = queryParameters(
		{
			username: true,
			isCool: ssp.boolean(true),
		},
		{
			debounceHistory: 500, // url will change after 500ms
			pushHistory: false, // no new history entries for this object
		},
	);
</script>

The queryParameters function is the primary way to interact with search parameters.

• Reading: Calling queryParameters() without arguments returns an object containing all current search parameters as strings.
• Writing: The returned object is reactive. Updating a property on this object (e.g., params.username = 'new_value') will automatically update the URL.

Example: Basic usage and writing to the store

<script lang="ts">
	import { queryParameters } from 'sveltekit-search-params';

	const params = queryParameters();
</script>

<input
	value={params.username}
	oninput={(e) => {
		params.username = e.target.value;
	}}
/>

<script lang="ts">
	import { queryParameters } from 'sveltekit-search-params';

	const params = queryParameters();
</script>

<pre>
    {JSON.stringify(params, null, 2)}
</pre>
<input
	value={params.username}
	oninput={(e) => {
		params.username = e.target.value;
	}}
/>

You can pass a configuration object to queryParameters to define which parameters you expect. This ensures they are present in the returned object even if they are missing from the URL.

• Expected parameters: Pass a key with the value true to include it in the object (it will be null if not in the URL).
• Default values: Use the defaultValue property within a parameter's configuration object to provide a fallback. When a default value is used, the URL will be updated to include this parameter once the client-side bundle loads.

Warning: Because goto cannot run on the server, if the page is server-side rendered, the object will show the default value, but the actual URL navigation will only occur once the client-side code executes.

Example

<script lang="ts">
	import { queryParameters } from 'sveltekit-search-params';

	const params = queryParameters({
		username: true,
		count: {
			encode: (value: number) => value.toString(),
			decode: (value: string | null) => (value ? parseInt(value) : null),
			defaultValue: 10,
		},
	});
</script>