FrontendArmory
BlogDemoboardLearning Resources
FrontendArmory
BlogDemoboardLearning Resources
logoNavi

The Navigation object

Each Navi app has a navigation store that holds the app’s current route, and provides methods that allow you to navigate the user to a new route.

There are three ways to create a Navigation object:

  1. The <Router> component internally creates a navigation store if you don’t pass it a navigation prop.
  2. createBrowserNavigation() — for use within the browser.
  3. createMemoryNavigation() — for use on server and within tests.

When you’re not statically rendering your site, you’ll typically just use the <Router> component. If you need to access the navigation store created by <Router>, then you can access it through the useNavigation() hook or <NaviConsumer> component.

When you are statically rendering, testing, or just want a little more control, you can manually create your navigation object and pass it to your <Router> via its navigation prop.

Your navigation object

An Observable that manages your app’s navigation state.

navigation.extractState(): any

Returns the current value of window.history.state, or the in-memory copy when called from a Memory navigation.

This is useful when performing server-side rendering, as it allows any state produced by server-side routes to be extracted, serialized, and injected into the browser history via createBrowserHistory().

navigation.getCurrentValue(): Route

Returns the latest Route object that corresponds to the current URL — even if it is not yet fully ready.

navigation.getRoute(): Promise<Route>

Returns a promise to the fully loaded Route object that represents the current URL.

The returned promise will only resove once the Route object reaches its steady state for the current URL. To get the current Route object even before it reaches its steady state, use navigation.getCurrentValue().

navigation.goBack(): Promise<Route>

Equivalent to pressing the browser’s back button. Returns a promise that resolves to the route of the page that is navigated to.

navigation.goBack(): Promise<Route>

Equivalent to pressing the browser’s back button. Returns a promise that resolves to the route of the page that is navigated to.

navigation.navigate(url, options: {
  body?: any,
  headers?: { [name: string]: string },
  method?: string,
  replace?: boolean,
  state?: any,
}): Promise<Route>

Navigates to the provided URL using the History API. By default, it uses history.pushState(), but this is configurable through the replace option.

The navigation.navigation() function returns a Promise to the Route object of the URL that is navigated to, which is useful when using it to navigate in response to forms.

Options

body

The value that will be made available under request.body while processing the new URL.

headers

An object of HTTP headers that will be made available under request.headers while processing the new URL.

method

A HTTP method, like 'GET' or 'POST'. Defaults to 'GET’.

This will be made available on your route matchers under request.method. It is useful for writing code that handles form submittions on the client, in the same way as it would be handled on the server.

replace

A flag that indicates that the History API’s history.replaceState() function should be called instead of history.pushState().

state

A state object that can be stored with the URL, and will be remembered even if the user navigates with the back/forward buttons.

Where possible, prefer to set this using a state option for your route() calls, or with the withState() matcher.

navigation.setContext(context)

Updates the Routing Context that is passed to the navigation’s matchers.

navigation.subscribe(listener: route => void)

Registers a callback that will be called each time that the current route changes, i.e. whenever the value that would be returned by navigation.getCurrentValue() changes.

The callback will be called with the latest Route object.

While this function gives you low level access to Navi’s state, it’s rare that you’ll need to call it directly (unless you’re writing an integration). It’s far easier to subscribe through a component like <Router>.

createBrowserNavigation()

Use createBrowserNavigation() to create a navigation object that is linked to the browser’s history.

At minimum, you’ll need to pass in a matcher to routes. You’ll also often want to pass in a context object, which will be used as the initial value for your matcher’s Routing Context.

createBrowserNavigation(options: {
  /**
   * The Matcher that declares your app's routes.
   */
  routes: Matcher,

  /**
   * If provided, this part of any URLs will be ignored. This is useful
   * for mounting a Navi app in a subdirectory on a domain.
   */
  basename?: string,

  /**
   * The initial Context for your matchers.
   */
  context?: any,

  /**
   * You can supply a history object as output by react-router, allowing
   * Navi and react-router to be used within the same app.
   */
  history?: History,

  /**
   * Accepts the history.state of the Navigation object used to pre-render the
   * page on the server, as extracted with `navigation.extractState()`.
   */
  state?: any,

  /**
   * Configures whether trailing slashes on your URLs will be added or removed.
   * By default, they will be removed.
   */
  trailingSlash?: 'add' | 'remove' | null
})

Example

let navigation = createBrowserNavigation({
  // Your app's routes.
  routes,

  // The state of the server-rendered route.
  state: window.__NAVI_STATE__,
})

createMemoryNavigation()

Use createMemoryNavigation() to create a navigation object that is independent from any browser history. This is useful for server-side rendering and testing.

At minimum, you’ll need to pass in a routes Matcher and a url or request.

createMemoryNavigation(options: {
  /**
   * The Matcher that declares your app's routes.
   */
  routes: Matcher,

  /**
   * The initial URL or Request to match.
   */
  url?: string | Partial<URLDescriptor>,
  request?: {
    body?: any,
    headers?: { [name: string]: string },
    method?: HTTPMethod,
    url?: string | URLDescriptor,
  },

  /**
   * If provided, this part of any URLs will be ignored. This is useful
   * for mounting a Navi app in a subdirectory on a domain.
   */
  basename?: string,

  /**
   * The initial Context for your matchers.
   */
  context?: any,
})

Example

let navigation = createMemoryNavigation({
  routes,
  url: '/test',
})
Matchers« PreviousfunctionsNext »