Dropdown

<quiet-dropdown>

stable

since 1.0

Dropdowns provide a menu of options that appear when the corresponding trigger is activated.

Dropdown menus appear when their trigger element is clicked. They are not modal, so no overlay is shown when open. Dropdowns will close when the user selects an item, clicks outside of them, or presses Escape. Only one dropdown can be open at a time.

              
                  Message
                
                Actions

                  Reply
                  
                  Forward
                  
                  Archive
                  
                  Delete
                  Delete
                
                 Show images 

                 Word wrap 

                  Preferences

<quiet-dropdown>
  <quiet-button slot="trigger" with-caret>
    <quiet-icon slot="start" name="mail"></quiet-icon>
    Message
  </quiet-button>

  <small>Actions</small>

  <quiet-dropdown-item value="reply">
    <quiet-icon slot="icon" name="corner-up-left"></quiet-icon>
    Reply
    <quiet-hotkey slot="details" keys="$command R" appearance="unstyled"></quiet-hotkey>
  </quiet-dropdown-item>

  <quiet-dropdown-item value="forward">
    <quiet-icon slot="icon" name="corner-up-right"></quiet-icon>
    Forward
    <quiet-hotkey slot="details" keys="$command F" appearance="unstyled"></quiet-hotkey>
  </quiet-dropdown-item>

  <quiet-dropdown-item value="archive">
    <quiet-icon slot="icon" name="archive"></quiet-icon>
    Archive
    <quiet-hotkey slot="details" keys="$shift $command A" appearance="unstyled"></quiet-hotkey>
  </quiet-dropdown-item>

  <quiet-dropdown-item value="delete" variant="destructive">
    <quiet-icon slot="icon" name="trash"></quiet-icon>
    Delete
    <span slot="details">Delete</span>
  </quiet-dropdown-item>

  <quiet-divider></quiet-divider>

  <quiet-dropdown-item value="images" type="checkbox" checked>
    Show images
  </quiet-dropdown-item>

  <quiet-dropdown-item value="wrap" type="checkbox" checked>
    Word wrap
  </quiet-dropdown-item>

  <quiet-divider></quiet-divider>

  <quiet-dropdown-item value="preferences">
    <quiet-icon slot="icon" name="adjustments-horizontal"></quiet-icon>
    Preferences
  </quiet-dropdown-item>
</quiet-dropdown>

Getting the selected item Jump to heading

When an item is selected, the quiet-select event will be emitted by the dropdown. You can inspect event.detail.selection 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.selection.value.

              
                View
                Enter full screen
                Actual size
                Zoom in
                Zoom out

<quiet-dropdown id="dropdown__selected">
  <quiet-button slot="trigger" with-caret>View</quiet-button>
  <quiet-dropdown-item value="full-screen">Enter full screen</quiet-dropdown-item>
  <quiet-dropdown-item value="actual">Actual size</quiet-dropdown-item>
  <quiet-dropdown-item value="zoom-in">Zoom in</quiet-dropdown-item>
  <quiet-dropdown-item value="zoom-out">Zoom out</quiet-dropdown-item>
</quiet-dropdown>

<script>
  const dropdown = document.getElementById('dropdown__selected');

  dropdown.addEventListener('quiet-select', event => {
    console.log(event.detail.selection.value);
  });
</script>

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

Showing icons Jump to heading

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

<quiet-dropdown>
  <quiet-button slot="trigger" with-caret>Edit</quiet-button>

  <quiet-dropdown-item value="cut">
    <quiet-icon slot="icon" name="scissors"></quiet-icon>
      Cut
  </quiet-dropdown-item>

  <quiet-dropdown-item value="copy">
    <quiet-icon slot="icon" name="clipboard-copy"></quiet-icon>
      Copy
  </quiet-dropdown-item>

  <quiet-dropdown-item value="paste">
    <quiet-icon slot="icon" name="clipboard-plus"></quiet-icon>
      Paste
  </quiet-dropdown-item>

  <quiet-dropdown-item value="delete">
    <quiet-icon slot="icon" name="backspace"></quiet-icon>
      Delete
  </quiet-dropdown-item>
</quiet-dropdown>

Showing labels & dividers Jump to heading

Use the <small> element for labels and the <quiet-divider> element for separators.

              
                Device
                Type
                Phone
                Tablet
                Desktop
                
                More options…
              
            

<quiet-dropdown>
  <quiet-button slot="trigger" with-caret>Device</quiet-button>
  <small>Type</small>
  <quiet-dropdown-item value="phone">Phone</quiet-dropdown-item>
  <quiet-dropdown-item value="tablet">Tablet</quiet-dropdown-item>
  <quiet-dropdown-item value="desktop">Desktop</quiet-dropdown-item>
  <quiet-divider></quiet-divider>
  <quiet-dropdown-item value="more">More options…</quiet-dropdown-item>
</quiet-dropdown>

Showing details Jump to heading

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

<quiet-dropdown>
  <quiet-button slot="trigger" with-caret>Message</quiet-button>

  <quiet-dropdown-item value="reply">
    Reply
    <quiet-hotkey slot="details" keys="$command R" appearance="unstyled"></quiet-hotkey>
  </quiet-dropdown-item>

  <quiet-dropdown-item value="forward">
    Forward
    <quiet-hotkey slot="details" keys="$command F" appearance="unstyled"></quiet-hotkey>
  </quiet-dropdown-item>

  <quiet-dropdown-item value="move">
    Move
    <quiet-hotkey slot="details" keys="$command M" appearance="unstyled"></quiet-hotkey>
  </quiet-dropdown-item>

  <quiet-divider></quiet-divider>

  <quiet-dropdown-item value="archive">
    Archive
    <quiet-hotkey slot="details" keys="$command A" appearance="unstyled"></quiet-hotkey>
  </quiet-dropdown-item>

  <quiet-dropdown-item value="delete" variant="destructive">
    Delete
    <span slot="details">Delete</span>
  </quiet-dropdown-item>
</quiet-dropdown>

Checkable items Jump to heading

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 quiet-select event if you want to keep it open instead.

              
                View
                Show canvas
                Show grid
                Show source
                
                Preferences…

<quiet-dropdown id="dropdown__checkboxes">
  <quiet-button slot="trigger" with-caret>View</quiet-button>
  <quiet-dropdown-item type="checkbox" value="canvas" checked>Show canvas</quiet-dropdown-item>
  <quiet-dropdown-item type="checkbox" value="grid" checked>Show grid</quiet-dropdown-item>
  <quiet-dropdown-item type="checkbox" value="source">Show source</quiet-dropdown-item>
  <quiet-divider></quiet-divider>
  <quiet-dropdown-item value="preferences">Preferences…</quiet-dropdown-item>
</quiet-dropdown>

<script>
  const dropdown = document.getElementById('dropdown__checkboxes');

  dropdown.addEventListener('quiet-select', event => {
    if (event.detail.selection.type === 'checkbox') {
      // Checkbox
      console.log(
        event.detail.selection.value,
        event.detail.selection.checked ? 'checked' : 'unchecked'
      );
    } else {
      // Not a checkbox
      console.log(event.detail.selection.value);
    }
  });
</script>

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

Destructive items Jump to heading

Add variant="destructive" to any dropdown item to highlight that it's a dangerous action.

              
                Project

                  Share
                
                  Preferences
                
                Danger zone

                  Archive
                
                  Delete

<quiet-dropdown>
  <quiet-button slot="trigger" with-caret>Project</quiet-button>

  <quiet-dropdown-item value="share">
    <quiet-icon slot="icon" name="share-2"></quiet-icon>
    Share
  </quiet-dropdown-item>

  <quiet-dropdown-item value="preferences">
    <quiet-icon slot="icon" name="adjustments-horizontal"></quiet-icon>
    Preferences
  </quiet-dropdown-item>

  <quiet-divider></quiet-divider>

  <small>Danger zone</small>
  
  <quiet-dropdown-item value="archive">
    <quiet-icon slot="icon" name="archive"></quiet-icon>
    Archive
  </quiet-dropdown-item>

  <quiet-dropdown-item value="delete" variant="destructive">
    <quiet-icon slot="icon" name="trash"></quiet-icon>
    Delete
  </quiet-dropdown-item>
</quiet-dropdown>

Disabling items Jump to heading

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

              
                Payment method
                Cash
                Personal check
                Credit card
                Gift card
              
            

<quiet-dropdown>
  <quiet-button slot="trigger" with-caret>Payment method</quiet-button>
  <quiet-dropdown-item value="cash">Cash</quiet-dropdown-item>
  <quiet-dropdown-item value="check" disabled>Personal check</quiet-dropdown-item>
  <quiet-dropdown-item value="credit">Credit card</quiet-dropdown-item>
  <quiet-dropdown-item value="gift-card">Gift card</quiet-dropdown-item>
</quiet-dropdown>

Changing the placement Jump to heading

You can set the preferred placement of the dropdown menu with the placement attribute. The menu will shift to a more optimal location if the preferred placement doesn't have enough room.

              
                  Types of cats
                  
                Bengal
                Calico
                Maine coon
                Siamese
                Tabby
                Tuxedo

<quiet-dropdown placement="right">
  <quiet-button slot="trigger">
    Types of cats
    <quiet-icon slot="end" name="chevron-right"></quiet-icon>
  </quiet-button>
  <quiet-dropdown-item value="bengal">Bengal</quiet-dropdown-item>
  <quiet-dropdown-item value="calico">Calico</quiet-dropdown-item>
  <quiet-dropdown-item value="maine-coon">Maine coon</quiet-dropdown-item>
  <quiet-dropdown-item value="siamese">Siamese</quiet-dropdown-item>
  <quiet-dropdown-item value="tabby">Tabby</quiet-dropdown-item>
  <quiet-dropdown-item value="tuxedo">Tuxedo</quiet-dropdown-item>
</quiet-dropdown>

Context menus Jump to heading

To turn a dropdown menu into a context menu, omit the trigger and set the context-menu attribute to the ID of an element in the same document. When you right-click or long press (touch only) the target element, the context menu will be shown.

Right-click or long press here to show the context menu

                Show canvas
                Show grid
                Show source
                
                Preferences…
              

<div id="dropdown__actions" tabindex="0">
  Right-click or long press here to show the context menu
</div>

<quiet-dropdown id="dropdown__selected" context-menu="dropdown__actions">
  <quiet-dropdown-item type="checkbox" value="canvas" checked>Show canvas</quiet-dropdown-item>
  <quiet-dropdown-item type="checkbox" value="grid" checked>Show grid</quiet-dropdown-item>
  <quiet-dropdown-item type="checkbox" value="source">Show source</quiet-dropdown-item>
  <quiet-divider></quiet-divider>
  <quiet-dropdown-item value="preferences">Preferences…</quiet-dropdown-item>
</quiet-dropdown>

<style>
  #dropdown__actions {
    display: flex;
    align-items: center;
    justify-content: center;
    text-align: center;
    min-height: 200px;
    color: var(--quiet-text-muted);
    background-color: var(--quiet-paper-color);
    border: dashed var(--quiet-border-width) var(--quiet-neutral-stroke-soft);
    border-radius: var(--quiet-border-radius);
    padding: 1rem;

    &:focus {
      outline: none;
    }

    &:focus-visible {
      outline: var(--quiet-focus-ring);
      outline-offset: calc(var(--quiet-border-width) * -1);
    }
  }
</style>

The context menu element must be in the DOM when the dropdown is connected, otherwise the dropdown won't be attached and a warning will be shown in the console.

API Jump to heading

Importing Jump to heading

The autoloader is the recommended way to import components but, if you prefer to do it manually, the following code snippets will be helpful.

CDN

npm

To manually import <quiet-dropdown> from the CDN, use the following code.

import 'https://cdn.jsdelivr.net/npm/@quietui/quiet@1.0.0/dist/components/dropdown/dropdown.js';

To manually import <quiet-dropdown> from npm, use the following code.

import '@quietui/quiet/dist/components/dropdown/dropdown.js';

Slots Jump to heading

Dropdown supports the following slots. Learn more about using slots

Name	Description
(default)	One or more `<dropdown-item>` elements to show in the dropdown. You can also use `<quiet-divider>` here.
`trigger`	The dropdown's trigger. Must be a `<quiet-button>` or `<button>` element.

Properties Jump to heading

Dropdown has the following properties that can be set with corresponding attributes. In many cases, the attribute's name is the same as the property's name. If an attribute is different, it will be displayed after the property. Learn more about attributes and properties

Property / Attribute	Description	Type	Default
`open`	Opens or closes the dropdown.	`boolean`	`false`
`contextMenu` `context-menu`	The ID of an element to apply the dropdown as a context menu.	`string`	`''`
`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.	`'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.	`number`	`0`
`offset`	The offset of the dropdown menu along its trigger.	`number`	`0`

Events Jump to heading

Dropdown dispatches the following custom events. You can listen to them the same way was native events. Learn more about custom events

Name	Description
`quiet-open`	Emitted when the dropdown is instructed to open but before it is shown.
`quiet-opened`	Emitted when the dropdown menu has opened and the animation has completed.
`quiet-close`	Emitted when the dropdown is dismissed but before it is hidden.
`quiet-closed`	Emitted when the dropdown menu has closed and the animation has completed.
`quiet-select`	Emitted when a dropdown item has been selected. You can inspect `event.detail.item` to see the `<quiet-dropdown-item>` that was selected. Calling `event.preventDefault()` will keep the dropdown open.

CSS custom properties Jump to heading

Dropdown supports the following CSS custom properties. You can style them like any other CSS property. Learn more about CSS custom properties

Name	Description	Default
`--show-duration`	The duration of the show/hide animation.	`50ms`

CSS parts Jump to heading

Dropdown exposes internal elements that can be styled with CSS using the selectors shown below. Learn more about CSS parts

Name	Description	CSS selector
`menu`	The dropdown menu's container.	`::part(menu)`

Custom States Jump to heading

Dropdown has the following custom states. You can target them with CSS using the selectors shown below. Learn more about custom states

Name	Description	CSS selector
`open`	Applied when the dropdown is open.	`:state(open)`

Dependencies Jump to heading

Dropdown automatically imports the following elements. Sub-dependencies are also included in this list.

<quiet-dropdown-item>

Dropdown

Getting the selected item Jump to heading #

Showing icons Jump to heading #

Showing labels & dividers Jump to heading #

Showing details Jump to heading #

Checkable items Jump to heading #

Destructive items Jump to heading #

Disabling items Jump to heading #

Changing the placement Jump to heading #

Context menus Jump to heading #

API Jump to heading #

Importing Jump to heading #

Slots Jump to heading #

Properties Jump to heading #

Events Jump to heading #

CSS custom properties Jump to heading #

CSS parts Jump to heading #

Custom States Jump to heading #

Dependencies Jump to heading #