# Navigation redirect

> Route top-level navigations and the new-tab page using EP URL mappings, including built-in plugin pages.

Source: https://console.getchrovia.com/en/docs/sdk-navigation-redirect

**Entitlement:** `navigationRedirect`. **Configuration:** `internal.navigation_redirect`, an object mapping URL patterns to target strings. No JavaScript API is required.

## Configure mappings

```json
{
  "internal": {
    "navigation_redirect": {
      "https://example.com/old*": "https://example.org/",
      "https://example.com/blank*": ""
    }
  }
}
```

Merge into the [EP](https://console.getchrovia.com/en/docs/sdk-extended-preferences), sign if required, and restart. Navigating to `https://example.com/old-page` should load `https://example.org/`. An empty target means `about:blank`, not a network cancellation error.

Patterns match the full URL and are case-sensitive. `*` matches zero or more characters; `?` matches zero or one character. Escape a literal `?` with a backslash: a JSON mapping key such as `"https://example.com/old\\?mode=*"` matches the query separator literally. This is not regex or extension match-pattern syntax.

Targets are fixed URLs, not substitution templates; capture groups are not expanded. Non-string entries and invalid targets are skipped. Avoid overlapping mappings and redirect cycles rather than relying on JSON insertion order as a priority mechanism.

## Replace the new-tab page

Install a [Provision plugin](https://console.getchrovia.com/en/docs/sdk-plugins) named `my-plugin` containing `index.html`, then configure:

```json
{
  "internal": {
    "navigation_redirect": {
      "chrome://newtab/": "provision-extension://my-plugin/index.html"
    }
  }
}
```

Use `chrome://newtab/`, including the trailing slash, not `chrome://new-tab-page/`. In a Provision target, use the installed plugin's directory name and an existing page path; you do not need to hardcode an extension ID.

This avoids an extension-wide `chrome_url_overrides.newtab` manifest override when only selected EP-configured instances should use your page.

## Scope and boundaries

Rules apply to supported `chrome://` pages and top-level navigations, not iframe, image, or fetch requests. HTTP redirect destinations are not re-evaluated by these rules. If a top-level form submission matches, the replacement opens as a new navigation without the original POST body or referrer. Do not use it to forward submitted form data. Use [DNR](https://console.getchrovia.com/en/docs/sdk-declarative-net-request) or [network interception](https://console.getchrovia.com/en/docs/sdk-network-intercept) for request-level behavior.

A redirect is not a security allowlist. Do not assume every alternative URL or API path to a destination is blocked. The destination URL may appear in the address bar or restored session; the original URL is not guaranteed to remain visible.

## Verify

Test direct navigation, a link from a controlled web page, and a new tab separately. For a plugin target, inspect `chrome://extensions` and confirm its directory name and page file. Re-sign changed EP mappings and relaunch existing instances; editing a Provision EP seed does not update their local copies.