Overview
ToggleComponent creates an interactive toggle switch for boolean values. It extends ValueComponent<boolean> and is commonly used for enable/disable options in settings.
Constructor
The parent HTML element where the toggle will be created
const toggle = new ToggleComponent(containerEl);
Properties
Direct access to the underlying HTML toggle element
Whether the toggle is currently disabled
Methods
setValue
Sets the toggle state to on or off.
true to enable the toggle, false to disable it
toggle.setValue(true); // Turn on
toggle.setValue(false); // Turn off
this (for method chaining)
getValue
Retrieves the current state of the toggle.
const isEnabled = toggle.getValue();
// Returns: true or false
boolean - true if toggle is on, false if off
onChange
Registers a callback function that executes when the toggle state changes.
callback
(value: boolean) => any
required
Function to call when the toggle state changes. Receives the new boolean value.
toggle.onChange((value) => {
console.log(`Toggle is now: ${value ? 'ON' : 'OFF'}`);
// Save to settings
});
this (for method chaining)
onClick
Manually trigger the toggle click action.
Adds a hover tooltip to the toggle.
The tooltip text to display
Optional configuration for tooltip placement, delay, and styling
toggle.setTooltip("Enable feature", {
placement: "top"
});
this (for method chaining)
setDisabled
Enables or disables the toggle.
Whether the toggle should be disabled
toggle.setDisabled(true);
this (for method chaining)
then
Facilitates method chaining with a callback.
cb
(component: this) => any
required
Callback function that receives the component instance
toggle.then((component) => {
component.setValue(true);
});
this (for method chaining)
Usage Examples
Basic Toggle Setting
new Setting(containerEl)
.setName("Enable feature")
.setDesc("Turn this feature on or off")
.addToggle((toggle) => {
toggle
.setValue(this.plugin.settings.featureEnabled)
.onChange(async (value) => {
this.plugin.settings.featureEnabled = value;
await this.plugin.saveSettings();
});
});
Toggle with Conditional Logic
new Setting(containerEl)
.setName("Auto-save")
.setDesc("Automatically save changes")
.addToggle((toggle) => {
toggle
.setValue(this.plugin.settings.autoSave)
.onChange(async (value) => {
this.plugin.settings.autoSave = value;
await this.plugin.saveSettings();
if (value) {
this.plugin.startAutoSave();
new Notice("Auto-save enabled");
} else {
this.plugin.stopAutoSave();
new Notice("Auto-save disabled");
}
});
});
new Setting(containerEl)
.setName("Debug mode")
.addToggle((toggle) => {
toggle
.setValue(this.plugin.settings.debugMode)
.setTooltip("Enable verbose logging")
.onChange(async (value) => {
this.plugin.settings.debugMode = value;
await this.plugin.saveSettings();
});
});
Disabled Toggle
new Setting(containerEl)
.setName("Premium feature")
.setDesc("Requires upgrade")
.addToggle((toggle) => {
toggle
.setValue(false)
.setDisabled(true)
.setTooltip("Available in premium version");
});
Conditional Disabling
const mainToggle = new Setting(containerEl)
.setName("Enable sync")
.addToggle((toggle) => {
toggle
.setValue(this.plugin.settings.syncEnabled)
.onChange(async (value) => {
this.plugin.settings.syncEnabled = value;
await this.plugin.saveSettings();
// Enable/disable dependent toggle
autoSyncToggle.setDisabled(!value);
});
});
const autoSyncToggle = new Setting(containerEl)
.setName("Auto-sync")
.setDesc("Sync automatically every 5 minutes")
.addToggle((toggle) => {
toggle
.setValue(this.plugin.settings.autoSync)
.setDisabled(!this.plugin.settings.syncEnabled)
.onChange(async (value) => {
this.plugin.settings.autoSync = value;
await this.plugin.saveSettings();
});
});
Toggle with Side Effects
new Setting(containerEl)
.setName("Dark mode")
.addToggle((toggle) => {
toggle
.setValue(this.plugin.settings.darkMode)
.onChange(async (value) => {
this.plugin.settings.darkMode = value;
await this.plugin.saveSettings();
// Apply theme changes
document.body.toggleClass('dark-mode', value);
this.plugin.updateTheme(value);
});
});
Programmatic Toggle Control
let myToggle: ToggleComponent;
new Setting(containerEl)
.setName("Feature")
.addToggle((toggle) => {
myToggle = toggle;
toggle
.setValue(false)
.onChange(async (value) => {
await this.handleToggleChange(value);
});
});
// Later, programmatically change the toggle
function enableFeature() {
myToggle.setValue(true);
}
See Also
