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
| Method | Signature | Description |
|---|---|---|
setData | (key: string, value: string) => void | Saves a string value under the given key in localStorage |
getData | (key: string) => string | null | Retrieves the stored string, or null if not found |
removeData | (key: string) => void | Deletes the entry for the key |
getJSON | (key: string, fallback?: any) => any | Reads 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) => void | Saves value as JSON under the given key |
isPersistentStorageAvailable | () => boolean | false when the browser blocks site data, so values last only until the page is reloaded |
Note:
localStoragestores only strings. UsegetJSON/setJSONfor objects and arrays.
Caveats
- Use a unique, widget-specific key prefix (e.g.
'MyWidget_filterValue') to avoid conflicts with other widgets or platform code. localStorageis per-browser and is shared across all tabs. Do not store sensitive data.- None of the methods throw.
getDatareturnsnullandgetJSONreturns 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()returnsfalse. - 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,
});