This is the API reference for the history JavaScript library.
The history library provides an API for tracking application history using location objects that contain URLs and state. This reference includes type signatures and return values for the interfaces in the library. Please read the getting started guide if you're looking for explanations about how to use the library to accomplish a specific task.
The history library includes support for three different "environments", or modes of operation.
- Browser history is used in web apps
- Hash history is used in web apps where you don't want to/can't send the URL to the server for some reason
- Memory history - is used in native apps and testing
Just pick the right mode for your target environment and you're good to go.
To read the current location and action, use history.location and history.action. Both of these properties are mutable and automatically update as the location changes.
To be notified when the location changes, setup a listener using history.listen.
To change the current location, you'll want to use one of the following:
history.push- Pushes a new location onto the history stackhistory.replace- Replaces the current location with anotherhistory.go- Changes the current index in the history stack by a given deltahistory.back- Navigates one entry back in the history stackhistory.forward- Navigates one entry forward in the history stack
To prevent the location from changing, use history.block. This API allows you to prevent the location from changing so you can prompt the user before retrying the transition.
If you're building a link, you'll want to use history.createHref to get a URL you can use as the value of <a href>.
The source code for the history library is written in TypeScript, but it is compiled to JavaScript before publishing. Some of the function signatures in this reference include their TypeScript type annotations, but you can always refer to the original source as well.
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.
A History object represents the shared interface for BrowserHistory, HashHistory, and MemoryHistory.
Type declaration
interface History {
readonly action: Action;
readonly location: Location;
createHref(to: To): string;
push(to: To, state?: any): void;
replace(to: To, state?: any): void;
go(delta: number): void;
back(): void;
forward(): void;
listen(listener: Listener): () => void;
block(blocker: Blocker): () => void;
}Type declaration
function createBrowserHistory(options?: { window?: Window }): BrowserHistory;
interface BrowserHistory extends History {}A browser history object keeps track of the browsing history of an application using the browser's built-in history stack. It is designed to run in modern web browsers that support the HTML5 history interface including pushState, replaceState, and the popstate event.
createBrowserHistory returns a BrowserHistory instance. window defaults to the defaultView of the current document.
import { createBrowserHistory } from "history";
let history = createBrowserHistory();See the Getting Started guide for more information.
Type declaration
function createPath(partialPath: Partial<Path>): string;
function parsePath(path: string): Partial<Path>;
interface Path {
pathname: string;
search: string;
hash: string;
}The createPath and parsePath functions are useful for creating and parsing URL paths.
createPath({ pathname: "/login", search: "?next=home" }); // "/login?next=home"
parsePath("/login?next=home"); // { pathname: '/login', search: '?next=home' }Type declaration
createHashHistory({ window?: Window }): HashHistory;
interface HashHistory extends History {}A hash history object keeps track of the browsing history of an application using the browser's built-in history stack. It is designed to be run in modern web browsers that support the HTML5 history interface including pushState, replaceState, and the popstate event.
createHashHistory returns a HashHistory instance. window defaults to the defaultView of the current document.
The main difference between this and browser history is that a hash history stores the current location in the hash portion of the URL, which means that it is not ever sent to the server. This can be useful if you are hosting your site on a domain where you do not have full control over the server routes, or e.g. in an Electron app where you don't want to configure the "server" to serve the same page at different URLs.
import { createHashHistory } from "history";
let history = createHashHistory();See the Getting Started guide for more information.
Type declaration
function createMemoryHistory({
initialEntries?: InitialEntry[],
initialIndex?: number
}): MemoryHistory;
type InitialEntry = string | Partial<Location>;
interface MemoryHistory extends History {
readonly index: number;
}A memory history object keeps track of the browsing history of an application using an internal array. This makes it ideal in situations where you need complete control over the history stack, like React Native and tests.
createMemoryHistory returns a MemoryHistory instance. 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.
import { createMemoryHistory } from "history";
let history = createMemoryHistory();
// Or, to pre-seed the history instance with some URLs:
let history = createMemoryHistory({
initialEntries: ["/home", "/profile", "/about"],
});See the Getting Started guide for more information.
The current (most recent) Action that modified the history stack. This property is mutable and automatically updates as the current location changes.
See also history.listen.
Goes back one entry in the history stack. Alias for history.go(-1).
See the Navigation guide for more information.
Type declaration
interface Blocker {
(tx: Transition): void;
}
interface Transition {
action: Action;
location: Location;
retry(): void;
}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 example when they have some unsaved data on the current page.
// 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.
Returns a string suitable for use as an <a href> value that will navigate to
the given destination.
Goes forward one entry in the history stack. Alias for history.go(1).
See the Navigation guide for more information.
Navigates back/forward by delta entries in the stack.
See the Navigation guide for more information.
The current index in the history stack.
[!Note:]
This property is available only on memory history instances.
Type declaration
interface Listener {
(update: Update): void;
}
interface Update {
action: Action;
location: Location;
}Starts listening for location changes and calls the given callback with an Update 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.
The current Location. This property is mutable and automatically updates as the current location changes.
Also see history.listen.
Pushes a new entry onto the stack.
See the Navigation guide for more information.
Replaces the current entry in the stack with a new one.
See the Navigation guide for more information.
Type declaration
interface Location {
pathname: string;
search: string;
hash: string;
state: unknown;
key: string;
}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.
The location.pathname property is a string that contains an initial / followed by the remainder of the URL up to the ?.
See also URL.pathname.
The location.search property is a string that 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.
The location.hash property is a string that 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.
The location.state property is 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, andpopstateAPIs. See alsoHistory.state.
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.
A State value is an arbitrary value that holds extra information associated with a Location but does not appear in the URL. This value is always associated with that location.
See the Navigation guide for more information.
Type declaration
type To = string | Partial<Path>;
interface Path {
pathname: string;
search: string;
hash: string;
}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.