Button Dropdown

The Button Dropdown component combines two buttons with a dropdown menu, allowing users to trigger a primary action or select from a list of related options. This component is ideal for scenarios where a single button action is accompanied by additional, secondary actions accessible via a dropdown. It supports customization for tone, size, variant, and can be disabled as needed.

Basic Usage

<template>
  <div class="spr-flex spr-items-center spr-gap-2">
    <spr-button-dropdown
      dropdown-id="example1"
      v-model="selected"
      :menu-list="menuList"
      width="160px"
      popper-width="160px"
      @click="mainButtonClicked"
    >
      Button Dropdown
    </spr-button-dropdown>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
const selected = ref([]);
const menuList = ref([
  {
    text: 'Add',
    value: 'add',
    icon: 'ph:check',
    iconColor: 'spr-text-color-supporting',
    onClickFn: () => {
      alert('Add was clicked.');
    },
  },
  {
    text: 'Delete',
    value: 'delete',
    icon: 'ph:trash',
    textColor: 'spr-text-color-danger-base',
    onClickFn: () => {
      alert('Delete was clicked.');
    },
  },
]);

const mainButtonClicked = () => {
  alert('Main button was clicked.');
};
</script>

Tone

<spr-button-dropdown dropdown-id="example2" v-model="selectedNeutral" :menu-list="menuList" tone="neutral">
  Neutral
</spr-button-dropdown>
<spr-button-dropdown dropdown-id="example3" v-model="selectedSuccess" :menu-list="menuList" tone="success">
  Success
</spr-button-dropdown>

Sizes

<spr-button-dropdown v-model="selectedSmall" dropdown-id="example4" :menu-list="menuList" size="small">
  Small
</spr-button-dropdown>
<spr-button-dropdown v-model="selectedMedium" dropdown-id="example5" :menu-list="menuList">
  Medium
</spr-button-dropdown>
<spr-button-dropdown v-model="selectedLarge" dropdown-id="example6" :menu-list="menuList" size="large">
  Large
</spr-button-dropdown>

Variant

<spr-button-dropdown v-model="selectedPrimary" dropdown-id="example7" :menu-list="menuList" variant="primary">
  Primary
</spr-button-dropdown>
<spr-button-dropdown v-model="selectedSecondary" dropdown-id="example8" :menu-list="menuList" variant="secondary">
  Secondary
</spr-button-dropdown>

Disabled

<spr-button-dropdown v-model="selectedDisabled" dropdown-id="example9" :menu-list="menuList" disabled>
  Disabled
</spr-button-dropdown>
<spr-button-dropdown
  v-model="selectedDisabled"
  dropdown-id="example9"
  :menu-list="menuList"
  variant="secondary"
  disabled
>
  Disabled
</spr-button-dropdown>

API Reference

Props

Name	Description	Type	Default
modelValue	Currently selected menu item(s). Used with v-model for two-way binding to track selections in the dropdown menu.	MenuListType[] | string[] | Record<string, unknown>[]	[]
menuList	Array of options to display in the dropdown menu. Each item can include: text: Display text for the menu item value: Unique identifier for the menu item icon: Optional Iconify icon name iconColor: Optional CSS class for icon color textColor: Optional CSS class for text color onClickFn: Optional callback function when item is clicked disabled: Optional boolean to disable specific menu items	MenuListType[] | string[] | Record<string, unknown>[]	[]
dropdownId	Required unique identifier for the dropdown component. Used for accessibility and state management.	string	Required
tone	Controls the color theme of the button dropdown. Options: neutral: Standard appearance success: Green appearance for positive actions Note: Unlike the standard button component, danger tone is not available for button-dropdown.	'neutral' | 'success'	'neutral'
variant	Controls the visual style of the button dropdown. Options: primary: Solid background with stronger emphasis secondary: Outlined style with medium emphasis Note: Unlike the standard button component, tertiary variant is not available.	'primary' | 'secondary'	'primary'
size	Controls the size of the button dropdown, affecting padding, font size, and overall dimensions.	'small' | 'medium' | 'large'	'medium'
disabled	When set to true, both the main button and dropdown trigger become non-interactive and appear visually disabled.	boolean	false
width	Sets the width of the entire button dropdown component. Can be any valid CSS width value.	string	'fit-content'
popperWidth	Sets the width of the dropdown menu container. Can be any valid CSS width value.	string	'fit-content'
popperInnerWidth	Sets the width of the content inside the dropdown menu. Useful for fine-tuning the layout.	string	'unset'
placement	Controls the position of the dropdown menu relative to the button. Common values: bottom: Opens below the button (default) top: Opens above the button left: Opens to the left of the button right: Opens to the right of the button Variants with -start or -end align the menu to the beginning or end of the button.	'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'

Events

Event	Payload	Description
click	MouseEvent	Emitted when the main (left) button is clicked. This event allows you to trigger a primary action when the main button is clicked, separate from the dropdown functionality.
update:modelValue	MenuListType[] | string[] | Record<string, unknown>[]	Emitted when a selection is made in the dropdown menu. Used for v-model binding to update the selected values. The payload contains the complete selection data.

Slots

Name	Description
default	Content for the main (left) button. This can include text, icons, or other elements. The dropdown button (right) always displays a caret-down icon and cannot be customized through slots.

Component Structure

The Button Dropdown consists of three main parts:

1. Main Button: The larger button on the left that triggers the primary action via the click event
2. Dropdown Trigger: The smaller button on the right with a caret icon that opens the dropdown menu
3. Dropdown Menu: The menu that appears when the dropdown trigger is clicked, containing the options specified in menuList

MenuListType Interface

// Key structure of objects that can be used in the menuList prop
type MenuListType = {
  text: string;                        // Display text for the menu item
  value: string | number;              // Unique identifier for the item
  icon?: string;                       // Optional Iconify icon name
  iconColor?: string;                  // CSS class for icon color
  textColor?: string;                  // CSS class for text color
  onClickFn?: () => void;              // Function to call when item is clicked
  disabled?: boolean;                  // Whether the item is disabled
  // Additional optional properties
  subtext?: string;                    // Secondary text line
  subvalue?: string;                   // Secondary value
  sublevel?: MenuListType[];           // Nested menu items (for hierarchical menus)
  group?: string;                      // Grouping identifier
};