# @woocommerce/navigation

> WooCommerce navigation utilities.

Latest version **9.0.0** (published 2026-06-11) · GPL-2.0-or-later license · 0 weekly downloads

## Install

```sh
npm install @woocommerce/navigation
pnpm add @woocommerce/navigation
yarn add @woocommerce/navigation
bun add @woocommerce/navigation
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; high maintenance score; popular repo.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 9.0.0 |
| Published | 2026-06-11 |
| First published | 2018-11-15 |
| Weekly downloads | 0 |
| License | GPL-2.0-or-later |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | ^24.15.0 |
| Dependencies | 11 |
| Unpacked size | 49.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 10508 |
| Author | Automattic |
| Maintainers | mikejolley, albertjuhe, nerrad, obliviousharmony, louwie17, chihsuan, ~woocommerce, zhongruige, opr, kraftbj |
| Keywords | wordpress, woocommerce, navigation |

## Links

- npm: https://www.npmjs.com/package/@woocommerce/navigation
- Repository: https://github.com/woocommerce/woocommerce
- Homepage: https://github.com/woocommerce/woocommerce/tree/trunk/packages/js/navigation/README.md
- Issues: https://github.com/woocommerce/woocommerce/issues
- npm.io page: https://npm.io/package/@woocommerce/navigation

## Dependencies (11)

- [qs](https://npm.io/package/qs.md) ^6.11.2
- [history](https://npm.io/package/history.md) ^5.3.0
- [@wordpress/url](https://npm.io/package/@wordpress/url.md) 4.19.2
- [@wordpress/i18n](https://npm.io/package/@wordpress/i18n.md) 5.19.1
- [@wordpress/hooks](https://npm.io/package/@wordpress/hooks.md) 4.19.1
- [react-router-dom](https://npm.io/package/react-router-dom.md) ~6.3.0
- [@wordpress/compose](https://npm.io/package/@wordpress/compose.md) 7.19.2
- [@wordpress/element](https://npm.io/package/@wordpress/element.md) 6.19.1
- [@wordpress/notices](https://npm.io/package/@wordpress/notices.md) 5.19.2
- [@wordpress/api-fetch](https://npm.io/package/@wordpress/api-fetch.md) 7.19.2
- [@wordpress/components](https://npm.io/package/@wordpress/components.md) 29.5.4

## Alternatives

- [express-promise-router](https://npm.io/package/express-promise-router.md) — 736.1K weekly downloads
- [next-usequerystate](https://npm.io/package/next-usequerystate.md) — 29.8K weekly downloads
- [@bitkyc08/opencodex](https://npm.io/package/@bitkyc08/opencodex.md) — 4.6K weekly downloads
- [lynkr](https://npm.io/package/lynkr.md) — 575 weekly downloads
- [baremetal.js](https://npm.io/package/baremetal.js.md) — 42 weekly downloads

## Recent versions

- 9.0.0 (latest) — 2026-06-11
- 1.1.0 (next) — 2018-11-27
- 8.2.0 — 2024-06-11
- 8.1.0 — 2022-07-08
- 8.0.0 — 2022-06-15
- 7.0.1 — 2022-03-23
- 7.0.0 — 2022-02-21
- 6.1.0 — 2021-08-10
- 6.0.1 — 2021-04-16
- 6.0.0 — 2021-04-12
- 5.2.0 — 2020-11-10
- 5.1.1 — 2020-09-30
- 0.1.0 — 2020-09-30
- 5.1.0 — 2020-09-11
- 5.0.0 — 2020-08-04
- … 7 more at https://npm.io/package/@woocommerce/navigation/versions

## README

# Navigation

A collection of navigation-related functions for handling query parameter objects, serializing query parameters, updating query parameters, and triggering path changes.

## Installation

Install the module

```bash
pnpm install @woocommerce/navigation --save
```

## Usage

### getHistory

A single history object used to perform path changes. This needs to be passed into ReactRouter to use the other path functions from this library.

```jsx
import { getHistory } from '@woocommerce/navigation';

render() {
	return (
		<Router history={ getHistory() }>
			…
		</Router>
	);
}
```

### getPath() ⇒ <code>String</code>
Get the current path from history.

**Returns**: <code>String</code> - Current path.

### getTimeRelatedQuery(query) ⇒ <code>Object</code>
Gets time related parameters from a query.

**Returns**: <code>Object</code> - Object containing the time related queries.

| Param | Type | Description |
| --- | --- | --- |
| query | <code>Object</code> | Query containing the parameters. |

### getIdsFromQuery(queryString) ⇒ <code>Array</code>
Get an array of IDs from a comma-separated query parameter.

**Returns**: <code>Array</code> - List of IDs converted to an array of unique integers.

| Param | Type | Description |
| --- | --- | --- |
| queryString | <code>string</code> | string value extracted from URL. |

### getNewPath(query, path, currentQuery) ⇒ <code>String</code>
Return a URL with set query parameters.

**Returns**: <code>String</code> - Updated URL merging query params into existing params.

| Param | Type | Description |
| --- | --- | --- |
| query | <code>Object</code> | object of params to be updated. |
| path | <code>String</code> | Relative path (defaults to current path). |
| currentQuery | <code>Object</code> | object of current query params (defaults to current querystring). |

### getQuery() ⇒ <code>Object</code>
Get the current query string, parsed into an object, from history.

**Returns**: <code>Object</code> - Current query object, defaults to empty object.

### onQueryChange(param, path, query) ⇒ <code>function</code>
This function returns an event handler for the given `param`

**Returns**: <code>function</code> - A callback which will update `param` to the passed value when called.

| Param | Type | Description |
| --- | --- | --- |
| param | <code>string</code> | The parameter in the querystring which should be updated (ex `page`, `per_page`) |
| path | <code>string</code> | Relative path (defaults to current path). |
| query | <code>string</code> | object of current query params (defaults to current querystring). |

### updateQueryString(query, path, currentQuery)
Updates the query parameters of the current page.

| Param | Type | Description |
| --- | --- | --- |
| query | <code>Object</code> | object of params to be updated. |
| path | <code>String</code> | Relative path (defaults to current path). |
| currentQuery | <code>Object</code> | object of current query params (defaults to current querystring). |

### flattenFilters(filters) ⇒ <code>Array</code>
Collapse an array of filter values with subFilters into a 1-dimensional array.

**Returns**: <code>Array</code> - Flattened array of all filters.

| Param | Type | Description |
| --- | --- | --- |
| filters | <code>Array</code> | Set of filters with possible subfilters. |

### getActiveFiltersFromQuery(query, config) ⇒ <code>Array.&lt;activeFilters&gt;</code>
Given a query object, return an array of activeFilters, if any.

**Returns**: <code>Array.&lt;activeFilters&gt;</code> - - array of activeFilters

| Param | Type | Description |
| --- | --- | --- |
| query | <code>object</code> | query object |
| config | <code>object</code> | config object |

### getDefaultOptionValue(config, options) ⇒ <code>string</code> \| <code>undefined</code>
Get the default option's value from the configuration object for a given filter. The first option is used as default if no <code>defaultOption</code> is provided.

**Returns**: <code>string</code> \| <code>undefined</code> - - the value of the default option.

| Param | Type | Description |
| --- | --- | --- |
| config | <code>object</code> | a filter config object. |
| options | <code>array</code> | select options. |

### getQueryFromActiveFilters(activeFilters, query, config) ⇒ <code>object</code>
Given activeFilters, create a new query object to update the url. Use previousFilters to
Remove unused params.

**Returns**: <code>object</code> - - query object representing the new parameters

| Param | Type | Description |
| --- | --- | --- |
| activeFilters | <code>Array.&lt;activeFilters&gt;</code> | activeFilters shown in the UI |
| query | <code>object</code> | the current url query object |
| config | <code>object</code> | config object |

### getUrlKey(key, rule) ⇒ <code>string</code>
Get the url query key from the filter key and rule.

**Returns**: <code>string</code> - - url query key.

| Param | Type | Description |
| --- | --- | --- |
| key | <code>string</code> | filter key. |
| rule | <code>string</code> | filter rule. |

### activeFilter : <code>Object</code>
Describe activeFilter object.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| key | <code>string</code> | filter key. |
| [rule] | <code>string</code> | a modifying rule for a filter, eg 'includes' or 'is_not'. |
| value | <code>string</code> | filter value(s). |

---
_Source: https://npm.io/package/@woocommerce/navigation · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._