1 files changed, 39 insertions, 0 deletions
diff --git a/history/docs/Navigation.md b/history/docs/Navigation.md
new file mode 100644
index 0000000..bc3804e
--- /dev/null
+++ b/history/docs/Navigation.md
@@ -0,0 +1,39 @@
+# Navigation
+
+`history` objects may be used to programmatically change the current location using the following methods:
+
+- `history.push(path, [state])`
+- `history.replace(path, [state])`
+- `history.go(n)`
+- `history.goBack()`
+- `history.goForward()`
+- `history.canGo(n)` (only in `createMemoryHistory`)
+
+When using `push` or `replace` you can either specify both the URL path and state as separate arguments or include everything in a single location-like object as the first argument.
+
+1. A URL path _or_
+2. A location-like object with `{ pathname, search, hash, state }`
+
+```js
+// Push a new entry onto the history stack.
+history.push('/home');
+
+// Push a new entry onto the history stack with a query string
+// and some state. Location state does not appear in the URL.
+history.push('/home?the=query', { some: 'state' });
+
+// If you prefer, use a single location-like object to specify both
+// the URL and state. This is equivalent to the example above.
+history.push({
+  pathname: '/home',
+  search: '?the=query',
+  state: { some: 'state' }
+});
+
+// Go back to the previous history entry. The following
+// two lines are synonymous.
+history.go(-1);
+history.goBack();
+```
+
+**Note:** Location state is only supported in `createBrowserHistory` and `createMemoryHistory`.