---
metaTitle: Dropdown component | AwesCode UI
meta:
  - name: description
    content: The <AwDropdown /> component is used to render Dropdown - UI Vue component for AwesCode UI.
title: Dropdown
---

# Dropdown

**Category:** Atom | **Import:** Global

The `AwDropdown` component provides a positioned dropdown menu with mobile and desktop support.

## Overview

`AwDropdown` creates a dropdown menu that can be positioned relative to a target element using Popper.js. It supports both desktop (positioned) and mobile (fullscreen overlay) modes, with automatic detection based on screen size.

## Usage

### Basic Example (Recommended)

The recommended way to control the dropdown is by calling the `toggle()` method via ref:

```markup
<AwButton color="accent" @click="$refs.dropdown.toggle()">
    Toggle Dropdown
</AwButton>
<AwDropdown ref="dropdown">
    <AwDescription tag="div" class="p-4">
        Dropdown content
    </AwDescription>
</AwDropdown>
```

### With Dropdown Buttons

```markup
<AwButton color="accent" @click="$refs.dropdown.toggle()">
    Open Menu
</AwButton>
<AwDropdown ref="dropdown">
    <AwDropdownButton @click="handleAction">
        Option 1
    </AwDropdownButton>
    <AwDropdownButton color="error" @click="handleAction">
        Option 2
    </AwDropdownButton>
    <AwDropdownButton @click="handleAction">
        Option 3
    </AwDropdownButton>
</AwDropdown>
```

### With State Sync (Alternative)

If you need to track the dropdown state in your component, use `:show.sync`:

```markup
<AwButton color="accent" @click="show = !show">
    Open Menu
</AwButton>
<AwDropdown :show.sync="show">
    <AwDropdownButton @click="handleAction">
        Option 1
    </AwDropdownButton>
    <AwDropdownButton @click="handleAction">
        Option 2
    </AwDropdownButton>
</AwDropdown>
```

### With Target Selector

```markup
<AwButton id="trigger" color="accent" @click="show = !show">
    Toggle
</AwButton>

<div>Some other content between dropdown and button</div>

<AwDropdown target="#trigger" :show.sync="show">
    <AwDescription tag="div" class="p-4">
        Dropdown content
    </AwDescription>
</AwDropdown>
```

### With Title and Description (Mobile)

```markup
<AwButton color="accent" @click="show = !show">
    Open Menu
</AwButton>
<AwDropdown
    :show.sync="show"
    title="Menu Title"
    description="Menu description"
>
    <AwDescription tag="div" class="p-4">
        Content
    </AwDescription>
</AwDropdown>
```

## API

### Props

| Name | Description | Type | Required | Default |
|------|-------------|------|----------|---------|
| tag | HTML tag for dropdown container | `String` | `false` | `'div'` (from config) |
| target | Target element reference or selector | `String` / `Element` | `false` | `''` |
| options | Popper.js options object | `Object` | `false` | From config |
| closeOnAction | Close when action element is clicked | `Boolean` | `false` | `true` |
| show | Whether dropdown is visible | `Boolean` | `false` | `false` |
| closeOutside | Close when clicking outside | `Boolean` | `false` | `true` |
| title | Mobile dropdown title | `String` | `false` | `''` |
| description | Mobile dropdown description | `String` | `false` | `''` |
| titleTag | HTML tag for title | `String` | `false` | `'h3'` |

### Slots

| Name | Description | Props | Default Slot Content |
|------|-------------|-------|---------------------|
| default | Dropdown content | - | - |
| heading | Custom mobile heading | `{ title, description }` | Default title/description |
| close | Custom close button (mobile) | - | Default close button |

### Events

| Name | Payload | Description |
|------|---------|-------------|
| update:show | `boolean` | Emitted when visibility changes (for v-model) |

### Methods

| Name | Parameters | Description |
|------|-----------|-------------|
| toggle | - | Toggle dropdown visibility |

### Config Options

The component uses default configuration from `@AwConfig`:

```javascript
export default {
  AwDropdown: {
    tag: 'div',
    baseClass: 'aw-dropdown',
    popperOptions: {
      placement: 'bottom-start',
      // ... popper modifiers
    }
  }
}
```

## Related Components

- `AwDropdownButton` - Button for dropdown items
- `AwContextMenu` - Context menu component
- `AwSelect` - Select component that uses dropdowns

## Notes

- **Import Method:** Global - Available as atom component
- Uses Popper.js for positioning on desktop
- Automatically switches to mobile overlay mode on small screens
- Prevents body scrolling when open on mobile
- Closes automatically when clicking action elements (links, buttons) by default
- Supports custom Popper.js options for advanced positioning
- **Auto-target detection:** If no `target` prop is specified, the dropdown automatically uses the previous sibling element as the trigger
- **Recommended control method:** Use `$refs.dropdown.toggle()` for simple show/hide control. This is the preferred approach for most use cases
- **Alternative state management:** Use `:show.sync` only when you need to track or react to the dropdown's visibility state in your component
- **Available methods:** Call `toggle()`, `open()`, or `close()` methods directly via refs for programmatic control