aura
Home Aura
aura

Dropdown

Overview

The <aura:dropdown> component is a versatile UI element that displays a collapsible list of items triggered by a clickable element. It’s highly customizable, supporting different widths, alignments, and content types like buttons, radio inputs, checkboxes, and toggles. Built without external dependencies, it’s lightweight and adaptable for menus, selection lists, or interactive controls.

Attributes

The dropdown supports the following attributes:

  • width (String)
    Sets the width of the dropdown. Accepts predefined size classes (e.g., sm, min-lg) or custom values like auto.
    Default: auto

  • align (String)
    Controls the alignment of the dropdown relative to its trigger. See the "Alignment" section for valid options.
    Default: bottom

Slots

The component uses slots to define its structure:

  • trigger (Required)
    The element (e.g., a button) that toggles the dropdown’s visibility.

  • default
    The content displayed within the dropdown when opened, typically wrapped in <aura:dropdown.content>.

Alignment Options

The align attribute supports the following values, allowing precise positioning:

  • Bottom: .bottom, .bottom-start, .bottom-end
  • Top: .top, .top-start, .top-end
  • Left: .left, .left-start, .left-end
  • Right: .right, .right-start, .right-end

These options determine where the dropdown appears relative to the trigger, with -start and -end providing fine-tuned alignment (e.g., left-aligned or right-aligned within the chosen direction).

Usage Examples

Basic Usage

A simple dropdown with a button trigger and a list of items.

Copy to clipboard

<aura:dropdown>
    <aura:button solid text="Toggle Dropdown" />

    <aura:dropdown.content>
        <aura:dropdown.button text="Item 1" />
        <aura:dropdown.button text="Item 2" />
        <aura:dropdown.button text="Item 3" />
    </aura:dropdown.content>
</aura:dropdown>

Custom Width

Sets a minimum large width (min-lg) for the dropdown.

Copy to clipboard

<aura:dropdown min-lg>
    <aura:button solid text="Toggle Dropdown" />

    <aura:dropdown.content>
        <aura:dropdown.button text="Item 1" />
        <aura:dropdown.button text="Item 2" />
        <aura:dropdown.button text="Item 3" />
    </aura:dropdown.content>
</aura:dropdown>

Alignment Variations

Demonstrates different alignment options with small (sm) width for clarity.

Copy to clipboard

<aura:dropdown left> <!-- Content --> </aura:dropdown>
<aura:dropdown top> <!-- Content --> </aura:dropdown>
<aura:dropdown bottom> <!-- Content --> </aura:dropdown>
<aura:dropdown right> <!-- Content --> </aura:dropdown>

Uses <aura:dropdown.radio> for a radio button selection list.

Copy to clipboard

<aura:dropdown>
    <aura:button solid text="Toggle Dropdown" />
    <aura:dropdown.content>
        <aura:dropdown.radio label="Item 1" value="1" name="radio" checked/>
        <aura:dropdown.radio label="Item 2" value="2" name="radio" />
        <aura:dropdown.radio label="Item 3" value="3" name="radio" disabled />
    </aura:dropdown.content>
</aura:dropdown>

Uses <aura:dropdown.checkbox> for a multi-select checkbox list.

Copy to clipboard

<aura:dropdown>
    <aura:button solid text="Toggle Dropdown" />
    <aura:dropdown.content>
        <aura:dropdown.checkbox label="Item 1" value="1" name="checkbox-one" checked/>
        <aura:dropdown.checkbox label="Item 2" value="2" name="checkbox-two" />
        <aura:dropdown.checkbox label="Item 3" value="3" name="checkbox-three" disabled />
    </aura:dropdown.content>
</aura:dropdown>

Uses <aura:dropdown.toggle> for a list of toggle switches.

Copy to clipboard

<aura:dropdown>
    <aura:button solid text="Toggle Dropdown" />
    <aura:dropdown.content>
        <aura:dropdown.toggle label="Item 1" value="1" name="toggle-one" checked/>
        <aura:dropdown.toggle label="Item 2" value="2" name="toggle-two" />
        <aura:dropdown.toggle label="Item 3" value="3" name="toggle-three" disabled />
    </aura:dropdown.content>
</aura:dropdown>

Additional Styling Elements

Enhances the dropdown with headings and dividers using <aura:dropdown.heading> and <aura:dropdown.divider>.

Heading

Copy to clipboard

<aura:dropdown>
    <aura:button solid text="Toggle Dropdown" />
    <aura:dropdown.content>
        <aura:dropdown.heading text="Heading" />
        <aura:dropdown.button text="Item 1" />
        <aura:dropdown.button text="Item 2" />
        <aura:dropdown.divider />
        <aura:dropdown.button text="Item 3" />
    </aura:dropdown.content>
</aura:dropdown>

Notes

  • The trigger slot is mandatory and typically contains a <aura:button> or similar interactive element.
  • Use width to control the dropdown’s size (e.g., sm for small, min-lg for minimum large) and align to position it relative to the trigger.
  • The radio, checkbox, and toggle variants behave like their standard HTML counterparts but are styled for dropdown use.
  • Combine <aura:dropdown.heading> and <aura:dropdown.divider> to organize content visually within the dropdown.

This updated documentation is more detailed, structured, and developer-friendly, with clear examples and explanations. Let me know if you’d like further adjustments!