Dropdown

The Dropdown component provides a flexible way to display a menu of options when a user interacts with a trigger element. Dropdowns are commonly used for navigation menus, action lists, and other UI interactions where you want to conserve space while providing multiple options. They are distinct from form selection controls and are not intended for form field selection.

Basic Usage

The Dropdown component can be used with various trigger elements, such as buttons, chips, or lozenges. The content inside the dropdown slot becomes the trigger element that opens the dropdown menu when clicked.

Chips

Lozange

<template>
  <div class="spr-flex spr-items-center spr-gap-4">
    <!-- Button trigger dropdown -->
    <spr-dropdown
      id="sample-dropdownBasic1"
      v-model="dropdownModel.dropdownBasic1"
      :menu-list="menuList"
      width="100px"
      popper-width="200px"
    >
      <spr-button class="spr-w-full" tone="success" has-icon>
        <span>Button</span>
        <Icon icon="ph:caret-down" />
      </spr-button>
    </spr-dropdown>

    <!-- Chips trigger dropdown -->
    <spr-dropdown
      id="sample-dropdownBasic2"
      v-model="dropdownModel.dropdownBasic2"
      :menu-list="menuList"
      width="100px"
      popper-width="200px"
    >
      <spr-chips class="spr-w-full" label="Chips" />
    </spr-dropdown>

    <!-- Lozenge trigger dropdown -->
    <spr-dropdown
      id="sample-dropdownBasic3"
      v-model="dropdownModel.dropdownBasic3"
      :menu-list="menuList"
      width="100px"
      popper-width="200px"
    >
      <spr-lozenge class="spr-w-full" label="Lozange" />
    </spr-dropdown>
  </div>
</template>

<script lang="ts" setup>
import { ref, watch } from 'vue';
import { Icon } from '@iconify/vue';

const dropdownModel = ref({
  dropdownBasic1: '',
  dropdownBasic2: '',
  dropdownBasic3: '',
});

const menuList = ref([
  { text: 'Google', value: 'https://www.google.com' },
  { text: 'GitHub', value: 'https://github.com' },
  { text: 'Gmail', value: 'https://mail.google.com' },
]);
</script>

Placements

The dropdown menu can be positioned in various ways relative to the trigger element. The placement prop controls where the dropdown menu appears.

Available placement options:

• auto, auto-start, auto-end - Automatically determine the best placement
• top, top-start, top-end - Position above the trigger
• right, right-start, right-end - Position to the right of the trigger
• bottom, bottom-start, bottom-end - Position below the trigger (default)
• left, left-start, left-end - Position to the left of the trigger

<template>
  <!-- Auto placement -->
  <spr-dropdown id="dropdown-auto" v-model="selectedValue" :menu-list="menuList" placement="auto" popper-width="200px">
    <spr-button class="spr-w-full" tone="success" has-icon>
      <span>Auto</span>
      <Icon icon="ph:caret-down" />
    </spr-button>
  </spr-dropdown>

  <!-- Top placement -->
  <spr-dropdown id="dropdown-top" v-model="selectedValue" :menu-list="menuList" placement="top" popper-width="200px">
    <spr-button class="spr-w-full" tone="success" has-icon>
      <span>Top</span>
      <Icon icon="ph:caret-down" />
    </spr-button>
  </spr-dropdown>
</template>

Width and Popper Width

The Dropdown component provides two ways to control the sizing:

• width: Controls the overall width of the dropdown wrapper (including the trigger element)
• popper-width: Controls the width of just the dropdown menu that appears when clicked

<template>
  <spr-dropdown
    id="sample-dropdownWidth"
    v-model="dropdownWidth"
    :menu-list="menuList"
    width="50%"
    popper-width="500px"
  >
    <spr-button class="spr-w-full" tone="success" has-icon>
      <span>Button</span>
      <Icon icon="ph:caret-down" />
    </spr-button>
  </spr-dropdown>
</template>

Popper Strategy

When using dropdowns inside positioned elements like modals or fixed panels, you may need to change the positioning strategy. The popper-strategy prop controls how the dropdown menu is positioned:

• absolute (default): Positions the dropdown relative to its nearest positioned ancestor
• fixed: Positions the dropdown relative to the viewport, ignoring parent element positioning

<template>
  <spr-button tone="success" @click="modalModel = true">Open Modal</spr-button>

  <spr-modal v-model="modalModel" title="Dropdown with Modal">
    <spr-dropdown
      id="sample-dropdownStrategy"
      v-model="dropdownStrategy"
      :menu-list="menuList"
      wrapper-position="initial"
      popper-strategy="fixed"
      width="100px"
    >
      <spr-button class="spr-w-full" tone="success" has-icon>
        <span>Button</span>
        <Icon icon="ph:caret-down" />
      </spr-button>
    </spr-dropdown>
    <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit...</p>
  </spr-modal>
</template>

<script setup>
import { ref } from 'vue';

const modalModel = ref(false);
const dropdownStrategy = ref('');
</script>

Important Note

When using the fixed popper strategy, you should also set wrapper-position="initial" to override the default relative positioning. This prevents positioning conflicts within complex layouts like modals.

Custom Popper Content

You can customize the content of the dropdown menu by using the popper slot. This allows you to include any custom HTML or components inside the dropdown.

<template>
  <spr-dropdown
    id="sample-dropdownCustomPopper"
    width="150px"
    :triggers="['hover', 'click']"
    :popper-triggers="['hover', 'click']"
    popper-width="500px"
  >
    <spr-button class="spr-w-full" tone="success" has-icon>
      <span>Custom Popper</span>
      <Icon icon="ph:caret-down" />
    </spr-button>

    <template #popper>
      <h5 class="spr-text-center">This is a custom popper!</h5>
    </template>
  </spr-dropdown>
</template>

API Reference

Props

Name	Description	Type	Default
id	Required. Unique identifier for the dropdown, used to bind the popper to the correct element	string	-
model-value	The selected value(s) in the dropdown. Bound with v-model	string | number | object | Array	[]
menu-list	List of options to display in the dropdown menu. Can be formatted as: - Array of objects with text and value properties - Array of strings - Array of custom objects (use with textField and valueField)	array	[]
text-field	When using custom objects in menuList, specifies which property to use for display text	string	'text'
value-field	When using custom objects in menuList, specifies which property to use for the value	string	'value'
search-string	Search term to filter the dropdown options	string	''
multiSelect	When true, allows selecting multiple options from the dropdown	boolean	false
group-items-by	Groups the dropdown items alphabetically	'A-Z' | 'Z-A'	-
placement	Controls the position of the dropdown menu relative to the trigger	'auto' | 'auto-start' | 'auto-end' | 'top' | 'top-start' | 'top-end' | 'right' | 'right-start' | 'right-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end'	'bottom'
wrapper-position	CSS position value for the dropdown wrapper	string	'relative'
width	Width of the dropdown wrapper (including the trigger element)	string	'100%'
popper-width	Width of the dropdown menu that appears when triggered	string	'100%'
popper-inner-width	Width of the inner content area of the dropdown menu	string	'unset'
popper-strategy	Positioning strategy for the dropdown menu, especially important in modals	'absolute' | 'fixed'	'absolute'
disabled	When true, disables the dropdown from being opened	boolean	false
ladderized	When true, enables hierarchical dropdown options (nested menus)	boolean	false
remove-current-level-in-back-label	For ladderized dropdowns, controls the back label behavior	boolean	false
no-check-in-list	When true, hides the checkmark icons in the dropdown list	boolean	false
lozenge	When true, enables lozenge list display.	boolean	false
triggers	Array of events that will trigger the dropdown to open	'click' | 'hover' | 'focus' | 'touch'[]	['click']
popper-triggers	Array of events that will trigger the dropdown menu (popper element) to open	'click' | 'hover' | 'focus' | 'touch'[]	[]
auto-hide	When true, automatically hides the dropdown when clicking outside it	boolean	true

Events

Name	Description	Parameters
update:modelValue	Emitted when the selected value(s) change	The new selected value(s)
@infinite-scroll-trigger	Emitted when the user scrolls to the bottom of the dropdown list, useful for implementing lazy loading	Boolean
@popper-state	Event emitted when you open or close the popper	Bolean

Slots

Name	Description
default	The trigger element that opens the dropdown when clicked (typically a button, chips, or lozenge)
popper	Custom elements for popper content.

Product Uses

These Sprout products use the Dropdown component: