Skip to main content

User Preferences

The SDK has no dedicated user-preferences store, but it does distinguish which scene settings are user-local and which belong to the document. Each viewport setting has a persistence scope (SettingScope):

  • export — saved into the document (grid enabled, grid style, snap-to-grid).
  • browser — kept locally only, e.g. in localStorage (pan, zoom, rotation).
  • ephemeral — session only, never persisted (viewport size).
import { dehydrateScene, hydrateScene, VIEWPORT_SCOPE } from "@oh-just-another/scene";

VIEWPORT_SCOPE is the source of truth for these scopes. dehydrateScene prepares a scene for storage by resetting ephemeral settings to their defaults; hydrateScene layers saved data and host-supplied overrides back over the defaults. This is how you persist per-user viewport state (pan/zoom) separately from the shared document.

Several user-facing toggles live on the viewport and persist with it rather than in undo history — for example show/hide grid and snap-to-grid, set via the editor.

Theme persistence exists only in the drop-in editor: <Editor persistTheme> (@oh-just-another/editor) stores the choice in localStorage (default key "diagram-theme", or pass a custom key string). @oh-just-another/react-ui itself does not persist a theme — it exports light and dark palettes (ELEMENT_PALETTE_LIGHT / _DARK, CANVAS_PALETTE_LIGHT / _DARK) and resolvePaletteTheme; store the preference yourself when composing chrome directly. The bundled color picker always offers ELEMENT_PALETTE_LIGHT: the canvas is not themed (dark mode darkens the chrome only), so element colors are always picked against light paper.

Editor preferences​

Device / assist settings that are not document data live on the editor as EditorPreferences: snapObjects, showObjectSize, suggestObjectSize and wheelMode ("auto" | "mouse" | "trackpad"). They are the check rows of the canvas context menu.

editor.preferences; // EditorPreferences
editor.setPreferences({ snapObjects: false, wheelMode: "trackpad" });
new Editor({ ..., preferences: { wheelMode: "mouse" } }); // seed

The drop-in editor persists them per browser with <Diagram persistPreferences> (default key "diagram-preferences", or a custom key); bindPreferencesPersistence(editor, key) / loadPreferences(key) from @oh-just-another/editor do the same for a hand-composed shell. Theme, viewport scopes and preferences remain separate stores.