DOCSEARCHbyAlgolia
Submit Docs

history

repository·dev·Indexed 27 days ago

https://github.com/remix-run/history

A minimal, environment-agnostic JavaScript API for managing session history, navigation, and state persistence. It supports three modes of operation: Browser history for standard web apps, Hash history for apps avoiding server-side URL routing, and Memory history for native applications or testing. The library provides tools to push, replace, and navigate the history stack, listen for location changes, and block navigation transitions.

Tokens
4.5K
Snippets
16
Records
37
Agent score
92%

What's inside history

  1. Overview of the history library

    dev
    The history library provides a unified API to manage session history in any JavaScript environment. It abstracts environment-specific differences, allowing you to manage the history stack, perform navigation, and persist state between sessions using a consistent history object.

  2. Choose a history environment

    dev

    The history library supports three modes of operation depending on your target environment:

    • Browser history: Use createBrowserHistory for standard web applications.
    • Hash history: Use createHashHistory for web applications where you cannot or do not want to send the URL to the server (uses the # hash).
    • Memory history: Use createMemoryHistory for native applications or testing environments where no browser URL bar exists.

  3. Choose a history type for your environment

    dev

    The history library provides three different methods for working with history depending on your target environment:

    • Browser History: Use createBrowserHistory for modern web browsers that support the HTML5 history API.
    • Hash History: Use createHashHistory for browsers where you want to store the location in the URL hash to avoid sending it to the server on reloads.
    • Memory History: Use createMemoryHistory for non-browser environments like React Native or for testing.

    Additionally, the library provides singletons for quick access to the current document's history via history/browser and history/hash bundles.

  4. Create a history instance

    dev

    You can create a custom history instance using the environment-specific creation functions. If you are working in an environment like an iframe, you can pass a custom window object to createBrowserHistory.

    To use the current document's history directly, you can import the singletons history/browser or history/hash.

  6. Block navigation with history.block()

    dev

    Use the history.block(blocker: Blocker) API to prevent users from navigating away from the current page. This is useful for warning users about unsaved changes.

    When a navigation attempt is blocked, the provided callback is executed. The callback receives a transition object (tx) which allows you to:

    1. Access the target location via tx.location.pathname.
    2. Call unblock() to remove the blocker.
    3. Call tx.retry() to re-attempt the navigation after the user has confirmed they wish to proceed.

    You can use standard browser APIs like window.confirm or implement custom UI dialogs within the callback.

    // Block navigation and register a callback that
// fires when a navigation attempt is blocked.
let unblock = history.block((tx) => {
  // Navigation was blocked! Let's show a confirmation dialog
  // so the user can decide if they actually want to navigate
  // away and discard changes they've made in the current page.
  let url = tx.location.pathname;
  if (window.confirm(`Are you sure you want to go to ${url}?`)) {
    // Unblock the navigation.
    unblock();

    // Retry the transition.
    tx.retry();
  }
});

  7. Load history via <script> tags using ES Modules

    dev

    In browsers that support JavaScript modules, you can import the library directly from unpkg. Use history.production.min.js for production environments or history.development.js for development.

    <script type="module">
  // Can also use history.development.js in development
  import { createBrowserHistory } from "https://unpkg.com/history/history.production.min.js";
  // ...
</script>

  10. Select the correct version of history

    dev

    The version of history you should use depends on your React Router version:

    • Version 5: Use this for React Router version 6. Documentation is located in the docs directory.
    • Version 4: Use this for React Router versions 4 and 5. Documentation is available on the v4 branch.

  11. Load history via <script> tags using UMD (Global)

    dev

    For legacy browsers that do not support JavaScript modules, use the UMD builds. The library will be available on the global window.HistoryLibrary object. Use history.production.min.js for production or history.development.js for development.

    <!-- Can also use history.development.js in development -->
<script src="https://unpkg.com/history/umd/history.production.min.js"></script>

  12. Programmatically navigate using history methods

    dev

    You can change the current location programmatically using the following history methods:

    • history.push(to: To, state?: State): Adds a new entry to the history stack.
    • history.replace(to: To, state?: State): Replaces the current entry on the history stack with a new one.
    • history.go(delta: number): Moves to a relative point in the history stack (e.g., -1 for back, 1 for forward).
    • history.back(): Moves back one entry in the history stack.
    • history.forward(): Moves forward one entry in the history stack.
    // 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 location-like object to specify the URL.
history.push(
  {
    pathname: "/home",
    search: "?the=query",
  },
  {
    some: "state",
  }
);

// Go back to the previous history entry.
history.go(-1);
history.back();