history API Reference#

This is the API reference for the history JavaScript library. The source code is TypeScript, but it is compiled to JavaScript before publishing. The function signatures in this reference all include their TypeScript type annotations for conciseness and clarity.

Although there are several APIs in the history library, the main interfaces are:

createBrowserHistory({ window?: Window })#

Returns a BrowserHistory instance for the given window, which defaults to the defaultView of the current document.

import { createBrowserHistory } from 'history';
let history = createBrowserHistory();

See the Getting Started guide for more information.

createHashHistory({ window?: Window })#

Returns a HashHistory instance for the given window, which defaults to the defaultView of the current document.

import { createHashHistory } from 'history';
let history = createHashHistory();

See the Getting Started guide for more information.

createMemoryHistory({ initialEntries?: InitialEntry[], initialIndex?: number })#

Returns a MemoryHistory instance.

import { createMemoryHistory } from 'history';
let history = createMemoryHistory();

You can provide initial entries to this history instance through the initialEntries property, which defaults to ['/'] (a single location at the root / URL). The initialIndex defaults to the index of the last item in initialEntries.

type InitialEntry = Path | LocationPieces;

See the Getting Started guide for more information.

History#

A history object is similar to a web browser's window.history instance but with a smaller API. history objects maintain a "stack" of location objects that represent a user's browsing history.

A history object has the following interface:

interface History<S extends State = State> {
  readonly action: Action;
  readonly location: Location<S>;
  createHref(to: To): string;
  push(to: To, state?: S): void;
  replace(to: To, state?: S): void;
  go(n: number): void;
  back(): void;
  forward(): void;
  listen(listener: Listener<S>): () => void;
  block(blocker: Blocker<S>): () => void;
}


interface Listener<S extends State = State> {
  (update: Update<S>): void;
}


interface Update<S extends State = State> {
  action: Action;
  location: Location<S>;
}


interface Blocker<S extends State = State> {
  (tx: Transition<S>): void;
}


interface Transition<S extends State = State> extends Update<S> {
  retry(): void;
}

history.action#

The current (most recent) Action that modified the history stack.

history.location#

The current Location.

history.createHref(to: To)#

Returns a string suitable for use as an <a href> value that will navigate to the given destination.

history.push(to: To, state?: State)#

Pushes a new entry onto the stack.

See the Navigation guide for more information.

history.replace(to: To, state?: State)#

Replaces the current entry in the stack with a new one.

See the Navigation guide for more information.

history.go(delta: number)#

Navigates back/forward by delta entries in the stack.

See the Navigation guide for more information.

history.back()#

Goes back one entry in the history stack. Alias for history.go(-1).

See the Navigation guide for more information.

history.forward()#

Goes forward one entry in the history stack. Alias for history.go(1).

See the Navigation guide for more information.

history.listen(listener: Listener)#

Starts listening for location changes and calls the given callback when it does.

// To start listening for location changes...
let unlisten = history.listen(({ action, location }) => {
  // The current location changed.
});

// Later, when you are done listening for changes...
unlisten();

See the Getting Started guide for more information.

history.block(blocker: Blocker)#

Prevents changes to the history stack from happening. This is useful when you want to prevent the user navigating away from the current page for some reason.

// To start blocking location changes...
let unblock = history.block(({ action, location, retry }) => {
  // A transition was blocked!
});

// Later, when you want to start allowing transitions again...
unblock();

See the guide on Blocking Transitions for more information.

Location#

A location is a particular entry in the history stack, usually analogous to a "page" or "screen" in your app. As the user clicks on links and moves around the app, the current location changes.

A location object has the following interface:

interface Location {
  pathname: string;
  search: string;
  hash: string;
  state: State;
  key: string;
}

location.pathname#

The location.pathname property contains an initial / followed by the remainder of the URL up to the ?.

See also URL.pathname.

location.search#

The location.search property contains an initial ? followed by the key=value pairs in the query string. If there are no parameters, this value may be the empty string (i.e. '').

See also URL.search.

location.hash#

The location.hash property contains an initial # followed by fragment identifier of the URL. If there is no fragment identifier, this value may be the empty string (i.e. '').

See also URL.hash.

location.state#

The location.state property contains a user-supplied State object that is associated with this location. This can be a useful place to store any information you do not want to put in the URL, e.g. session-specific data.

Note: In web browsers, this state is managed using the browser's built-in pushState, replaceState, and popstate APIs. See also History.state.

location.key#

The location.key property is a unique string associated with this location. On the initial location, this will be the string default. On all subsequent locations, this string will be a unique identifier.

This can be useful in situations where you need to keep track of 2 different states for the same URL. For example, you could use this as the key to some network or device storage API.

Action#

An Action represents a type of change that occurred in the history stack. Action is an enum with three members:

  • Action.Pop - A change to an arbitrary index in the stack, such as a back or forward navigation. This does not describe the direction of the navigation, only that the index changed. This is the default action for newly created history objects.
  • Action.Push - Indicates a new entry being added to the history stack, such as when a link is clicked and a new page loads. When this happens, all subsequent entries in the stack are lost.
  • Action.Replace - Indicates the entry at the current index in the history stack being replaced by a new one.

See the Getting Started guide for more information.

To#

A To value represents a destination location, but doesn't contain all the information that a normal location object does. It is primarily used as the first argument to history.push and history.replace.

See the Navigation guide for more information.

State#

A State value is an object of extra information that is associated with a Location but that does not appear in the URL. This value is always associated with that location.

See the Navigation guide for more information.