Overview
DropdownComponent creates a dropdown menu (HTML <select> element) for selecting from predefined options. It extends ValueComponent<string> and is ideal for settings with a limited set of choices.
Constructor
The parent HTML element where the dropdown will be created
const dropdown = new DropdownComponent(containerEl);
Properties
Direct access to the underlying HTML select element
Whether the dropdown is currently disabled
Methods
addOption
Adds a single option to the dropdown.
The internal value for this option (what gets returned when selected)
The display text shown to the user
dropdown.addOption("dark", "Dark Mode");
dropdown.addOption("light", "Light Mode");
this (for method chaining)
addOptions
Adds multiple options at once from a Record/object.
options
Record<string, string>
required
An object where keys are internal values and values are display texts
dropdown.addOptions({
"small": "Small",
"medium": "Medium",
"large": "Large"
});
this (for method chaining)
setValue
Sets the currently selected option by its value.
The value of the option to select
dropdown.setValue("medium");
this (for method chaining)
getValue
Retrieves the value of the currently selected option.
const selectedValue = dropdown.getValue();
// Returns: "medium"
string - The value of the selected option
onChange
Registers a callback function that executes when the selection changes.
callback
(value: string) => any
required
Function to call when selection changes. Receives the new selected value.
dropdown.onChange((value) => {
console.log(`Selected: ${value}`);
// Save to settings
});
this (for method chaining)
setDisabled
Enables or disables the dropdown.
Whether the dropdown should be disabled
dropdown.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
dropdown.then((component) => {
component.setValue("default");
});
this (for method chaining)
Usage Examples
Basic Dropdown
new Setting(containerEl)
.setName("Theme")
.setDesc("Choose 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();
});
});
Using addOptions
const fontSizes = {
"12": "Small (12px)",
"14": "Medium (14px)",
"16": "Large (16px)",
"18": "Extra Large (18px)"
};
new Setting(containerEl)
.setName("Font Size")
.setDesc("Set the default font size")
.addDropdown((dropdown) => {
dropdown
.addOptions(fontSizes)
.setValue(this.plugin.settings.fontSize || "14")
.onChange(async (value) => {
this.plugin.settings.fontSize = value;
await this.plugin.saveSettings();
this.plugin.updateFontSize(value);
});
});
Dropdown with Dynamic Options
// Get available languages from plugin
const languages = this.plugin.getAvailableLanguages();
new Setting(containerEl)
.setName("Language")
.addDropdown((dropdown) => {
// Add each language as an option
languages.forEach(lang => {
dropdown.addOption(lang.code, lang.name);
});
dropdown
.setValue(this.plugin.settings.language)
.onChange(async (value) => {
this.plugin.settings.language = value;
await this.plugin.saveSettings();
this.plugin.loadLanguage(value);
});
});
Conditional Dropdown
let syncIntervalDropdown: DropdownComponent;
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 the interval dropdown
syncIntervalDropdown.setDisabled(!value);
});
});
new Setting(containerEl)
.setName("Sync Interval")
.setDesc("How often to sync")
.addDropdown((dropdown) => {
syncIntervalDropdown = dropdown;
dropdown
.addOptions({
"5": "5 minutes",
"15": "15 minutes",
"30": "30 minutes",
"60": "1 hour"
})
.setValue(this.plugin.settings.syncInterval)
.setDisabled(!this.plugin.settings.syncEnabled)
.onChange(async (value) => {
this.plugin.settings.syncInterval = value;
await this.plugin.saveSettings();
});
});
new Setting(containerEl)
.setName("Date Format")
.setDesc("Choose how dates are displayed")
.addDropdown((dropdown) => {
dropdown
.addOptions({
"YYYY-MM-DD": "2024-03-05 (ISO)",
"MM/DD/YYYY": "03/05/2024 (US)",
"DD/MM/YYYY": "05/03/2024 (EU)",
"DD MMM YYYY": "05 Mar 2024"
})
.setValue(this.plugin.settings.dateFormat)
.onChange(async (value) => {
this.plugin.settings.dateFormat = value;
await this.plugin.saveSettings();
});
});
Dropdown with Side Effects
new Setting(containerEl)
.setName("Default View")
.setDesc("Choose the default view mode")
.addDropdown((dropdown) => {
dropdown
.addOptions({
"reading": "Reading Mode",
"editing": "Editing Mode",
"preview": "Preview Mode"
})
.setValue(this.plugin.settings.defaultView)
.onChange(async (value) => {
this.plugin.settings.defaultView = value;
await this.plugin.saveSettings();
// Apply view change to current file
const activeLeaf = this.app.workspace.activeLeaf;
if (activeLeaf) {
this.plugin.setViewMode(activeLeaf, value);
}
new Notice(`Default view changed to ${value}`);
});
});
Direct DOM Access
const dropdown = new DropdownComponent(containerEl);
dropdown.addOptions({
"option1": "Option 1",
"option2": "Option 2"
});
// Access the underlying select element
dropdown.selectEl.size = 5; // Show 5 options at once
dropdown.selectEl.addClass("custom-dropdown");
See Also
