SettingTab

Official

A setting tab.

Import:

import { SettingTab } from 'obsidian';

Signature:

export class SettingTab

Constructor

new SettingTab(app: App, setting: Setting)

Constructor.

To extract the constructor type, use ExtractConstructor<SettingTab>.

Properties

Property	Type	Description
app	App	Reference to the app instance.
containerEl	HTMLElement	HTML element for the setting tab content.
icon	IconName	The icon to display in the settings sidebar.
id	string	Unique ID of the tab.
installedPluginsEl?	HTMLElement	Reference to installed plugins element. Tab is the community plugins tab.
name	string	Sidebar name of the tab.
navEl	HTMLElement	Sidebar navigation element of the tab.
plugin?	Plugin	Reference to the plugin that initialized the tab. Tab is a plugin tab.
renderedItems	unknown[]	The rendered setting items (and groups) currently shown in the tab.
setting	Setting	Reference to the settings modal.
settingItems	SettingDefinitionItem[]	Nested setting definitions as returned by `getSettingDefinitions`. Populated by `update`.

Methods

Method	Returns	Description
display()	void	Override to render the tab imperatively. Not called when `getSettingDefinitions` returns a non-empty array; the tab is rendered declaratively from those definitions instead. Only implement display() as a fallback for plugins that need to support Obsidian versions older than 1.13.0.
getControlBinding(configKey)	unknown	Builds a two-way binding (current value plus an onChange persister) for a control key.
getControlValue(key)	unknown	Read the current value for a control key. Called on every render of a `control`-type setting definition. The default implementation reads from `this.app.vault.getConfig` — appropriate for the app's own setting tabs. `obsidian#PluginSettingTab` and `InternalPluginSettingTab` override this to read from their conventional settings storage; plugins with custom storage override on their subclass.
getDefinitionForElement(el)	unknown	Finds the setting definition rendered to the given element.
getElementForDefinition(definition)	HTMLElement \| undefined	Finds the rendered element for a setting definition.
getSettingDefinitions()	SettingDefinitionItem[]	Override to provide setting definitions. Return an array of definitions and inline groups. Called on every `display` and once when the tab is added to the setting modal for search indexing.
hide()	void	Hides the contents of the setting tab. Any registered components should be unloaded when the view is hidden. Override this if you need to perform additional cleanup.
refreshDomState()	void	Re-evaluate every `visible` and `disabled` predicate against the current state and apply the result to the rendered DOM. Call this from a `render` callback's `onChange` (or any other imperative path) after mutating state that other settings' predicates depend on. Cheap: toggles CSS state in place, no re-render. For changes that affect the structure of the definitions themselves (added or removed items), call `update` instead.
renderTab()	void	Re-renders the tab's already-built setting items, or displays the tab if none exist yet.
setControlValue(key, value)	void \| Promise<void>	Persist a new value for a control key. Called on user change of a `control`-type setting definition. The default implementation writes to `this.app.vault.setConfig`. Override to persist elsewhere; pair with `getControlValue`.
update()	void	Stores the result of `getSettingDefinitions` for rendering and search indexing. Called by `addSettingTab()` and by dynamic tabs when their data changes.

Links to this page: