Query state boolean default to true: does not init url + calling setter with false does put false in url

[remi-van]

Context

What's your version of nuqs?

"nuqs": "^2.4.3",

What framework are you using?

• ❌ Next.js (app router)
• ❌ Next.js (pages router)
• ❌ React SPA (no router)
• ❌ Remix
• ✅ React Router
• ❌ Other (please specify)

Which version of your framework are you using?

"react": "^19.0.0",
"react-router": "^7.5.2",

Description

When initializing query state boolean to true (useQueryState("bool", parseAsBoolean.withDefault(true))), setting value to false (setBool(false)) will update the url params bool=false, and won't when setting it to true (empty url params). The behavior is inverted, it should update the url for true, not false.

Expected: When default boolean query state to true, it should update the url with the query param.

Reproduction

Cannot provide reproduction, because on stackblitz, it seems it doesn't update the URL when setting query state. (https://stackblitz.com/edit/vitejs-vite-qp7k4iak)

[franky47]

This is working as intended: by default, nuqs does not write the default value to the URL (this can be changed by setting the clearOnDefault option to false).

If your boolean is true by default (ie: when the URL is empty), then false values should be explicitly listed in the URL.

For the behaviour you described (empty URL means false, and explicit values being interpreted as such), you should set .withDefault(false).

[remi-van]

@franky47 Thanks for the quick answer!

I'm not sure I can have that. Here is the scenario:

const [date, setDate] = useQueryState("date", parseAsIsoDate)
const hasDate = Boolean(date)
const [isLiveData, setIsLiveData] = useQueryState("live", parseAsBoolean.withDefault(!hasDate))
// If there is no date, it is defaulted to "live" data

Later when I run setIsLiveData(!isLiveData) it will write live=false in the params. I think this is a bug, false should not be written in the params, right?
And the same goes the opposite. If I setIsLiveData(true) with useQueryState("live", parseAsBoolean.withDefault(true)), it won't write live=true in the params, that is a bug too I believe. It should set the params when the boolean query state is true, isn't it?

It's kind of counter intuitive that the boolean value in the search params isn't reflecting the boolean in the state.

[franky47]

It looks like you have dependent state, which opens the question: what would these URLs do / do they make sense?

• ?date=2020-01-01&live=true
• ?date=2020-01-01&live=false
• ?date=2020-01-01
• ?live=true
• ?live=false

The general recommendation with URL state is to keep it as descriptive as possible, reducing the meaning of search params to a pure declaration (ie: not depend on other things).
Otherwise it gets difficult to maintain over time and creates entry points into your app with possibly conflicting values.

In any case, coming back to default values:

• withDefault(false) seems the most logical: if the value is missing, it means false, otherwise it means whatever it contains (true or false).
• withDefault(true) means if there is no value, then the state is true, and if there is it follows what it contains (true or false)
• In both cases, the default value is not written to the URL when set, unless you set the clearOnDefault option to false.

TL;DR: booleans should likely have a false default value as it seems more logical when reading the URL (opt-in), and URL state should be isolated, declarative and side-effects free to be maintainable.

[remi-van]

That's a good point. I can use a sort-of derived state for isLiveData based on the date being present or not.

So I went with:

const [date, setDate] = useQueryState("date", parseAsIsoDate)
const [isLiveData, setIsLiveData] = useState(date === null)

TL;DR: booleans should likely have a false default value as it seems more logical when reading the URL

I have a good solution for my problem. But it still feels confusing to have a queryState that contains the opposite value than the one in the url, when default value is true. As well as having a different behavior depending on the default boolean value (the url will either write "bool=true" or "bool=false" depending on the default).