set(null) does not consistently remove multiple query states from the URL

[Gustavo-Wippel]

Hi! I’m facing an issue when clearing multiple Nuqs query states.
When calling set(null) to reset all filters, some values are removed successfully — but others remain in the URL, even though they should be cleared.

Example

Before clearing filters:
?situacao=CONFERENCIA%2CAPROVACAO&periodoCriacao=2025-11-03_2025-11-05

After calling set(null) on all query states:
?situacao=CONFERENCIA%2CAPROVACAO

periodoCriacao is cleared correctly, but situacao stays in the URL.
This does not happen only with situacao — this behavior can affect any filter, depending on the moment the cleanup happens.

Expected behavior

Calling set(null) for each query state should remove all corresponding query parameters.

After clearing, the URL should be empty or contain only the filters still intentionally set.

Actual behavior

Some filters are removed while others remain.

Inconsistent result when clearing multiple query states at once.

My Nuqs Context:

export const filtrosParsers = {
  aprovador: parseAsArrayOf(parseAsString).withDefault([]).withOptions({ clearOnDefault: true }),
  fluxos: parseAsArrayOf(parseAsString).withDefault([]).withOptions({ clearOnDefault: true }),
  motivos: parseAsArrayOf(parseAsString).withDefault([]).withOptions({ clearOnDefault: true }),
  situacao: parseAsArrayOf(parseAsString).withDefault([]).withOptions({ clearOnDefault: true }),
  empresas: parseAsArrayOf(parseAsString).withDefault([]).withOptions({ clearOnDefault: true }),
  centrosDeCusto: parseAsArrayOf(parseAsString)
    .withDefault([])
    .withOptions({ clearOnDefault: true }),
  termo: parseAsString.withDefault('').withOptions({ clearOnDefault: true }),
  pagina: parseAsInteger.withDefault(1),
  ordenacao: parseSelectOrderingAllowedValues
    .withDefault('data_criacao_desc')
    .withOptions({ clearOnDefault: true }),
  radioGroup: parseCheckBoxAllowedValues
    .withDefault('pendentesPraMim')
    .withOptions({ clearOnDefault: true }),
  periodoCriacao: parseAsDateRange.withOptions({ clearOnDefault: true }),
  periodoViagem: parseAsDateRange.withOptions({ clearOnDefault: true }),
} as const;

export const filtrosDefaults: FiltrosType = {
  aprovador: [] as string[],
  fluxos: [] as string[],
  motivos: [] as string[],
  situacao: [] as string[],
  empresas: [] as string[],
  centrosDeCusto: [] as string[],
  termo: '',
  pagina: 1,
  ordenacao: 'data_criacao_desc' as SelecteOrderingAllowedValues,
  radioGroup: 'pendentesPraMim' as CheckBoxAllowedValues,
  periodoCriacao: { start: null, end: null },
  periodoViagem: { start: null, end: null },
};

type FiltrosType = ReturnType<typeof useQueryStates<typeof filtrosParsers>>[0];
export type SetFiltrosType = ReturnType<typeof useQueryStates<typeof filtrosParsers>>[1];

interface NuqsContextType {
  urlValues: FiltrosType;
  setUrlValues: SetFiltrosType;
}

const NuqsContext = createContext<NuqsContextType | null>(null);

export const NuqsProvider = ({ children }: { children: React.ReactNode }) => {
  const [urlValues, setUrlValues] = useQueryStates(filtrosParsers);

  return (
    <NuqsContext.Provider value={{ urlValues, setUrlValues }}>{children}</NuqsContext.Provider>
  );
};
export const useNuqsContext = () => {
  const context = useContext(NuqsContext);
  if (!context) {
    throw new Error('useNuqsContext deve ser usado dentro de NuqsProvider');
  }
  return context;
};

Function that clear URL Values:

setUrlValues(filtrosDefaults); 

I’d like to know if this is expected behavior (batching, sync timing, ordering) or if it might be a bug when resetting multiple states simultaneously.

[franky47]

Thanks, I don't see a setState(null) in your example, would you be able to open an issue with a minimal reproduction please?