PluginSettingsTabBase<PluginSettings>
Base class for creating plugin settings tabs in Obsidian. Provides a method for binding value components to plugin settings and handling changes.
Import:
import { PluginSettingsTabBase } from 'obsidian-dev-utils/obsidian/plugin/plugin-settings-tab';Signature:
export class PluginSettingsTabBase<PluginSettings extends object> extends mixinAsyncEvents<PluginSettingsTabBaseEventMap>()(PluginSettingTab)Extends: mixinAsyncEvents<PluginSettingsTabBaseEventMap>()(PluginSettingTab)
Constructor
new PluginSettingsTabBase(params: PluginSettingsTabBaseConstructorParams<PluginSettings>)Creates a new plugin settings tab.
Properties
| Property | Type | Description |
|---|---|---|
| pluginSettingsComponent | PluginSettingsComponentBase<PluginSettings> | The settings manager. |
Methods
| Method | Returns | Description |
|---|---|---|
| bind(params) | TValueComponent | Binds a value component to a plugin setting. |
| display() | void | Renders the plugin settings tab. |
| displayLegacy() | void | Legacy way to render the plugin settings tab imperatively. The pre-declarative fallback: Obsidian only calls it when getSettingDefinitions returns an empty array, i.e. when the consumer has not overridden getSettingDefinitionItems. Such a consumer overrides this method and builds the UI with SettingEx and bind. |
| getControlValue(key) | unknown | Reads the value backing a native control setting definition.Obsidian calls it on every render of a control-type definition. The inherited implementation reads plugin.settings, which a plugin built on PluginSettingsComponentBase never populates, so it is routed to the settings component instead. |
| getSettingDefinitionItems() | SettingDefinitionItem[] | The declarative setting definitions for the tab (Obsidian 1.13+). Consumers override this, typically building each row with settingEx and bind and grouping them with settingGroupEx. Returning an empty array — the default — makes Obsidian fall back to the imperative displayLegacy path.MUST be a pure builder. Obsidian calls it when the tab is registered ( addSettingTab), long before the tab is ever opened, in order to index the settings for search. Anything with a side effect belongs inside a row's PluginSettingsTabBaseSettingExParams.render callback, which runs only when the row is actually rendered. |
| getSettingDefinitions() | SettingDefinitionItem[] | Returns the declarative setting definitions rendered by Obsidian 1.13+. Delegates to getSettingDefinitionItems. When a consumer has not overridden that hook it returns an empty array, and Obsidian falls back to the imperative displayLegacy path. |
| hide() | void | Hides the plugin settings tab. |
| hideAsync() | Promise<void> | Async actions to perform when the settings tab is being hidden. |
| onLoadSettings(_loadedState, _isInitialLoad) | Promise<void> | Called when the plugin settings are loaded. |
| refresh() | void | Re-renders the settings tab after the underlying state changed. Rebuilds the definitions and re-renders, which covers both paths: Obsidian renders the declarative definitions when getSettingDefinitionItems provides them, and falls back to displayLegacy when it does not. Nothing is rendered while the tab is not the one on screen.Use it only for changes that alter the STRUCTURE of the tab — rows added or removed. When only a PluginSettingsTabBaseSettingExParams.disabled / PluginSettingsTabBaseSettingExParams.visible predicate has to be re-evaluated, call the much cheaper refreshDomState instead, which toggles the rendered DOM in place. |
| revalidate() | Promise<void> | Revalidates the settings. |
| setControlValue(key, value) | Promise<void> | Persists the value of a native control setting definition.The counterpart of getControlValue: it routes the write to the settings component instead of the inherited plugin.saveData path, so validation, transformers and the debounced save all apply as they do for a bind-ed component. |
| settingEx(params) | SettingDefinitionRender | Builds a search-indexable declarative row that is rendered imperatively. The bridge between the declarative API and ODU's imperative building blocks: Obsidian owns the row (so it indexes it for search and evaluates its PluginSettingsTabBaseSettingExParams.visible / PluginSettingsTabBaseSettingExParams.disabled predicates on every refreshDomState), while PluginSettingsTabBaseSettingExParams.render fills it in with SettingEx adders and bind exactly as an imperative tab would. |
| settingGroupEx(params) | SettingDefinitionGroup | Builds a declarative heading group. The declarative counterpart of SettingGroupEx: where that class appends a group to a container imperatively, this returns the definition Obsidian renders, so a group-structured tab keeps its shape after the migration. |
| show() | void | Shows the plugin settings tab. |
Links to this page: