Demo |Mirror link

URI size limitation,up to 12KB is safe

Add a andfollow me to support the project!

Will appreciate you feedback/opinion ondiscussions

Share if it useful for you.X.comLinkedInFBVK

Why usestate-in-url?

Use cases

Features

Table of content

installation

1. Install package

# npmnpm install --save state-in-url# yarnyarn add state-in-url# pnpmpnpm add state-in-url

2. Edit tsconfig.json

useUrlState

useUrlState hook for Next.js

Usage examples

Basic

// userState.ts// Only parameters with value different from default will go to the url.exportconstuserState:UserState={name:'',age:0}// use `Type` not `Interface`!typeUserState={name:string,age:number}

'use client'import{useUrlState}from'state-in-url/next';import{userState}from'./userState';functionMyComponent(){// can pass `replace` arg, it's control will `setUrl` will use `rounter.push` or `router.replace`, default replace=true// can pass `searchParams` from server components, pass `useHistory: false` if you need to fetch smt in the server componentconst{ urlState, setUrl, setState, reset}=useUrlState(userState);return(<div>// urlState.name will return default value from `userState` if url empty<inputvalue={urlState.name}// same api as React.useState, e.g. setUrl(currVal => currVal + 1)onChange={(ev)=>setUrl({name:ev.target.value})}/><inputvalue={urlState.age}onChange={(ev)=>setUrl({age:+ev.target.value})}/><inputvalue={urlState.name}onChange={(ev)=>{setState(curr=>({ ...curr,name:ev.target.value}))}}// Can update state immediately but sync change to url as neededonBlur={()=>setUrl()}/><buttononClick={reset}>Reset</button></div>)}

Custom hook to work with slice of state conveniently

With complex state shape

Update state only and sync to URL manually

With server side rendering

Using hook inlayout component

With arbitrary state shape (not recommended)

useUrlState hook for React-Router

Example

exportconstform:Form={name:'',age:undefined,agree_to_terms:false,tags:[],};typeForm={name:string;age?:number;agree_to_terms:boolean;tags:{id:string;value:{text:string;time:Date}}[];};

import{useUrlState}from'state-in-url/react-router';import{form}from'./form';functionTagsComponent(){const{ urlState, setUrl, setState}=useUrlState(form);constonChangeTags=React.useCallback((tag:(typeoftags)[number])=>{setUrl((curr)=>({        ...curr,tags:curr.tags.find((t)=>t.id===tag.id)          ?curr.tags.filter((t)=>t.id!==tag.id)          :curr.tags.concat(tag),}));},[setUrl],);return(<div><Fieldtext="Tags"><divclassName="flex flex-wrap gap-2">{tags.map((tag)=>(<Tagactive={!!urlState.tags.find((t)=>t.id===tag.id)}text={tag.value.text}onClick={()=>onChangeTags(tag)}key={tag.id}/>))}</div></Field><inputvalue={urlState.name}onChange={(ev)=>{setState(curr=>({ ...curr,name:ev.target.value}))}}// Can update state immediately but sync change to url as neededonBlur={()=>setUrl()}/></div>);}consttags=[{id:'1',value:{text:'React.js',time:newDate('2024-07-17T04:53:17.000Z')},},{id:'2',value:{text:'Next.js',time:newDate('2024-07-18T04:53:17.000Z')},},{id:'3',value:{text:'TailwindCSS',time:newDate('2024-07-19T04:53:17.000Z')},},];

Other hooks and helpers

useUrlStateBase hook for others routers

useSharedState hook for React.js

'use client'import{useSharedState}from'state-in-url';exportconstsomeState={name:''};functionSettingsComponent(){const{ state, setState}=useSharedState(someState);}

useUrlEncode hook for React.js

encodeState anddecodeState helpers

encode anddecode helpers

Best Practices

typeUserState={name:string;age:number;other:{id:string,value:number}[]};constuserState={name:'',age:0,other:[],};exportconstuseUserState=()=>{const{ urlState, setUrl, reset}=useUrlState(userState);// other logic// reset query params when navigating to other pageReact.useEffect(()=>{returnreset},[])return{userState:urlState,setUserState:setUrl};;}

Gotchas

Other

Contribute and/or run locally

Roadmap

Contact & Support

Changelog

License

Inspiration