Logo for jsDocs.io

history

  • Version 5.3.0
  • Published
  • 121 kB
  • 1 dependency
  • MIT license

Install

npm i history
yarn add history
pnpm add history

Overview

Manage session history with JavaScript

Index

Functions

Interfaces

Enums

Type Aliases

Functions

function createBrowserHistory

createBrowserHistory: (options?: BrowserHistoryOptions) => BrowserHistory;

  • Browser history stores the location in regular URLs. This is the standard for most web apps, but it requires some configuration on the server to ensure you serve the same app at multiple URLs.

    See Also

    • https://github.com/remix-run/history/tree/main/docs/api-reference.md#createbrowserhistory

function createHashHistory

createHashHistory: (options?: HashHistoryOptions) => HashHistory;

  • Hash history stores the location in window.location.hash. This makes it ideal for situations where you don't want to send the location to the server for some reason, either because you do cannot configure it or the URL space is reserved for something else.

    See Also

    • https://github.com/remix-run/history/tree/main/docs/api-reference.md#createhashhistory

function createMemoryHistory

createMemoryHistory: (options?: MemoryHistoryOptions) => MemoryHistory;

  • Memory history stores the current location in memory. It is designed for use in stateful non-browser environments like tests and React Native.

    See Also

    • https://github.com/remix-run/history/tree/main/docs/api-reference.md#creatememoryhistory

function createPath

createPath: ({ pathname, search, hash }: Partial<Path>) => string;

  • Creates a string URL path from the given pathname, search, and hash components.

    See Also

    • https://github.com/remix-run/history/tree/main/docs/api-reference.md#createpath

function parsePath

parsePath: (path: string) => Partial<Path>;

  • Parses a string URL path into its separate pathname, search, and hash components.

    See Also

    • https://github.com/remix-run/history/tree/main/docs/api-reference.md#parsepath

Interfaces

interface Blocker

interface Blocker {}

  • A function that receives transitions when navigation is blocked.

call signature

(tx: Transition): void;

    interface BrowserHistory

    interface BrowserHistory extends History {}

    • A browser history stores the current location in regular URLs in a web browser environment. This is the standard for most web apps and provides the cleanest URLs the browser's address bar.

      See Also

      • https://github.com/remix-run/history/tree/main/docs/api-reference.md#browserhistory

    interface HashHistory

    interface HashHistory extends History {}

    • A hash history stores the current location in the fragment identifier portion of the URL in a web browser environment.

      This is ideal for apps that do not control the server for some reason (because the fragment identifier is never sent to the server), including some shared hosting environments that do not provide fine-grained controls over which pages are served at which URLs.

      See Also

      • https://github.com/remix-run/history/tree/main/docs/api-reference.md#hashhistory

    interface History

    interface History {}

    • A history is an interface to the navigation stack. The history serves as the source of truth for the current location, as well as provides a set of methods that may be used to change it.

      It is similar to the DOM's window.history object, but with a smaller, more focused API.

    property action

    readonly action: Action;

    • The last action that modified the current location. This will always be Action.Pop when a history instance is first created. This value is mutable.

      See Also

      • https://github.com/remix-run/history/tree/main/docs/api-reference.md#history.action

    property location

    readonly location: Location;

    • The current location. This value is mutable.

      See Also

      • https://github.com/remix-run/history/tree/main/docs/api-reference.md#history.location

    method back

    back: () => void;

    • Navigates to the previous entry in the stack. Identical to go(-1).

      Warning: if the current location is the first location in the stack, this will unload the current document.

      See Also

      • https://github.com/remix-run/history/tree/main/docs/api-reference.md#history.back

    method block

    block: (blocker: Blocker) => () => void;

    • Prevents the current location from changing and sets up a listener that will be called instead.

      Parameter blocker

      A function that will be called when a transition is blocked

      Returns

      unblock - A function that may be used to stop blocking

      See Also

      • https://github.com/remix-run/history/tree/main/docs/api-reference.md#history.block

    method createHref

    createHref: (to: To) => string;

    • Returns a valid href for the given to value that may be used as the value of an <a href> attribute.

      Parameter to

      The destination URL

      See Also

      • https://github.com/remix-run/history/tree/main/docs/api-reference.md#history.createHref

    method forward

    forward: () => void;

    • Navigates to the next entry in the stack. Identical to go(1).

      See Also

      • https://github.com/remix-run/history/tree/main/docs/api-reference.md#history.forward

    method go

    go: (delta: number) => void;

    • Navigates n entries backward/forward in the history stack relative to the current index. For example, a "back" navigation would use go(-1).

      Parameter delta

      The delta in the stack index

      See Also

      • https://github.com/remix-run/history/tree/main/docs/api-reference.md#history.go

    method listen

    listen: (listener: Listener) => () => void;

    • Sets up a listener that will be called whenever the current location changes.

      Parameter listener

      A function that will be called when the location changes

      Returns

      unlisten - A function that may be used to stop listening

      See Also

      • https://github.com/remix-run/history/tree/main/docs/api-reference.md#history.listen

    method push

    push: (to: To, state?: any) => void;

    • Pushes a new location onto the history stack, increasing its length by one. If there were any entries in the stack after the current one, they are lost.

      Parameter to

      The new URL

      Parameter state

      Data to associate with the new location

      See Also

      • https://github.com/remix-run/history/tree/main/docs/api-reference.md#history.push

    method replace

    replace: (to: To, state?: any) => void;

    • Replaces the current location in the history stack with a new one. The location that was replaced will no longer be available.

      Parameter to

      The new URL

      Parameter state

      Data to associate with the new location

      See Also

      • https://github.com/remix-run/history/tree/main/docs/api-reference.md#history.replace

    interface Listener

    interface Listener {}

    • A function that receives notifications about location changes.

    call signature

    (update: Update): void;

      interface Location

      interface Location extends Path {}

      • An entry in a history stack. A location contains information about the URL path, as well as possibly some arbitrary state and a key.

        See Also

        • https://github.com/remix-run/history/tree/main/docs/api-reference.md#location

      property key

      key: Key;

      • A unique string associated with this location. May be used to safely store and retrieve data in some other storage API, like localStorage.

        Note: This value is always "default" on the initial location.

        See Also

        • https://github.com/remix-run/history/tree/main/docs/api-reference.md#location.key

      property state

      state: unknown;

      • A value of arbitrary data associated with this location.

        See Also

        • https://github.com/remix-run/history/tree/main/docs/api-reference.md#location.state

      interface MemoryHistory

      interface MemoryHistory extends History {}

      • A memory history stores locations in memory. This is useful in stateful environments where there is no web browser, such as node tests or React Native.

        See Also

        • https://github.com/remix-run/history/tree/main/docs/api-reference.md#memoryhistory

      property index

      readonly index: number;

        interface Path

        interface Path {}

        • The pathname, search, and hash values of a URL.

        property hash

        hash: Hash;

        • A URL fragment identifier, beginning with a #.

          See Also

          • https://github.com/remix-run/history/tree/main/docs/api-reference.md#location.hash

        property pathname

        pathname: Pathname;

        • A URL pathname, beginning with a /.

          See Also

          • https://github.com/remix-run/history/tree/main/docs/api-reference.md#location.pathname

        property search

        search: Search;

        • A URL search string, beginning with a ?.

          See Also

          • https://github.com/remix-run/history/tree/main/docs/api-reference.md#location.search

        interface Transition

        interface Transition extends Update {}

        • A change to the current location that was blocked. May be retried after obtaining user confirmation.

        method retry

        retry: () => void;

        • Retries the update to the current location.

        interface Update

        interface Update {}

        • A change to the current location.

        property action

        action: Action;

        • The action that triggered the change.

        property location

        location: Location;

        • The new location.

        Enums

        enum Action

        enum Action {
            Pop = 'POP',
            Push = 'PUSH',
            Replace = 'REPLACE',
        }

        • Actions represent the type of change to a location value.

          See Also

          • https://github.com/remix-run/history/tree/main/docs/api-reference.md#action

        member Pop

        Pop = 'POP'

        • A POP indicates a change to an arbitrary index in the history stack, such as a back or forward navigation. It does not describe the direction of the navigation, only that the current index changed.

          Note: This is the default action for newly created history objects.

        member Push

        Push = 'PUSH'

        • A 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.

        member Replace

        Replace = 'REPLACE'

        • A REPLACE indicates the entry at the current index in the history stack being replaced by a new one.

        Type Aliases

        type BrowserHistoryOptions

        type BrowserHistoryOptions = {
            window?: Window;
        };

          type Hash

          type Hash = string;

          • A URL fragment identifier, beginning with a #.

            See Also

            • https://github.com/remix-run/history/tree/main/docs/api-reference.md#location.hash

          type HashHistoryOptions

          type HashHistoryOptions = {
              window?: Window;
          };

            type InitialEntry

            type InitialEntry = string | Partial<Location>;

            • A user-supplied object that describes a location. Used when providing entries to createMemoryHistory via its initialEntries option.

            type Key

            type Key = string;

            • A unique string associated with a location. May be used to safely store and retrieve data in some other storage API, like localStorage.

              See Also

              • https://github.com/remix-run/history/tree/main/docs/api-reference.md#location.key

            type MemoryHistoryOptions

            type MemoryHistoryOptions = {
                initialEntries?: InitialEntry[];
                initialIndex?: number;
            };

              type PartialLocation

              type PartialLocation = Partial<Location>;

              • A partial Location object that may be missing some properties.

                Deprecated

              type PartialPath

              type PartialPath = Partial<Path>;

              • A partial Path object that may be missing some properties.

                Deprecated

              type Pathname

              type Pathname = string;

              • A URL pathname, beginning with a /.

                See Also

                • https://github.com/remix-run/history/tree/main/docs/api-reference.md#location.pathname

              type Search = string;

              • A URL search string, beginning with a ?.

                See Also

                • https://github.com/remix-run/history/tree/main/docs/api-reference.md#location.search

              type State

              type State = unknown;

              • An object that is used to associate some arbitrary data with a location, but that does not appear in the URL path.

                See Also

                • https://github.com/remix-run/history/tree/main/docs/api-reference.md#location.state

                Deprecated

              type To

              type To = string | Partial<Path>;

              • Describes a location that is the destination of some navigation, either via history.push or history.replace. May be either a URL or the pieces of a URL path.

              Package Files (1)

              Dependencies (1)

              Dev Dependencies (0)

              No dev dependencies.

              Peer Dependencies (0)

              No peer dependencies.

              Badge

              To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

              You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/history.

              • Markdown
                [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/history)
              • HTML
                <a href="https://www.jsdocs.io/package/history"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>