Guide

History

Choose which writes add a back-button entry with historyMode.

Writes replace the current history entry by default, so typing in a search box does not fill the back button with one entry per keystroke. Ask for push where pressing Back should undo the change, such as moving between steps or opening a record.

/guide/history

historyMode: 'replace'

0

historyMode: 'push'

0

Click both a few times, then press Back.
const 
replaced
=
useQueryState
('replaced',
numberCodec
({
default
: 0 }))
const
pushed
=
useQueryState
('pushed',
numberCodec
({
default
: 0,
historyMode
: 'push' }))

Where to set it

LevelHowApplies to
One valuehistoryMode in the codec optionsWrites that change that key
One grouphistoryMode on useQueryStatesWrites from that group, unless a codec sets its own
The appdefaultHistoryMode on the clientEvery write that does not set a mode

When writes with different modes land in the same tick, the single navigation is a push. One push wins over any number of replaces.

An app-wide default

To make push the default, register the client once, before your components run. In a Vue app, do it right after creating the router:

import { 
QueryStateClient
,
registerQueryStateClient
} from '@chronicstone/vue-route-query'
import {
createRouter
,
createWebHistory
} from 'vue-router'
const
router
=
createRouter
({
history
:
createWebHistory
(),
routes
: [] })
registerQueryStateClient
(
router
, new
QueryStateClient
({
router
,
defaultHistoryMode
: 'push' }))

In Nuxt, do the same in a plugin:

plugins/query-state.ts
import { QueryStateClient, registerQueryStateClient } from '@chronicstone/vue-route-query'

export default defineNuxtPlugin(() => {
  const router = useRouter()
  registerQueryStateClient(router, new QueryStateClient({ router, defaultHistoryMode: 'push' }))
})
Copyright © 2026 Cyprien Thao. Released under the MIT License.