Skip to main content Sidebar
Design tokens Components Layout Style utilities
Privacy Code of Conduct Licence Impressum
© 2025 Placer • Built with Astro

We’d love to hear from you. Please reach out to us with any questions or inquiries you may have.

You can contact us via e‐mail at placer.coc.reports+contact@gmail.com.

We look forward to hearing from you!

Got it!
Skip to table of contents

The Placer Toolkit alpha has arrived! 🎉
Plenty of changes are coming your way—some big, some breaking, some even nuclear! Beware the changelog…

Bring it on!

    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>
    Code Edit

    Demos#

    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.

    Edit

    To keep the dropdown open after selection, call event.preventDefault() in the pc-select event’s callback.

    Showing icons#

    Use the icon slot to add icons to dropdown items. This works best with the Icon component.

    Edit

    Showing labels and dividers#

    Use the <h1>–<h6> elements to add labels and the <pc-divider> element for dividers.

    Edit

    Showing details#

    Use the details slot to display details, such as keyboard shortcuts, inside dropdown items.

    Edit

    Checkable items#

    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.

    Edit

    When a checkable option exists anywhere in the dropdown, all items will receive additional padding so they align properly.

    Destructive items#

    Add appearance="danger" to any dropdown item to highlight it’s a dangerous action.

    Edit

    Placement#

    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.

    Edit

    Distance#

    The distance from the panel to the trigger can be customised using the distance attribute. This value is specified in pixels.

    Edit

    Skidding#

    The skidding of the panel along the trigger can be customised using the skidding attribute. This value is specified in pixels.

    Edit

    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.

    Edit

    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.

    Disabling items#

    Add the disabled attribute to any dropdown item to disable it.

    Edit

    Properties#

    NameDescriptionReflectsDefault
    openOpens or closes the dropdown.
    Type: boolean    		 false
    sizeThe dropdown’s size.
    Type: "small" | "medium" | "large"    		 "medium"
    placementThe 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"
    distanceThe distance of the dropdown menu from its trigger.
    Type: number    		 0
    skiddingThe 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 attributes and properties.

    Slots#

    NameDescription
    (default)The dropdown’s items, typically <pc-dropdown-item> elements.
    triggerThe element that triggers the dropdown, such as a <pc-button> or <button>.

    Learn more about using slots.

    Events#

    NameDescriptionEvent detail
    pc-showEmitted when the dropdown is about to show.‐
    pc-after-showEmitted when the dropdown has been shown.‐
    pc-hideEmitted when the dropdown is about to hide.‐
    pc-after-hideEmitted when the dropdown has been hidden.‐
    pc-selectEmitted when an item in the dropdown is selected.‐

    Learn more about events.

    Parts#

    NameDescription
    baseThe component’s host element.
    menuThe dropdown menu container.

    Learn more about customising CSS parts.

    Importing#

    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.1/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.1/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";

    Dependencies#

    This component automatically imports these components: