Control in-app navigation anywhere you can run JavaScript
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

Hickory

npm Travis BrowserStack Status

A single page application navigation system that works in the browser or in memory.

Documentation

You can learn about Hickory and read up on the APIs in the documentation

Inspiration

Hickory is heavily inspired by the history package and the history modules from vue-router.

Packages

This repository is a monorepo for the Hickory packages. Unless you are creating your own customized history type, you only need to know about three of them:

Package Version Repo API
browser npm packages/browser API
hash npm packages/hash API
in-memory npm packages/in-memory API

Usage

Below is a quick introduction to the API of a history object.

import Browser from "@hickory/browser";

const history = Browser();

// You must add a respond handler function. Whenever there
// is navigation, that function will be called. It is responsible
// for finishing the navigation. "finish" should not be called until
// after any route matching/data loaded has finished running.
history.respondWith(({ location, action, finish, cancel }) => {
  console.log("Navigating to:", location);
  finish();
});

// All of the locations that are visited by the user of your
// application will be stored in an array. An index value is used to keep
// track of which location in the array is the current one.

// There are two navigation methods that you can use to change locations.

// navigate() is used for navigating to a new location.
// It has three modes: "ANCHOR", "PUSH", and "REPLACE".
// "PUSH" pushes the new location onto the session history after the current location
// "REPLACE" replaces the current location in the session history
// "ANCHOR" (default) acts like "PUSH" for new locations and "REPLACE" when the provided location
//   is the same as the current location (the same behavior as clicking an <a>).
// The first argument to navigate() is either a string or a partial location object.
// The optional second argument is the navigation mode ("ANCHOR" if not provided).

// mode = "ANCHOR"
history.navigate("/next-location");
// mode = "PUSH"
history.navigate("/new-location", "PUSH");
// mode = "REPLACE"
history.navigate("/same-location", "REPLACE");

// go() is used to jump to existing locations in the session history.
// negative values go backwards and positive values go forwards

// current index = 4
history.go(-2);
// new index = 2

// You might want to have you users confirm navigation before actually
// switching pages. To do this, pass a confirmation function to the
// confirmWith method.

history.confirmWith(function(info, confirm, prevent) {
  const confirmed = window.confirm("Are you sure you want to navigate?");
  if (confirmed) {
    confirm();
  } else {
    prevent();
  }
});

// Now, whenever there is navigation (the user clicks a link or the browser's
// forward/back buttons), the confirmation function will be run and the
// navigation will be cancelled if the prevent function is called.

// In the above example, if the user clicks the cancel button of the
// "confirm" popup, then the navigation will be cancelled. If the user clicks
// the "OK" button, then the navigation will occur.

// If/when you no longer want the user to have to confirm navigation, just call
// the removeConfirmation function and navigation will always happen.

history.removeConfirmation();

Browser Support

Browser testing is provided thanks to BrowserStack

The following browsers are currently tested:

  • Chrome 57 on Windows 10
  • Firefox 53 on Windows 10
  • Internet Explorer 11 on Windows 10
  • Edge 13 on Windows 10
  • Safari 10 on macOS Sierra
  • Safari on iOS 10.3
  • Chrome on Android 4.4