diff --git a/docs/api-reference.md b/docs/api-reference.md
index a56a9d2df..3e3141599 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -1,11 +1,12 @@
+
# history API Reference
This is the API reference for [the history JavaScript library](https://github.com/ReactTraining/history). 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:
-- The create* methods:
+- The create\* methods:
- [`createBrowserHistory({ window?: Window })`](#createbrowserhistory)
- [`createHashHistory({ window?: Window })`](#createhashhistory)
- [`createMemoryHistory({ initialEntries?: InitialEntry[], initialIndex?: number })`](#creatememoryhistory)
@@ -31,6 +32,7 @@ Although there are several APIs in the history library, the main interfaces are:
- The [`State`](#state) type alias
+
## `createBrowserHistory({ window?: Window })`
Returns a [`BrowserHistory`](https://github.com/ReactTraining/history/blob/0f992736/packages/history/index.ts#L306) instance for the given `window`, which defaults to [the `defaultView` of the current `document`](https://developer.mozilla.org/en-US/docs/Web/API/Document/defaultView).
@@ -43,6 +45,7 @@ let history = createBrowserHistory();
See [the Getting Started guide](getting-started.md) for more information.
+
## `createHashHistory({ window?: Window })`
Returns a [`HashHistory`](https://github.com/ReactTraining/history/blob/0f992736/packages/history/index.ts#L317) instance for the given `window`, which defaults to [the `defaultView` of the current `document`](https://developer.mozilla.org/en-US/docs/Web/API/Document/defaultView).
@@ -55,6 +58,7 @@ let history = createHashHistory();
See [the Getting Started guide](getting-started.md) for more information.
+
## `createMemoryHistory({ initialEntries?: InitialEntry[], initialIndex?: number })`
Returns a [`MemoryHistory`](https://github.com/ReactTraining/history/blob/0f992736/packages/history/index.ts#L324) instance.
@@ -73,9 +77,10 @@ type InitialEntry =
+
## History
-A `history` object is similar to a [web browser's `window.history`](https://developer.mozilla.org/en-US/docs/Web/API/Window/history) instance but with a smaller API. `history` objects maintain a "stack" of [`location`](#location) objects that represent a user's browsing history.
+A `history` object is similar to a [web browser's `window.history`](https://developer.mozilla.org/en-US/docs/Web/API/Window/history) instance but with a smaller API. `history` objects maintain a "stack" of [`location`](#location) objects that represent a user's browsing history. As you navigate around the app, the stack is automatically updated to reflect the changes.
A `history` object has the following interface:
@@ -89,49 +94,32 @@ interface History<S extends State = Sta
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;
+ listen(listener: Listener<S>): () => void;
+ block(blocker: Blocker<S>): () => void;
}
+
### `history.action`
The current (most recent) [`Action`](#action) that modified the history stack.
+
### `history.location`
The current [`Location`](#location).
+
### `history.createHref(to: To)`
Returns a string suitable for use as an `` value that will navigate to
the given destination.
+
### `history.push(to: To, state?: State)`
Pushes a new entry onto the stack.
@@ -139,6 +127,7 @@ Pushes a new entry onto the stack.
See [the Navigation guide](navigation.md) for more information.
+
### `history.replace(to: To, state?: State)`
Replaces the current entry in the stack with a new one.
@@ -146,6 +135,7 @@ Replaces the current entry in the stack with a new one.
See [the Navigation guide](navigation.md) for more information.
+
### `history.go(delta: number)`
Navigates back/forward by `delta` entries in the stack.
@@ -153,6 +143,7 @@ Navigates back/forward by `delta` entries in the stack.
See [the Navigation guide](navigation.md) for more information.
+
### `history.back()`
Goes back one entry in the history stack. Alias for `history.go(-1)`.
@@ -160,6 +151,7 @@ Goes back one entry in the history stack. Alias for `history.go(-1)`.
See [the Navigation guide](navigation.md) for more information.
+
### `history.forward()`
Goes forward one entry in the history stack. Alias for `history.go(1)`.
@@ -167,6 +159,7 @@ Goes forward one entry in the history stack. Alias for `history.go(1)`.
See [the Navigation guide](navigation.md) for more information.
+
### `history.listen(listener: Listener)`
Starts listening for location changes and calls the given callback when it does.
@@ -184,6 +177,7 @@ unlisten();
See [the Getting Started guide](getting-started.md#listening) 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.
@@ -198,10 +192,10 @@ let unblock = history.block(({ action, location, retry }) => {
unblock();
```
-See [the guide on Blocking Transitions](blocking-transitions.md) for more
-information.
+See [the guide on Blocking Transitions](blocking-transitions.md) 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.
@@ -219,6 +213,7 @@ interface Location {
+
### `location.pathname`
The `location.pathname` property contains an initial `/` followed by the remainder of the URL up to the `?`.
@@ -226,6 +221,7 @@ The `location.pathname` property contains an initial `/` followed by the remaind
See also [`URL.pathname`](https://developer.mozilla.org/en-US/docs/Web/API/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. `''`).
@@ -233,6 +229,7 @@ The `location.search` property contains an initial `?` followed by the `key=valu
See also [`URL.search`](https://developer.mozilla.org/en-US/docs/Web/API/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. `''`).
@@ -240,6 +237,7 @@ The `location.hash` property contains an initial `#` followed by fragment identi
See also [`URL.hash`](https://developer.mozilla.org/en-US/docs/Web/API/URL/hash).
+
### `location.state`
The `location.state` property contains a user-supplied [`State`](#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.
@@ -247,6 +245,7 @@ The `location.state` property contains a user-supplied [`State`](#state) object
Note: In web browsers, this state is managed using the browser's built-in `pushState`, `replaceState`, and `popstate` APIs. See also [`History.state`](https://developer.mozilla.org/en-US/docs/Web/API/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.
@@ -254,6 +253,7 @@ The `location.key` property is a unique string associated with this location. On
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`](https://github.com/ReactTraining/history/blob/0f992736/packages/history/index.ts#L4) represents a type of change that occurred in the history stack. `Action` is an `enum` with three members:
@@ -271,6 +271,7 @@ An [`Action`](https://github.com/ReactTraining/history/blob/0f992736/packages/hi
See [the Getting Started guide](getting-started.md) for more information.
+
## To
A [`To`](https://github.com/ReactTraining/history/blob/0f992736/packages/history/index.ts#L212) value represents a destination location, but doesn't contain all the information that a normal [`location`](#location) object does. It is primarily used as the first argument to [`history.push`](#history.push) and [`history.replace`](#history.replace).
@@ -278,6 +279,7 @@ A [`To`](https://github.com/ReactTraining/history/blob/0f992736/packages/history
See [the Navigation guide](navigation.md) for more information.
+
## State
A [`State`](https://github.com/ReactTraining/history/blob/0f992736/packages/history/index.ts#L61) value is an object of extra information that is associated with a [`Location`](#location) but that does not appear in the URL. This value is always associated with that location.