Repository files navigation

kit-query-params is a lightweight query params state management library for SvelteKit that simplifies state management and URL synchronization. It provides a seamless way to keep your application state in sync with URL search parameters, enhancing user experience and enabling easy sharing of application states.

Key features:

• Works like a normal state in svelte 5 : reactive, mutable and without using the boxed value pattern.
• Automatic URL synchronization: State changes are reflected in the URL, making it easy to share and bookmark specific application states.
• Handlesstring,number,date,boolean andenum as primitives, arrays of primitives, arrays of objects and nested objects.
• Type safe and runtime safe: Define your state structure with a simple schema, ensuring type safety throughout your application.
• Reactive state management: Utilizes Svelte's reactive state system for efficient updates and rendering.
• Customizable debounce: Control the frequency of URL updates to optimize performance.
• History management: Choose between pushing new history entries or replacing the current one.
• Clean URL handling: Automatically removes empty values from the URL to keep it tidy.
• Can preserve unknown params (not defined in the schema).

npm install kit-query-params

pnpm install kit-query-params

bun install kit-query-params

Create a state with the queryParams function. You need to pass a schema of the parameters you want to use. The type of the state will be infered from the schema.The state is a like a normal state in svelte 5. It is reactive and you can mutate or update its properties.

Every mutation will be reflected in the url search params.You can use thedebounce option to customize the time between each update.

Each update will trigger a navigation by default but you can use theshallow option to prevent it.

You can use thepushHistory option to control if you want to push a new history entry or replace the current one. By default it will not push a new history entry.

The library will try its best to keep the url clean by removing empty strings, null values and so on.

<scriptlang="ts">import {queryParamsState }from'kit-query-params';const queryParams=queryParamsState({schema: {search:'string',tags: ['number']}});</script><buttononclick={()=> {queryParams.tags.push(queryParams.tags.length+1);}}>Add tag</button><inputbind:value={queryParams.search} />{JSON.stringify(queryParams)}

ThequeryParamsState function accepts an options object. Here's a table describing the available options:

The schema is a simple object that defines the structure of the URL parameters. It is an object where the keys are the parameter names and the values are the types.

Primitive types are:string,number,date,boolean andenum.

You can define arrays of primitives and arrays of objects.

Objects can be nested and can be of any type.

constschema={search:'string',new:'boolean',startDate:'date',count:'number',enum:'<blue,green,red>'};

constschema={// Define an object with nested objectsuser:{language:'<en,fr,es>'name:'string',address:{street:'string',city:'string',zip:'string'}},// Define an array of strings (can be any other primitive: boolean, number, date)tags:['string'],// Define an array of objects (objects inside arrays can also be nested)friends:[{name:'string',age:'number'}]};

thequeryParamsState function returns a proxy reflecting the defined schema that also contains:

• a$reset function to clear the search params (it will also clear the unknown params in the url if you setpreserveUnknownParams tofalse)
• a$queryParams property that is the underlyingSvelteURLqueryParams reactive URLqueryParams
• a$sync method to manually update the url

kit-query-params also exports aparseURL function. This function can be used to parse the URL parameters into a typed object. It can be usefull inside theload function of a route.

import{parseURL}from'kit-query-params';exportconstload=({ url})=>{constqueryParams=parseURL(url,{search:'string',tags:['number']});constresult=awaitapi.getCustomers({search:queryParams.search,// search is of type string | nulltags:queryParams.tags// tags is of type number[]});return{result};};

This project is licensed under the MIT License.This README provides a comprehensive introduction to your library, installation instructions, and usage examples covering the main functionalities. It also includes sections on advanced usage and error handling. You may want to adjust the project name, installation instructions, and license information to match your specific project details.