README.md

Visual Studio Code Dropdown

The vscode-dropdown is a web component implementation of a select element.

Usage

❌ Don't	✅ Do
Don't use a dropdown for selections with with less than three options. Try a checkbox group or radio group instead.	Use dropdowns for selections with many unique options.

❌ Don't	✅ Do
Avoid overflowing text in dropdown list options.	Use concise language to describe a selection.

❌ Don't	✅ Do
Don't use a dropdown without a descriptive label without supporting context.	Use dropdowns without labels sparingly in situations where its purpose can easily be identified or if space is limited.

Implementation

The vscode-dropdown component must be used with the vscode-option component.

Interactive component examples

Attributes

Attribute	Type	Description
disabled	boolean	Disables the dropdown and child options.
open	boolean	If true, toggles the dropdown to the open position.
position	string	Reflects the placement for the listbox when the dropdown is open. Options: above, below.

Basic Dropdown

<vscode-dropdown>
  <vscode-option>Option Label #1</vscode-option>
  <vscode-option>Option Label #2</vscode-option>
  <vscode-option>Option Label #3</vscode-option>
</vscode-dropdown>

With Label

Note: There are long term plans to better support labels in dropdown components, but in the meantime the below markup and styling will create a label that adheres to the VS Code design language.

<div class="dropdown-container">
  <label for="my-dropdown">Choose an option:</label>
  <vscode-dropdown id="my-dropdown">
    <vscode-option>Option Label #1</vscode-option>
    <vscode-option>Option Label #2</vscode-option>
    <vscode-option>Option Label #3</vscode-option>
  </vscode-dropdown>
</div>

.dropdown-container {
  box-sizing: border-box;
  display: flex;
  flex-flow: column nowrap;
  align-items: flex-start;
  justify-content: flex-start;
}

.dropdown-container label {
  display: block;
  color: var(--vscode-foreground);
  cursor: pointer;
  font-size: var(--vscode-font-size);
  line-height: normal;
  margin-bottom: 2px;
}

Disabled Attribute

<vscode-dropdown disabled>
  <vscode-option>Option Label #1</vscode-option>
  <vscode-option>Option Label #2</vscode-option>
  <vscode-option>Option Label #3</vscode-option>
</vscode-dropdown>

Open Attribute

<vscode-dropdown open>
  <vscode-option>Option Label #1</vscode-option>
  <vscode-option>Option Label #2</vscode-option>
  <vscode-option>Option Label #3</vscode-option>
</vscode-dropdown>

Position Attribute

<vscode-dropdown position="above">
  <vscode-option>Option Label #1</vscode-option>
  <vscode-option>Option Label #2</vscode-option>
  <vscode-option>Option Label #3</vscode-option>
</vscode-dropdown>

<vscode-dropdown position="below">
  <vscode-option>Option Label #1</vscode-option>
  <vscode-option>Option Label #2</vscode-option>
  <vscode-option>Option Label #3</vscode-option>
</vscode-dropdown>

Custom Indicator

The default indicator is a downward facing chevron, but it can customized by adding an element with the attribute slot="indicator".

<!-- Note: Using Visual Studio Code Codicon Library -->

<vscode-dropdown>
  <span slot="indicator" class="codicon codicon-settings"></span>
  <vscode-option>Option Label #1</vscode-option>
  <vscode-option>Option Label #2</vscode-option>
  <vscode-option>Option Label #3</vscode-option>
</vscode-dropdown>