Dropdown

Popover with a trigger and arbitrary content. Closes on outside click and on Escape, and can be driven programmatically.

Import

import { Dropdown, DropdownMenu } from 'vuiii'

Basic Usage

With no trigger slot it renders a Button labelled by label. The content is whatever you put in the default slot — DropdownMenu is the usual choice.

View in Storybook

<Dropdown label="Options" color="primary">
  <template #default="{ close }">
    <DropdownMenu :items="menuItems" @item-click="({ item }) => { run(item); close() }" />
  </template>
</Dropdown>

Close it yourself

The default slot receives close, because the dropdown cannot know which of your clicks should dismiss it. Picking a menu item usually should.

Props

Prop	Type	Default	Description
label	string	-	Label of the default button trigger
icon	string	-	Prefix icon of the default button trigger
color	ButtonColor	-	Color of the default button trigger
block	boolean	false	Makes the trigger full width
dropdownPlacement	'left' | 'right' | 'center'	-	Alignment of the popover against the trigger
fullDropdownWidth	boolean	false	Stretches the popover to the trigger's width

Slots

Slot	Description
default	Popover content. Props: { close }
trigger	Replaces the button trigger. Props: { open, close, toggle, isOpen }

Events

Event	Description
open	When the popover opens
close	When the popover closes

Custom Trigger

The trigger slot hands you the controls, so any element can open the popover.

<Dropdown>
  <template #trigger="{ toggle, isOpen }">
    <IconButton icon="pencil" title="Actions" @click="toggle()" />
  </template>

  <template #default="{ close }">
    <div class="custom-content">
      <button @click="doSomething(); close()">Action</button>
    </div>
  </template>
</Dropdown>

Placement

<Dropdown label="Menu" dropdown-placement="right">
  <DropdownMenu :items="items" />
</Dropdown>

Programmatic Control

A template ref exposes open, close, toggle and isOpen. isOpen arrives already unwrapped — read it as a plain boolean, not .value.

<script setup>
import { ref } from 'vue'
import type { DropdownRef } from 'vuiii'

const dropdownRef = ref<DropdownRef>()

dropdownRef.value?.open()
dropdownRef.value?.toggle()

if (dropdownRef.value?.isOpen) {
  // …
}
</script>

<template>
  <Dropdown ref="dropdownRef" label="Menu">
    <DropdownMenu :items="items" />
  </Dropdown>
</template>

Dismissal

Every open dropdown closes on an outside mousedown or on Escape, and the click still reaches the page underneath — so clicking straight into an input both closes the popover and focuses the field.

Storybook

For interactive examples with all variants, see Dropdown in Storybook.