Overview
The Setting class provides a structured way to create settings UI with a label, description, and various control components. Settings are commonly used in plugin settings tabs to provide user configuration options.
Since: 0.9.7
Constructor
The parent HTML element where the setting will be rendered
const setting = new Setting(containerEl);
Properties
The main setting container elementSince: 0.9.7
Element containing the name and descriptionSince: 0.9.7
Element containing the setting name/labelSince: 0.9.7
Element containing the setting descriptionSince: 0.9.7
Element containing the setting controls (buttons, inputs, etc.)Since: 0.9.7
Array of component instances added to this settingSince: 0.9.7
Configuration Methods
setName()
Sets the name/label of the setting.
name
string | DocumentFragment
required
The name text or DocumentFragment to display
setting.setName('Enable feature');
this (for chaining)
Since: 0.12.16
setDesc()
Sets the description text below the name.
desc
string | DocumentFragment
required
The description text or DocumentFragment
setting.setDesc('This feature enables advanced functionality');
this (for chaining)
Since: 0.9.7
setClass()
Adds a CSS class to the setting element.
The CSS class name to add
setting.setClass('my-custom-setting');
this (for chaining)
Since: 0.9.7
Adds a tooltip to the setting.
Optional tooltip configuration
setting.setTooltip('Additional help text');
this (for chaining)
Since: 1.1.0
setHeading()
Styles this setting as a heading.
Returns: this (for chaining)
Since: 0.9.16
setDisabled()
Enables or disables the setting and all its components.
Whether the setting should be disabled
setting.setDisabled(true);
this (for chaining)
Since: 1.2.3
Control Methods
These methods add interactive controls to the setting.
Adds a button control.
cb
(component: ButtonComponent) => any
required
Callback to configure the button component
setting.addButton(btn => btn
.setButtonText('Click me')
.onClick(() => {
console.log('Button clicked!');
})
);
this (for chaining)
Since: 0.9.7
Adds an extra button (typically an icon button).
cb
(component: ExtraButtonComponent) => any
required
Callback to configure the extra button component
setting.addExtraButton(btn => btn
.setIcon('reset')
.setTooltip('Reset to default')
.onClick(() => {
// Reset logic
})
);
this (for chaining)
Since: 0.9.16
addToggle()
Adds a toggle switch control.
cb
(component: ToggleComponent) => any
required
Callback to configure the toggle component
setting.addToggle(toggle => toggle
.setValue(true)
.onChange(value => {
console.log('Toggle value:', value);
})
);
this (for chaining)
Since: 0.9.7
addText()
Adds a text input control.
cb
(component: TextComponent) => any
required
Callback to configure the text component
setting.addText(text => text
.setPlaceholder('Enter value')
.setValue('default')
.onChange(value => {
console.log('Text value:', value);
})
);
this (for chaining)
Since: 0.9.7
addTextArea()
Adds a multi-line text area control.
cb
(component: TextAreaComponent) => any
required
Callback to configure the text area component
setting.addTextArea(text => text
.setPlaceholder('Enter multiple lines')
.setValue('default\ntext')
.onChange(value => {
console.log('TextArea value:', value);
})
);
this (for chaining)
Since: 0.9.7
addSearch()
Adds a search input control.
cb
(component: SearchComponent) => any
required
Callback to configure the search component
setting.addSearch(search => search
.setPlaceholder('Search...')
.onChange(value => {
console.log('Search query:', value);
})
);
this (for chaining)
Since: 0.9.21
addDropdown()
Adds a dropdown selection control.
cb
(component: DropdownComponent) => any
required
Callback to configure the dropdown component
setting.addDropdown(dropdown => dropdown
.addOption('option1', 'Option 1')
.addOption('option2', 'Option 2')
.setValue('option1')
.onChange(value => {
console.log('Selected:', value);
})
);
this (for chaining)
Since: 0.9.7
addSlider()
Adds a slider control.
cb
(component: SliderComponent) => any
required
Callback to configure the slider component
setting.addSlider(slider => slider
.setLimits(0, 100, 1)
.setValue(50)
.onChange(value => {
console.log('Slider value:', value);
})
);
this (for chaining)
Since: 0.9.7
Adds a moment.js date format input control.
cb
(component: MomentFormatComponent) => any
required
Callback to configure the moment format component
setting.addMomentFormat(format => format
.setDefaultFormat('YYYY-MM-DD')
.setValue('YYYY-MM-DD HH:mm')
.onChange(value => {
console.log('Format:', value);
})
);
this (for chaining)
Since: 0.9.7
addColorPicker()
Adds a color picker control.
cb
(component: ColorComponent) => any
required
Callback to configure the color component
setting.addColorPicker(color => color
.setValue('#ff0000')
.onChange(value => {
console.log('Color:', value);
})
);
this (for chaining)
Since: 0.16.0
addProgressBar()
Adds a progress bar control.
cb
(component: ProgressBarComponent) => any
required
Callback to configure the progress bar component
setting.addProgressBar(progress => progress
.setValue(0.5) // 50%
);
this (for chaining)
Since: 1.4.4
addComponent()
Adds a custom component.
cb
(el: HTMLElement) => T
required
Callback that receives an HTML element and returns a component instance
setting.addComponent(el => {
const customComponent = new MyCustomComponent(el);
return customComponent;
});
this (for chaining)
Since: 1.11.0
Utility Methods
then()
Facilitates method chaining with a callback.
cb
(setting: this) => any
required
Callback that receives the setting instance
setting
.setName('My Setting')
.then(s => {
// Additional configuration
s.settingEl.addClass('custom-class');
});
this (for chaining)
Since: 0.9.20
clear()
Removes all components from this setting.
Returns: this (for chaining)
Since: 0.13.8
Example
import { Setting, PluginSettingTab } from 'obsidian';
class MySettingTab extends PluginSettingTab {
display(): void {
const { containerEl } = this;
containerEl.empty();
// Heading
new Setting(containerEl)
.setName('General Settings')
.setHeading();
// Toggle setting
new Setting(containerEl)
.setName('Enable feature')
.setDesc('Turn this feature on or off')
.addToggle(toggle => toggle
.setValue(this.plugin.settings.enabled)
.onChange(async (value) => {
this.plugin.settings.enabled = value;
await this.plugin.saveSettings();
})
);
// Text input setting
new Setting(containerEl)
.setName('API Key')
.setDesc('Enter your API key')
.addText(text => text
.setPlaceholder('Enter key')
.setValue(this.plugin.settings.apiKey)
.onChange(async (value) => {
this.plugin.settings.apiKey = value;
await this.plugin.saveSettings();
})
);
// Dropdown setting
new Setting(containerEl)
.setName('Theme')
.setDesc('Select your preferred theme')
.addDropdown(dropdown => dropdown
.addOption('light', 'Light')
.addOption('dark', 'Dark')
.addOption('auto', 'Auto')
.setValue(this.plugin.settings.theme)
.onChange(async (value) => {
this.plugin.settings.theme = value;
await this.plugin.saveSettings();
})
);
// Button setting
new Setting(containerEl)
.setName('Reset settings')
.setDesc('Reset all settings to default values')
.addButton(btn => btn
.setButtonText('Reset')
.setWarning()
.onClick(async () => {
this.plugin.settings = DEFAULT_SETTINGS;
await this.plugin.saveSettings();
this.display();
})
);
}
}
See Also
