Skip to table of contents Dropdown
<pc-dropdown> 0.5.1 experimental Dropdowns display a list of options that can be triggered by keyboard navigation, submenus and various customisation options.
A dropdown consists of a trigger and a panel. By default, activating the trigger will expose the panel and interacting outside of the panel will close it.
This component is designed to work well with dropdown items to provide a list of options the user can select from. However, dropdowns can also be used in low‐level applications. The API gives you complete control over showing, hiding and positioning the panel.
<pc-dropdown>
<pc-button slot="trigger">
Dropdown
<pc-icon
library="default"
icon-style="solid"
name="chevron-down"
slot="suffix"
></pc-icon>
</pc-button>
<pc-dropdown-item>
<pc-icon
library="default"
icon-style="solid"
name="scissors"
slot="icon"
></pc-icon>
Cut
</pc-dropdown-item>
<pc-dropdown-item>
<pc-icon
library="default"
icon-style="solid"
name="copy"
slot="icon"
></pc-icon>
Copy
</pc-dropdown-item>
<pc-dropdown-item>
<pc-icon
library="default"
icon-style="solid"
name="paste"
slot="icon"
></pc-icon>
Paste
</pc-dropdown-item>
<pc-divider></pc-divider>
<pc-dropdown-item>
Show images
<pc-dropdown-item
slot="submenu"
value="show-all-images"
>
Show all images
</pc-dropdown-item>
<pc-dropdown-item
slot="submenu"
value="show-thumbnails"
>
Show thumbnails
</pc-dropdown-item>
</pc-dropdown-item>
<pc-divider></pc-divider>
<pc-dropdown-item type="checkbox" checked>
Emoji shortcuts
</pc-dropdown-item>
<pc-dropdown-item type="checkbox" checked>
Word wrap
</pc-dropdown-item>
<pc-divider></pc-divider>
<pc-dropdown-item appearance="danger">
<pc-icon
library="default"
icon-style="solid"
name="trash"
slot="icon"
></pc-icon>
Delete
</pc-dropdown-item>
</pc-dropdown>
Getting the selected item
When an item is selected, the pc-select event will be emitted by the dropdown. You can inspect event.detail.item to get a reference to the selected item. If you’ve provided a value for each dropdown item, it will be available in event.detail.item.value.
<div class="dropdown-selection">
<pc-dropdown>
<pc-button slot="trigger">
View
<pc-icon
library="default"
icon-style="solid"
name="chevron-down"
slot="suffix"
></pc-icon>
</pc-button>
<pc-dropdown-item value="full-screen">Enter full screen</pc-dropdown-item>
<pc-dropdown-item value="actual-size">Actual size</pc-dropdown-item>
<pc-dropdown-item value="zoom-in">Zoom in</pc-dropdown-item>
<pc-dropdown-item value="zoom-out">Zoom out</pc-dropdown-item>
</pc-dropdown>
</div>
<script>
const container = document.querySelector(".dropdown-selection");
const dropdown = container.querySelector("pc-dropdown");
dropdown.addEventListener("pc-select", (event) => {
console.log(event.detail.item.value);
});
</script>
To keep the dropdown open after selection, call event.preventDefault() in the pc-select event’s callback.
Use the icon slot to add icons to dropdown items. This works best with the Icon component.
<pc-dropdown>
<pc-button slot="trigger">
Edit
<pc-icon
library="default"
icon-style="solid"
name="chevron-down"
slot="suffix"
></pc-icon>
</pc-button>
<pc-dropdown-item value="cut">
<pc-icon
library="default"
icon-style="solid"
name="scissors"
slot="icon"
></pc-icon>
Cut
</pc-dropdown-item>
<pc-dropdown-item value="copy">
<pc-icon
library="default"
icon-style="solid"
name="copy"
slot="icon"
></pc-icon>
Copy
</pc-dropdown-item>
<pc-dropdown-item value="paste">
<pc-icon
library="default"
icon-style="solid"
name="paste"
slot="icon"
></pc-icon>
Paste
</pc-dropdown-item>
<pc-dropdown-item appearance="danger" value="delete">
<pc-icon
library="default"
icon-style="solid"
name="trash"
slot="icon"
></pc-icon>
Delete
</pc-dropdown-item>
</pc-dropdown>
Showing labels and dividers
Use the <h1>–<h6> elements to add labels and the <pc-divider> element for dividers.
<pc-dropdown>
<pc-button slot="trigger">
Device
<pc-icon
library="default"
icon-style="solid"
name="chevron-down"
slot="suffix"
></pc-icon>
</pc-button>
<h3>Type</h3>
<pc-dropdown-item value="phone">Phone</pc-dropdown-item>
<pc-dropdown-item value="tablet">Tablet</pc-dropdown-item>
<pc-dropdown-item value="desktop">Desktop</pc-dropdown-item>
<pc-divider></pc-divider>
<pc-dropdown-item value="more-options">More options…</pc-dropdown-item>
</pc-dropdown>
Use the details slot to display details, such as keyboard shortcuts, inside dropdown items.
<pc-dropdown>
<pc-button slot="trigger">
Message
<pc-icon
library="default"
icon-style="solid"
name="chevron-down"
slot="suffix"
></pc-icon>
</pc-button>
<pc-dropdown-item value="reply">
Reply
<span slot="details">⌘ R</span>
</pc-dropdown-item>
<pc-dropdown-item value="reply-all">
Reply all
<span slot="details">⇧ ⌘ R</span>
</pc-dropdown-item>
<pc-dropdown-item value="forward">
Forward
<span slot="details">⌘ J</span>
</pc-dropdown-item>
<pc-dropdown-item value="move">
Move
<span slot="details">⌃ ⌘ V</span>
</pc-dropdown-item>
<pc-divider></pc-divider>
<pc-dropdown-item value="archive">
Archive
<span slot="details">⌃ ⌘ A</span>
</pc-dropdown-item>
<pc-dropdown-item appearance="danger" value="delete">
Delete
<span slot="details">⌘ ⌫</span>
</pc-dropdown-item>
</pc-dropdown>
You can turn a dropdown item into a checkable option by setting type="checkbox". Add the checked attribute to make it checked initially. When clicked, the item’s checked state will toggle and the dropdown will close. You can cancel the pc-select event if you want to keep it open instead.
<pc-dropdown class="dropdown-checkboxes">
<pc-button slot="trigger">
View
<pc-icon
library="default"
icon-style="solid"
name="chevron-down"
slot="suffix"
></pc-icon>
</pc-button>
<pc-dropdown-item
type="checkbox"
value="show-canvas"
checked
>
Show canvas
</pc-dropdown-item>
<pc-dropdown-item
type="checkbox"
value="show-grid"
checked
>
Show grid
</pc-dropdown-item>
<pc-dropdown-item
type="checkbox"
value="show-source"
>
Show source
</pc-dropdown-item>
<pc-divider></pc-divider>
<pc-dropdown-item value="preferences">Preferences…</pc-dropdown-item>
</pc-dropdown>
<script>
const dropdown = document.querySelector(".dropdown-checkboxes");
dropdown.addEventListener("pc-select", (event) => {
if (event.detail.item.type === "checkbox") {
console.log(
event.detail.item.value,
event.detail.item.checked ? "checked" : "unchecked"
);
} else {
console.log(event.detail.item.value);
}
});
</script>
When a checkable option exists anywhere in the dropdown, all items will receive additional padding so they align properly.
Add appearance="danger" to any dropdown item to highlight it’s a dangerous action.
<pc-dropdown>
<pc-button slot="trigger">
Project
<pc-icon
library="default"
icon-style="solid"
name="chevron-down"
slot="suffix"
></pc-icon>
</pc-button>
<pc-dropdown-item value="share">
<pc-icon
library="default"
icon-style="solid"
name="share"
slot="icon"
></pc-icon>
Share
</pc-dropdown-item>
<pc-dropdown-item value="preferences">
<pc-icon
library="default"
icon-style="solid"
name="gear"
slot="icon"
></pc-icon>
Preferences
</pc-dropdown-item>
<pc-divider></pc-divider>
<h3>Danger zone</h3>
<pc-dropdown-item value="archive">
<pc-icon
library="default"
icon-style="solid"
name="archive"
slot="icon"
></pc-icon>
Archive
</pc-dropdown-item>
<pc-dropdown-item appearance="danger" value="delete">
<pc-icon
library="default"
icon-style="solid"
name="trash"
slot="icon"
></pc-icon>
Delete
</pc-dropdown-item>
</pc-dropdown>
The preferred placement of the dropdown can be set with the placement attribute. Note: The actual position may vary to ensure the panel remains in the viewport.
<pc-dropdown placement="right-start">
<pc-button slot="trigger">
File formats
<pc-icon
library="default"
icon-style="solid"
name="chevron-right"
slot="suffix"
></pc-icon>
</pc-button>
<pc-dropdown-item value="pdf">PDF document (.pdf)</pc-dropdown-item>
<pc-dropdown-item value="docx">Word document (.docx)</pc-dropdown-item>
<pc-dropdown-item value="xlsx">Excel spreadsheet (.xlsx)</pc-dropdown-item>
<pc-dropdown-item value="pptx">PowerPoint presentation (.pptx)</pc-dropdown-item>
<pc-dropdown-item value="txt">Plain Text (.txt)</pc-dropdown-item>
<pc-dropdown-item value="json">JSON file (.json)</pc-dropdown-item>
</pc-dropdown>
The distance from the panel to the trigger can be customised using the distance attribute. This value is specified in pixels.
<pc-dropdown distance="30">
<pc-button slot="trigger">
Edit
<pc-icon
library="default"
icon-style="solid"
name="chevron-down"
slot="suffix"
></pc-icon>
</pc-button>
<pc-dropdown-item>Cut</pc-dropdown-item>
<pc-dropdown-item>Copy</pc-dropdown-item>
<pc-dropdown-item>Paste</pc-dropdown-item>
<pc-divider></pc-divider>
<pc-dropdown-item>Find</pc-dropdown-item>
<pc-dropdown-item>Replace</pc-dropdown-item>
</pc-dropdown>
The skidding of the panel along the trigger can be customised using the skidding attribute. This value is specified in pixels.
<pc-dropdown skidding="30">
<pc-button slot="trigger">
Edit
<pc-icon
library="default"
icon-style="solid"
name="chevron-down"
slot="suffix"
></pc-icon>
</pc-button>
<pc-dropdown-item>Cut</pc-dropdown-item>
<pc-dropdown-item>Copy</pc-dropdown-item>
<pc-dropdown-item>Paste</pc-dropdown-item>
<pc-divider></pc-divider>
<pc-dropdown-item>Find</pc-dropdown-item>
<pc-dropdown-item>Replace</pc-dropdown-item>
</pc-dropdown>
To create submenus, nest dropdown items inside of a dropdown item and assign slot="submenu" to each one. You can also add dividers as needed.
<pc-dropdown class="dropdown-submenus">
<pc-button slot="trigger">
Export
<pc-icon
library="default"
icon-style="solid"
name="chevron-down"
slot="suffix"
></pc-icon>
</pc-button>
<pc-dropdown-item>
Documents
<pc-dropdown-item slot="submenu" value="pdf">PDF document (.pdf)</pc-dropdown-item>
<pc-dropdown-item slot="submenu" value="docx">Word document (.docx)</pc-dropdown-item>
<pc-dropdown-item slot="submenu" value="doc">Word 97–2003 document (.doc)</pc-dropdown-item>
</pc-dropdown-item>
<pc-dropdown-item>
Spreadsheets
<pc-dropdown-item slot="submenu" value="xlsx">Excel spreadsheet (.xlsx)</pc-dropdown-item>
<pc-dropdown-item slot="submenu" value="xls">Excel 97–2003 spreadsheet (.xls)</pc-dropdown-item>
<pc-dropdown-item slot="submenu" value="ods">OpenDocument spreadsheet (.ods)</pc-dropdown-item>
<pc-dropdown-item slot="submenu" value="numbers">Numbers spreadsheet (.numbers)</pc-dropdown-item>
<pc-divider slot="submenu"></pc-divider>
<pc-dropdown-item slot="submenu" value="csv">CSV spreadsheet (.csv)</pc-dropdown-item>
<pc-dropdown-item slot="submenu" value="tsv">Tab‐separated values (.tsv)</pc-dropdown-item>
<pc-dropdown-item slot="submenu" value="json">JSON file (.json)</pc-dropdown-item>
</pc-dropdown-item>
<pc-divider></pc-divider>
<pc-dropdown-item>
Options
<pc-dropdown-item
slot="submenu"
type="checkbox"
value="compress-files"
>
Compress files
</pc-dropdown-item>
<pc-dropdown-item
slot="submenu"
type="checkbox"
value="include-metadata"
checked
>
Include metadata
</pc-dropdown-item>
<pc-dropdown-item
slot="submenu"
type="checkbox"
value="password-protect"
>
Password protect
</pc-dropdown-item>
</pc-dropdown-item>
</pc-dropdown>
<script>
const dropdown = document.querySelector(".dropdown-submenus");
dropdown.addEventListener("pc-select", (event) => {
console.log(event.detail.item.value);
});
</script>
Dropdown items that have a submenu will not dispatch the pc-select event. However, items inside the submenu will, unless they also have a submenu.
As a UX best practice, avoid using more than one level of submenu when possible.
Add the disabled attribute to any dropdown item to disable it.
<pc-dropdown>
<pc-button slot="trigger">
Payment method
<pc-icon
library="default"
icon-style="solid"
name="chevron-down"
slot="suffix"
></pc-icon>
</pc-button>
<pc-dropdown-item value="cash">Cash</pc-dropdown-item>
<pc-dropdown-item value="personal-check" disabled>Personal check</pc-dropdown-item>
<pc-dropdown-item value="credit-card">Credit/debit card</pc-dropdown-item>
<pc-dropdown-item value="gift-card">Gift card</pc-dropdown-item>
</pc-dropdown>
| Name | Description | Reflects | Default |
|---|
open | Opens or closes the dropdown.
Type: boolean |
| false |
size | The dropdown’s size.
Type: "small" | "medium" | "large" |
| "medium" |
placement | The placement of the dropdown menu in reference to the trigger. The menu will shift to a more optimal location if the preferred placement doesn’t have enough room.
Type: "top"
| "top-start"
| "top-end"
| "bottom"
| "bottom-start"
| "bottom-end"
| "right"
| "right-start"
| "right-end"
| "left"
| "left-start"
| "left-end" |
| "bottom-start" |
distance | The distance of the dropdown menu from its trigger.
Type: number |
| 0 |
skidding | The skidding of the dropdown menu along its trigger.
Type: number |
| 0 |
updateComplete |
A read‐only promise that resolves when
the component has
finished updating.
| | ‐ |
Learn more about customising animations.
| Name | Description |
|---|
| (default) | The dropdown’s items, typically <pc-dropdown-item> elements. |
trigger | The element that triggers the dropdown, such as a <pc-button> or <button>. |
Learn more about using slots.
| Name | Description | Event detail |
|---|
pc-show | Emitted when the dropdown is about to show. | ‐ |
pc-after-show | Emitted when the dropdown has been shown. | ‐ |
pc-hide | Emitted when the dropdown is about to hide. | ‐ |
pc-after-hide | Emitted when the dropdown has been hidden. | ‐ |
pc-select | Emitted when an item in the dropdown is selected. | ‐ |
Learn more about events.
| Name | Description |
|---|
base | The component’s host element. |
menu | The dropdown menu container. |
Learn more about customising CSS parts.
If you’re using the autoloader or the standard loader,
you can skip this section. But if you’re cherry picking,
you can use any of the following snippets to import this component.
CDN (script tag)CDN (import)npm (import)
To manually import this component from the CDN,
copy this code snippet and paste it in your HTML.
<script type="module" src="https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.3/cdn/components/dropdown/dropdown.js"></script>
To manually import this component from the CDN, copy
this code snippet and paste it in your JavaScript file.
import "https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.3/cdn/components/dropdown/dropdown.js";
To manually import this component from npm, copy this
code snippet and paste it in your JavaScript file.
import "placer-toolkit/dist/components/dropdown/dropdown.js";
This component automatically imports these components: