Dropdown

Dropdown component

Repository status

Detailed changes for each release are documented in Changelog

If you are using vue 2.x version, please use v-dropdown 2.x version instead

Installation

Install v-dropdown component in to your project

npm

npm i v-dropdown

yarn

yarn add v-dropdown

pnpm

pnpm add v-dropdown

Usage

<template>
  <Dropdown @visible-change="change">
    <!-- trigger element -->
    <template #trigger>
      <button type="button">Click me</button>
    </template>

    <!-- contents display in dropdown -->
    <div>
      some contents
    </div>
  </Dropdown>
</template>

<script setup>
import Dropdown from 'v-dropdown'
// or
// import { Dropdown } from 'v-dropdown'
function change (val) {
  console.log(val)
}
</script>

Examples

Quick demo

<Dropdown>
  <!-- trigger element -->
  <template #trigger>
    <button type="button">Click me</button>
  </template>
  <!-- contents display in dropdown -->
  <div>some contents</div>
</Dropdown>

Dropdown component uses click-triggered objects by default to open the dropdown conatiner

trigger by hover

<Dropdown trigger="hover">
  <template #trigger>
    <button type="button">Hover me</button>
  </template>
  ...
</Dropdown>

trigger by contextmenu

<Dropdown
  trigger="contextmenu"
  :full-width="true"
>
  <template #trigger>
    <div>Mouse right click me</div>
  </template>
  ...
</Dropdown>

Mouse right click trigger container area to open dropdown container

Mouse right click me

close toggle

<Dropdown :toggle="false" >
  ...
</Dropdown>

Set the click to trigger the object cycle to switch the dropdown container open and closed, the effect also works on the mouse hover and the right mouse button menu trigger mode

Disabled

<Dropdown :disabled="true" >
  <!-- named scoped slots -->
  <template #trigger="{ visible, disabled }">
    <button
      type="button"
      :class="{
        'border-primary': visible.value,
        'bg-primary': visible.value,
        'bg-opacity-10': visible.value,
      }"
    >
      Click me (visible: {{ visible }}, disabled: {{ disabled }})
    </button>
  </template>
</Dropdown>

Manual

<template>
  <Dropdown
    :manual="true"
    ref="dropdownManual"
  >
    <template #trigger>
      <input
        type="text"
        @input="inputChange"
      />
    </template>
    ...
  </Dropdown>
</template>

<script setup>
import { ref } from 'vue'
const dropdownManual = ref(null)

function inputChange (e) {
  if (e.target.value === '3') {
    dropdownManual.value.display()
  } else {
    // Dropdown expose `visible` state
    if (dropdownManual.value.visible) {
      dropdownManual.value.close()
    }
  }
}
</script>

In this example, the dropdown container will only open when the number 3 is entered

No border

<Dropdown :border="false" >
  ...
</Dropdown>

Alignment direction

<Dropdown align="center" >
  ...
</Dropdown>

Specify container width

<Dropdown :width="500" >
  ...
</Dropdown>

Slots

In the Dropdown component, the trigger object and content are distributed using slots

trigger named scoped slots

Named scoped slots for placing trigger objects, which outputs the following component state

interface TriggerSlotData {
  visible: boolean  // the dropdown container visible status
  disabled: boolean // disabled status
}

<template>
  <Dropdown>
    <template #trigger>
      <button type="button">Click me</button>
    </template>
  </Dropdown>
</template>

Apply scoped slots status data

<template>
  <Dropdown>
    <template #trigger="{ visible }">
      <button
        type="button"
        :class="{ active: visible }"
      >Click me</button>
    </template>
  </Dropdown>
</template>

default

The default slot is used to place the content area in the dropdown container

<template>
  <Dropdown>
    <template #trigger>
      <button type="button">Click me</button>
    </template>

    <!-- contents display in dropdown default slot -->
    <div>
      some contents
    </div>
  </Dropdown>
</template>

Props

align

• type 'left' | 'center' | 'right'
• default 'left'

The dropdown container align to trigger container direction

TIP

Dropdown automatically determines the vertical orientation of the dropdown container (up or down) depending on the position of the screen

border

• type boolean
• default true

The dropdown container display border

toggle

• type boolean
• default true

Cyclically toggle the display/closing of the dropdown container

manual

• type boolean
• default false

Manual operation mode; when this mode is enabled, the trigger specified by trigger will no longer be able to open/close the drop-down bar, but can only be controlled by function calls, this mode is suitable for scenarios requiring precise control

disabled

• type boolean
• default false

Enabled / disabled Dropdown component

animated

• type boolean | string
• default true

To turn on/off the dropdown animation, in addition to setting on and off, you can also specify a string as the class name of the custom animation, the content of which needs to be defined externally

width

• type number

Specify the width of the dropdown container, or adapt to the content width if not specified

fullWidth

• type boolean
• default false

Trigger container display mode

• true block element box display: block
• false inline element boxes display: inline-block

trigger

• type 'click' | 'hover' | 'contextmenu'
• default 'click'

Open the dropdown container trigger method

customTriggerClass

• type string
• default ''

Add custom class to trigger container

customContainerClass

• type string
• default ''

Add custom class to dropdown container

Events

Component operation response events

visible-change

Respond to the state change of the dropdown container opening / closing

`visible-change`: (visible: boolean) => void

API

Before using component's API, need to declare a ref attribute for the component, declare a ref variable by ref() to hold the element reference(the name must match template ref value) and use it to call API methods

<template>
  <Dropdown ref="dropdown" />
</template>

<script setup>
import { ref } from 'vue'
import { Dropdown } from 'v-dropdown'

const dropdown = ref(null)
// call api
dropdown.value.display()
</script>

display

Display dropdown container

display: () => void

close

Close dropdown container

close: () => void

toggleVisible

Toggle dropdown visible state

toggleVisible: () => void

adjust

Detect and adjust dropdown container position, make the dropdown container align to the trigger container

adjust: () => void