Obsidian Settings

Obsidian Declarative Settings (1.13.0+)

Settings tabs describe their UI as data — an array of definition objects returned from getSettingDefinitions(). Obsidian handles rendering, search indexing, persistence, and validation.

Type definitions

The canonical source is packages/obsidian-api/obsidian.d.ts. Read the relevant types there when you need precise signatures — the guide below covers usage patterns, not exhaustive type docs.

Quick lookup commands:

• rg 'SettingControl<' packages/obsidian-api/obsidian.d.ts — all control types
• rg 'SettingDefinition' packages/obsidian-api/obsidian.d.ts — all definition types
• rg 'class PluginSettingTab' packages/obsidian-api/obsidian.d.ts — tab class
• rg 'class SettingPage' packages/obsidian-api/obsidian.d.ts — imperative sub-page class

How it works

Override getSettingDefinitions() on your PluginSettingTab subclass. Each entry in the returned array is a SettingDefinitionItem — one of:

control, render, and action are mutually exclusive on a single definition.

Control types

Every control reads from and writes to this.plugin.settings[key] automatically. Obsidian calls saveData() after each change.

slider requires all three of min, max, step (not optional like on number).

Examples

// Toggle
{ name: 'Enable sync', control: { type: 'toggle', key: 'syncEnabled' } }

// Text with validation
{
  name: 'API key',
  control: {
    type: 'text',
    key: 'apiKey',
    placeholder: 'Enter key…',
    validate: (v) => v.length < 8 ? 'Must be at least 8 characters.' : undefined,
  },
}

// Dropdown with default
{
  name: 'Theme',
  control: {
    type: 'dropdown',
    key: 'theme',
    defaultValue: 'system',
    options: { system: 'System', light: 'Light', dark: 'Dark' },
  },
}

// Number with range
{
  name: 'Max results',
  control: { type: 'number', key: 'maxResults', min: 1, max: 100, defaultValue: 20 },
}

// Slider (min/max/step required)
{
  name: 'Opacity',
  control: { type: 'slider', key: 'opacity', min: 0, max: 100, step: 1 },
}

// Folder picker
{
  name: 'Output folder',
  control: { type: 'folder', key: 'outputDir', includeRoot: true },
}

Conditional visibility and disabling

Two predicates toggle a setting's state without rebuilding the tab:

• visible on any definition — hides the row when false. Hidden rows are excluded from search.
• disabled on a control or action — disables interaction without hiding.

Both accept boolean | (() => boolean). The function form re-evaluates on every DOM-state refresh. For control definitions, Obsidian refreshes automatically after every change.

getSettingDefinitions() {
  return [
    { name: 'Advanced mode', control: { type: 'toggle', key: 'advanced' } },
    {
      name: 'Debug level',
      visible: () => this.plugin.settings.advanced,
      control: {
        type: 'dropdown',
        key: 'logLevel',
        defaultValue: 'info',
        options: { info: 'Info', verbose: 'Verbose' },
      },
    },
  ];
}

Use visible when a setting is irrelevant in the current state. Use disabled when it exists but is locked (prerequisite not met, feature not unlocked).

After mutating state from a render callback or other imperative path, call this.refreshDomState() to re-run predicates without a full re-render. For changes that add/remove definitions (not just toggle visibility), call this.update() instead.

Validation

Every control accepts an optional validate callback. Return a non-empty string to reject and show an inline error. Return void/undefined/empty string to accept. Async validators work too.

{
  name: 'Extension',
  control: {
    type: 'text',
    key: 'ext',
    validate: (v) => /\s/.test(v) ? 'No spaces allowed.' : undefined,
  },
}

validate is a UI gate, not a data invariant. Stored values may already be invalid (from older plugin versions). Validate again when reading settings in loadSettings() if invariants matter.

Groups

Group related settings under a heading:

{
  type: 'group',
  heading: 'Appearance',
  items: [
    { name: 'Font size', control: { type: 'number', key: 'fontSize', min: 8, max: 32 } },
    { name: 'Accent color', control: { type: 'color', key: 'accent' } },
  ],
}

Groups also accept search (renders a filter input in the header — since 1.13.1), extraButtons, cls, and visible.

Groups cannot nest inside groups. Use sub-pages for deeper hierarchy.

Lists

For user-managed collections (add/delete/reorder rows), use type: 'list':

{
  type: 'list',
  heading: 'Watched folders',
  emptyState: 'No folders yet.',
  addItem: {
    name: 'Add folder',
    action: () => this.openAddFolderModal(),
  },
  onReorder: async (oldIndex, newIndex) => {
    let folders = this.plugin.settings.folders;
    let [moved] = folders.splice(oldIndex, 1);
    folders.splice(newIndex, 0, moved);
    await this.plugin.saveData(this.plugin.settings);
  },
  onDelete: async (idx) => {
    this.plugin.settings.folders.splice(idx, 1);
    await this.plugin.saveData(this.plugin.settings);
    this.update();
  },
  items: this.plugin.settings.folders.map((path) => ({
    name: path,
    searchable: false,
  })),
}

• onReorder adds drag handles. DOM is already reordered — just update your data and save.
• onDelete wires both the delete button and the Delete key. Always call this.update() after.
• addItem renders a + button (desktop) / tappable row (mobile). Open a Modal for multi-field input.
• emptyState shows when items is empty.
• searchable: false on items keeps individual rows out of global search.

For action rows inside lists, use action and read the live index argument (not the outer map index, which goes stale after reorder):

items: commands.map((cmd) => ({
  name: cmd.name,
  searchable: false,
  action: (el, index) => this.plugin.doSomething(index),
})),

Sub-pages

Navigable sub-pages for sections with self-contained scope. Use sparingly — only when the parent tab is too long to scan.

Declarative (preferred)

{
  type: 'page',
  name: 'Advanced',
  desc: 'Power-user options.',
  items: [
    { name: 'Debug logging', control: { type: 'toggle', key: 'debug' } },
    { type: 'group', heading: 'Cache', items: [
      { name: 'Size (MB)', control: { type: 'slider', key: 'cacheMb', min: 1, max: 500, step: 1 } },
    ]},
  ],
}

Imperative (when runtime state drives UI)

Subclass SettingPage and pass a factory. Controls built in display() are invisible to getSettingDefinitions() — no search indexing, no auto-save, no visible/disabled predicates.

import { SettingPage, Setting } from 'obsidian';

class StatusPage extends SettingPage {
  constructor(private plugin: MyPlugin) {
    super();
    this.title = 'Status';
  }

  display() {
    this.containerEl.empty();
    new Setting(this.containerEl)
      .setName('Refresh')
      .addButton((btn) => btn.setButtonText('Refresh').onClick(() => this.display()));
  }

  hide() { /* clean up observers/timers */ }
}

// In getSettingDefinitions():
{ type: 'page', name: 'Status', page: () => new StatusPage(this.plugin) }

items and page are mutually exclusive.

Page names must be unique among siblings at the same depth.

Since 1.13.1: displayValue shows a value on the page entry, status: 'warning' adds an indicator.

Render callback

Use render when a setting needs side effects, derived values, or controls not covered by the declarative types (moment format, progress bars, custom suggesters, multi-button rows).

{
  name: 'Date format',
  render: (setting) => {
    setting.addMomentFormat((fmt) => fmt
      .setValue(this.plugin.settings.dateFormat)
      .onChange(async (v) => {
        this.plugin.settings.dateFormat = v;
        await this.plugin.saveData(this.plugin.settings);
      }));
  },
}

render does not auto-save — always call saveData() yourself.

Return a cleanup function from render if you create subscriptions that outlive the DOM (ResizeObserver, setInterval, etc.). Plain DOM listeners attached to elements inside the row are cleaned up automatically.

Custom settings storage

By default, control definitions read/write this.plugin.settings[key] and auto-call saveData().

Override getControlValue(key) and setControlValue(key, value) to read/write a different store (Svelte store, reactive proxy, immutable pattern). When overriding setControlValue, persist the value yourself — the automatic saveData() call is replaced.

See references/settings-guide.md § "Custom settings storage" and § "Advanced: nested settings with dot-notation keys" for the dot-path recipe.

Reacting to external changes

If the tab displays state that changes outside the settings UI (vault contents, plugin computation), call this.update() to rebuild from getSettingDefinitions(). Wire listeners in the constructor and register through plugin.registerEvent(). Debounce bursty events.

constructor(app: App, plugin: MyPlugin) {
  super(app, plugin);
  this.plugin = plugin;
  let refresh = debounce(() => this.update(), 200, true);
  plugin.registerEvent(this.app.vault.on('create', refresh));
  plugin.registerEvent(this.app.vault.on('delete', refresh));
}

Gotcha: update() skips the row holding focus

The reconciler behind update()/refreshCurrentPage deliberately skips clearing and re-rendering any setting row whose settingEl contains document.activeElement — it preserves focus while the user edits a field. A matched row (stable key) only re-runs its render/control build when e.setting && !e.settingEl.contains(activeElement).

Symptom: an action/button handler inside a row calls this.update(); every other row refreshes but the clicked row stays stuck on its pre-action state, because the clicked button is activeElement and lives in that row.

Fix: blur the button before triggering the update, e.g. btn.extraSettingsEl.blur() (or el.blur()) before the async work. Modal-driven actions are unaffected — focus is on the modal, not the row.

Navigating to settings from code

app.setting is the settings modal. It is internal API — declared in apps/obsidian/src/typings/obsidian-ex.d.ts, verified against Obsidian 1.13. Reach for it when a notice, ribbon action, or command sends the user to a specific place in settings.

There is no setting id. Definitions carry name, desc, aliases, and (for controls) a storage key — search and navigation use none of them as an address. A sub-page is addressed by its page name path, and a row is addressed by the definition object itself (identity, not id).

Open my plugin tab

app.setting.open();
app.setting.openTabById(plugin.manifest.id);

open() is idempotent and synchronous, so this is safe whether or not the modal already shows. Which window it lands in depends on config — see Verifying on screen. openTabById returns the SettingTab or null, and does not open the modal on its own. Built-in tab ids in 1.13: about, appearance, editor, file, interface, hotkeys, keychain, plugins, community-plugins. sync and publish are core-plugin tabs.