This file is a prompt-friendly companion to node_modules/obsidian/obsidian.d.ts for building settings tabs and settings-driven UI in this plugin.
Use this file when you need the common settings API surface quickly. Fall back to the full declaration file when you need methods not listed here, inheritance details, or adjacent UI APIs such as Modal, Notice, SearchComponent, or ColorComponent.
- Building or editing a
PluginSettingTab - Adding standard
Settingrows - Wiring text, dropdown, toggle, and button controls to plugin settings
- Following the repo's current settings patterns without pasting the full
obsidian.d.ts
- Authoritative API:
node_modules/obsidian/obsidian.d.ts - Current repo examples:
This document is intentionally selective. It is not a complete Obsidian API reference.
From obsidian.d.ts:
export abstract class PluginSettingTab extends SettingTab {
constructor(app: App, plugin: Plugin);
}What matters in practice:
- Extend
PluginSettingTabfor plugin settings screens. - Register the tab from plugin
onload()withthis.addSettingTab(...). - Render the tab inside
display(), usually after clearingthis.containerEl.
From obsidian.d.ts:
export class Setting {
constructor(containerEl: HTMLElement);
setName(name: string | DocumentFragment): this;
setDesc(desc: string | DocumentFragment): this;
setClass(cls: string): this;
setTooltip(tooltip: string, options?: TooltipOptions): this;
setHeading(): this;
setDisabled(disabled: boolean): this;
addButton(cb: (component: ButtonComponent) => any): this;
addToggle(cb: (component: ToggleComponent) => any): this;
addText(cb: (component: TextComponent) => any): this;
addDropdown(cb: (component: DropdownComponent) => any): this;
}What matters in practice:
new Setting(containerEl)creates one settings row.- Use
setName()andsetDesc()for the visible label and supporting text. - Use
setHeading()for section headers. - Use
setClass()for plugin-specific styling hooks. - Use
setDisabled()when the whole row should become inactive based on current state.
TextComponent extends AbstractTextComponent<HTMLInputElement>.
Relevant methods:
export class AbstractTextComponent<
T extends HTMLInputElement | HTMLTextAreaElement,
> extends ValueComponent<string> {
inputEl: T;
setDisabled(disabled: boolean): this;
getValue(): string;
setValue(value: string): this;
setPlaceholder(placeholder: string): this;
onChange(callback: (value: string) => any): this;
}
export class TextComponent extends AbstractTextComponent<HTMLInputElement> {
constructor(containerEl: HTMLElement);
}export class DropdownComponent extends ValueComponent<string> {
selectEl: HTMLSelectElement;
constructor(containerEl: HTMLElement);
setDisabled(disabled: boolean): this;
addOption(value: string, display: string): this;
addOptions(options: Record<string, string>): this;
getValue(): string;
setValue(value: string): this;
onChange(callback: (value: string) => any): this;
}export class ToggleComponent extends ValueComponent<boolean> {
toggleEl: HTMLElement;
constructor(containerEl: HTMLElement);
setDisabled(disabled: boolean): this;
getValue(): boolean;
setValue(on: boolean): this;
setTooltip(tooltip: string, options?: TooltipOptions): this;
onChange(callback: (value: boolean) => any): this;
}export class ButtonComponent extends BaseComponent {
buttonEl: HTMLButtonElement;
constructor(containerEl: HTMLElement);
setDisabled(disabled: boolean): this;
setCta(): this;
removeCta(): this;
setWarning(): this;
setTooltip(tooltip: string, options?: TooltipOptions): this;
setButtonText(name: string): this;
setIcon(icon: IconName): this;
setClass(cls: string): this;
onClick(callback: (evt: MouseEvent) => any): this;
}Use text inputs for string settings and lightweight inline edits.
new Setting(containerEl)
.setName("Default RSS tag")
.setDesc("Default tag for RSS articles")
.addText((text) => {
text
.setPlaceholder("rss")
.setValue(this.plugin.settings.defaultRssTag)
.onChange(async (value) => {
this.plugin.settings.defaultRssTag = value.trim();
await this.plugin.saveSettings();
});
});Notes:
text.inputElis available for lower-level DOM access such asspellcheck, focus, or key handlers.- Normalize user input before saving when the setting expects trimmed values.
Use dropdowns for enum-like settings.
new Setting(containerEl)
.setName("View style")
.setDesc("Choose between list and card view for articles")
.addDropdown((dropdown) =>
dropdown
.addOption("list", "List")
.addOption("card", "Card")
.setValue(this.plugin.settings.viewStyle)
.onChange(async (value) => {
this.plugin.settings.viewStyle = value as "list" | "card";
await this.plugin.saveSettings();
}),
);Notes:
- Add options before
setValue()so the current value resolves correctly. - Use a cast only when the saved type is narrower than the dropdown's string value.
Use toggles for booleans and enabled states.
new Setting(containerEl)
.setName("Use web viewer")
.setDesc("Use web viewer core plugin for articles when available")
.addToggle((toggle) =>
toggle
.setValue(this.plugin.settings.useWebViewer)
.onChange(async (value) => {
this.plugin.settings.useWebViewer = value;
await this.plugin.saveSettings();
}),
);Notes:
- Prefer toggles over string or dropdown controls for plain on/off settings.
Setting#setDisabled()is the usual way to disable the whole row from a parent condition.
Use buttons for explicit actions such as save, import, reapply, delete, or open modal flows.
new Setting(actionsSurface)
.setName("Scan all and apply auto tagging")
.setDesc("Scan every stored article and apply enabled auto-tagging rules.")
.addButton((button) => {
button
.setButtonText("Scan and tag")
.setCta()
.onClick(() => {
void onReapply();
});
});Notes:
- Use
setCta()for the primary action in a row. - Use
setWarning()for destructive actions such as delete/reset flows. button.buttonElis available when custom classes or lower-level DOM access are needed.
This plugin's settings tab should be added from plugin onload() using this.addSettingTab(...).
async onload() {
await this.loadSettings();
this.settingTab = new RssDashboardSettingTab(this.app, this);
this.addSettingTab(this.settingTab);
}Settings tab classes should extend PluginSettingTab.
export class RssDashboardSettingTab extends PluginSettingTab {
plugin: RssDashboardPlugin;
constructor(app: App, plugin: RssDashboardPlugin) {
super(app, plugin);
this.plugin = plugin;
}
display(): void {
const { containerEl } = this;
containerEl.empty();
}
}Section heading:
new Setting(containerEl).setName("Dashboard").setHeading();Row bound to saved settings:
new Setting(containerEl)
.setName("Show summary")
.setDesc("Display content summary in card view")
.addToggle((toggle) =>
toggle
.setValue(this.plugin.settings.showSummary)
.onChange(async (value) => {
this.plugin.settings.showSummary = value;
await this.plugin.saveSettings();
}),
);Plugin data should be loaded and saved through the plugin wrapper methods that call Obsidian persistence APIs.
async loadSettings() {
this.settings = Object.assign({}, DEFAULT_SETTINGS, await this.loadData());
}
async saveSettings() {
await this.saveData(this.settings);
}For editors with dependent controls or summaries, save first and rerender only when the UI structure must change.
const commit = ({ rerender = false } = {}) => {
void (async () => {
await onChange();
if (rerender) {
renderAutoTagRuleEditor(options);
}
})();
};Use rerenders for structural changes such as:
- adding or deleting rule cards
- changing condition type and needing different controls
- rebuilding dependent option groups
Prefer in-place updates when only text or enabled state changes.
Open the full declaration file instead of relying on this doc when you need:
- methods not listed here, such as
addExtraButton(),addSearch(),addTextArea(), oraddColorPicker() - adjacent UI APIs like
Modal,Notice,SearchComponent,ColorComponent, orSuggestModal - inheritance details for shared component behavior
- exact property names on component elements such as
inputEl,selectEl, orbuttonEl - confirmation that a method exists before prompting an LLM to use it
Use this when asking an LLM to build or edit settings UI in this repo:
Use docs/development/obsidian-settings-reference.md as the primary reference for settings UI patterns in this plugin. Fall back to node_modules/obsidian/obsidian.d.ts only if you need methods or component types not covered there. Follow this repo's conventions: extend PluginSettingTab, register with this.addSettingTab() in onload(), use Setting rows for controls, and persist settings with loadData()/saveData().
When changing plugin code:
- edit TypeScript source in
src/, notmain.js - run
npm run buildbefore handing off