Skip to content

State Syncing Utilities

State syncing utilities are a set of helpers for syncing your application state with URL or browser storage.

When you should consider using state syncing utils:

  • You want to sync your application state with URL in similar manner analyze applications do that.
  • You want to follow platform's <> out of the box.
  • You want to support state:storeInSessionStore escape hatch for URL overflowing out of the box.
  • You should also consider using them if you'd like to serialize state to different (not rison) format. Utils are composable, and you can implement your own storage.
  • In case you want to sync part of your state with URL, but other part of it with browser storage.

When you shouldn't look into using state syncing utils:

  • Adding a query param flag or simple key/value to URL

They are designed to work together with state containers. But state containers are not required.

State syncing utilities include:

  • syncState util which:
  • Subscribes to state changes and pushes them to state storage.
  • Optionally subscribes to state storage changes and pushes them to state.
  • Two types of storage compatible with syncState:
  • OsdUrlStateStorage - Serializes state and persists it to URL's query param in rison or hashed format. Listens for state updates in the URL and pushes them back to state.
  • SessionStorageStateStorage - Serializes state and persists it to session storage.

Example

import {
  createStateContainer,
  syncState,
  createOsdUrlStateStorage,
} from 'src/plugins/opensearch_dashboards_utils/public';

const stateContainer = createStateContainer({ count: 0 });
const stateStorage = createOsdUrlStateStorage();

const { start, stop } = syncState({
  storageKey: '_a',
  stateContainer,
  stateStorage,
});

start();

// state container change is synched to state storage
// osdUrlStateStorage updates the URL to "/#?_a=(count:2)"
stateContainer.set({ count: 2 });

stop();

Demo Plugins

See demo plugins here.

To run them, start OpenSearch Dashboards with --run-examples flag.

Reference