#@guanriyue/decurl

The default @guanriyue/decurl entry provides ready-to-use React Router hooks. They read the current React Router location and navigate inside the hook, so you do not need to place a Provider manually.

import { useSearchValue, useSearchValues } from '@guanriyue/decurl';

The default hooks use the default singleton search store. For applications with one React Router runtime, this is usually enough.

These hooks must run inside a React Router context, such as BrowserRouter, RouterProvider, or another React Router runtime.

If you need to explicitly provide a store, configure store behavior, or reduce direct dependency on React Router useLocation, see @guanriyue/decurl/provided.

#useSearchValues

useSearchValues(searchFields) reads and updates multiple search values.

useSearchValues(searchFields): [values, setValues]

Parameters:

Returns:

import { useSearchValues } from '@guanriyue/decurl';

const SearchPanel = () => {
  const [values, setValues] = useSearchValues(searchFields);

  return (
    <button
      type="button"
      onClick={() => {
        setValues({ page: values.page + 1 });
      }}
    >
      Next page
    </button>
  );
};

setValues(patch, options?) accepts a patch. It only updates fields included in the patch, and leaves other fields unchanged. By default, it writes back to the URL with { replace: true }.

Passing null or undefined deletes the corresponding URL key. If the written value equals the field defaultValue, the key is also deleted by default; whether to preserve default values is controlled by the URLSearchParams codec encode rules.

If the whole patch is undefined, Decurl deletes every URL key represented by the current searchFields and preserves search params outside those fields:

setValues(undefined);

The patch can also be an updater:

setValues((previousValues) => ({
  page: previousValues.page + 1,
}));

If the updater returns undefined, it has the same semantics as setValues(undefined).

#useSearchValue

useSearchValue(codec) reads and updates a single field. The codec must already have a fixed name, usually from the return value of defineFields.

useSearchValue(codec): [value, setValue]

Parameters:

Returns:

import { useSearchValue } from '@guanriyue/decurl';

const PageButton = () => {
  const [page, setPage] = useSearchValue(searchFields.page);

  return (
    <button
      type="button"
      onClick={() => {
        setPage(page + 1);
      }}
    >
      Next page
    </button>
  );
};

setValue(patch, options?) also supports a direct value or an updater. By default, it writes back to the URL with { replace: true }.

Passing null or undefined deletes the URL key represented by the field. If the written value equals the field defaultValue, the key is also deleted by default.

setPage((previousPage) => previousPage + 1);

#Render Behavior

The default hooks read React Router location inside the hook. Some route updates may cause components to re-render with React Router. If you need to centralize React Router capability access in a separate component or observe the related render boundary, see @guanriyue/decurl/provided and Provided Runtime.

#Navigate Options

The second setter argument is passed through to React Router navigate. Decurl uses replace: true by default to avoid writing frequent search params updates into many history entries.

setPage(1, { replace: true, preventScrollReset: true });

If multiple setter calls happen before the same flush, the navigate options from the last call override the defaults.

#SearchProvider

SearchProvider provides an independent search store and can configure store options. Default hooks first read the nearest SearchProvider store; without a Provider, they use the default global store.

import { SearchProvider } from '@guanriyue/decurl';

<SearchProvider flushDelay={80} flushMode="debounce">
  <App />
</SearchProvider>

SearchProvider only provides the store. It does not read React Router location or navigate. Default hooks read React Router capabilities by themselves; provided hooks need to be used with SearchRuntimeConnector.

#Types

#Related

• @guanriyue/decurl/provided
• @guanriyue/decurl/codec
• React Router Integration Overview