Skip to main content

keyValueStorage

Reference​

A localStorage wrapper with built-in error handling. Use it to persist small amounts of widget state across page reloads (e.g., last selected filter, collapsed/expanded state).

const { protrakUtils } = React.useContext(customWidgetContext);
const { keyValueStorage } = protrakUtils;

const storage = keyValueStorage();

Methods​

MethodSignatureDescription
setData(key: string, value: string) => voidSaves a string value under the given key in localStorage
getData(key: string) => string | nullRetrieves the stored string, or null if not found
removeData(key: string) => voidDeletes the entry for the key
getJSON(key: string, fallback?: any) => anyReads and parses a JSON value. Returns fallback (default null) when the key is missing, empty, "null" or not valid JSON. An unreadable value is removed.
setJSON(key: string, value: any) => voidSaves value as JSON under the given key
isPersistentStorageAvailable() => booleanfalse when the browser blocks site data, so values last only until the page is reloaded

Note: localStorage stores only strings. Use getJSON / setJSON for objects and arrays.

Caveats​

  • Use a unique, widget-specific key prefix (e.g. 'MyWidget_filterValue') to avoid conflicts with other widgets or platform code.
  • localStorage is per-browser and is shared across all tabs. Do not store sensitive data.
  • None of the methods throw. getData returns null and getJSON returns the fallback when storage cannot be read. A write that fails (for example because storage is full) logs one warning in the browser console.
  • If the browser blocks site data, values are kept in memory for the current tab only and are lost on reload. Check isPersistentStorageAvailable() if your widget needs to know.
  • If the browser's storage is full, values saved earlier are still returned. A new value that does not fit is kept for the current tab only, and isPersistentStorageAvailable() returns false.
  • Values are removed when the user signs out.

Usage Example​

function PersistentFilterWidget(pageContext) {
const { protrakUtils, protrakComponents } =
React.useContext(customWidgetContext);
const { keyValueStorage } = protrakUtils;
const { Box, Label, TextBox, Button, ButtonEnums } = protrakComponents;

const STORAGE_KEY = 'PersistentFilterWidget_search';

const storage = keyValueStorage();

// Initialise from stored value
const [search, setSearch] = React.useState(
storage.getData(STORAGE_KEY) || ''
);

const handleChange = (e) => {
const val = e.target.value;
setSearch(val);
storage.setData(STORAGE_KEY, val);
};

const handleClear = () => {
setSearch('');
storage.removeData(STORAGE_KEY);
};

return (
<Box style={{ display: 'flex', gap: '0.5rem', alignItems: 'center' }}>
<Label>Search</Label>
<TextBox
value={search}
onChange={handleChange}
placeholder="Persists across reloads..."
/>
<Button
text="Clear"
appearance={ButtonEnums.Appearance.Subtle}
onClick={handleClear}
/>
</Box>
);
}

Storing objects​

const storage = keyValueStorage();

// Save
storage.setJSON('MyWidget_prefs', { sortBy: 'Name', ascending: true });

// Read, with a default when nothing is saved or the saved value is unreadable
const prefs = storage.getJSON('MyWidget_prefs', {
sortBy: 'Name',
ascending: true,
});