Skip to Content
API ReferenceSettings

Settings API

dmn.settings reads and partially updates global app settings.

Read settings

get()

Returns the complete current settings object.

interface SettingsState {
  hardwareAcceleration: boolean;
  alwaysOnTop: boolean;
  overlayLocked: boolean;
  noteEffect: boolean;
  noteSettings: NoteSettings;
  angleMode: string;
  language: string;
  laboratoryEnabled: boolean;
  developerModeEnabled: boolean;
  backgroundColor: string;
  useCustomCSS: boolean;
  customCSS: { path: string | null; content: string };
  useCustomJS: boolean;
  customJS: { path: string | null; content: string; plugins: JsPlugin[] };
  overlayResizeAnchor:
    | 'top-left'
    | 'top-right'
    | 'bottom-left'
    | 'bottom-right'
    | 'center';
  keyCounterEnabled: boolean;
  gridSettings: {
    alignmentGuides: boolean;
    spacingGuides: boolean;
    sizeMatchGuides: boolean;
  };
}
const settings = await dmn.settings.get();
console.log('Language:', settings.language);
console.log('Always on top:', settings.alwaysOnTop);
console.log('Overlay locked:', settings.overlayLocked);

See src/types/settings/settings.ts and src/types/settings/noteSettings.ts in the app source for the complete current types.

Update settings

update(patch)

Updates only the supplied fields and returns the committed settings.

await dmn.settings.update({
  language: 'en',
});
 
await dmn.settings.update({
  alwaysOnTop: true,
  backgroundColor: 'transparent',
});

Nested settings objects such as noteSettings, customCSS, customJS, and gridSettings are partially merged.

await dmn.settings.update({
  noteEffect: true,
  noteSettings: { speed: 15, reverse: true },
});

Subscribe to changes

onChanged(listener)

interface SettingsDiff {
  changed: Record<string, unknown>;
  full: SettingsState;
}
const unsub = dmn.settings.onChanged(({ changed, full }) => {
  console.log('Changed settings:', changed);
  console.log('Current settings:', full);
});
 
dmn.plugin.registerCleanup(unsub);

Example: toggle a boolean setting

async function toggleBooleanSetting(key) {
  const settings = await dmn.settings.get();
  const current = settings[key];
  if (typeof current === 'boolean') {
    await dmn.settings.update({ [key]: !current });
  }
}
 
await toggleBooleanSetting('alwaysOnTop');
KnobsOverlay