Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / JavaScript

history.pushState() — a history entry without reloading

history.pushState() normally adds a session history entry, stores state, and optionally changes the URL without loading a new document. Updating the interface remains your responsibility.

Version: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntax

history.pushState(state, unused[, url]);

history.pushState() is a browser API defined by HTML, not ECMAScript; current browser engines support it. Having Node 24 does not establish its availability. The method normally adds a session history entry, but on an initial about:blank document it replaces the current entry rather than adding one. In either case, it does not load a new document and returns undefined. By contrast, history.replaceState() updates the current entry without adding a new one.

state is serialized rather than retained as a reference; read it through history.state. Functions cannot be stored this way and cause DataCloneError. The required unused parameter conventionally receives ''; it does not set the page title.

The optional url may be relative; omitting it preserves the address. On HTTP(S) pages it must retain the origin: scheme, host, and port. A disallowed URL, a document that is not fully active, or excessively frequent calls can cause SecurityError.

The call fires neither popstate nor hashchange, even when changing the fragment. Update the interface yourself; handle popstate and event.state for Back/Forward traversal. The example shows that subsequently changing the input object does not change the stored state.

Examples

(() => {
  const state = { page: 2 };
  const url = new URL(location.href);
  url.hash = 'cktis-page-2';

  const result = history.pushState(state, '', url.href);
  state.page = 99;

  console.log(JSON.stringify({
    page: history.state.page,
    hash: location.hash,
    returnsUndefined: result === undefined
  }));
})();

Result

{"page":2,"hash":"#cktis-page-2","returnsUndefined":true}

The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.

Sources