> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thehuxdesign.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dropdown

> A customizable dropdown/select component with various styles and variants

## Overview

`HuxDropdown` is a versatile dropdown/select component that provides multiple visual variants, sizes, and supports custom item rendering with icons. It adapts seamlessly to light and dark themes.

## Basic Usage

```dart theme={null}
HuxDropdown<String>(
  items: [
    HuxDropdownItem(
      value: 'item1',
      child: Text('Item 1'),
    ),
    HuxDropdownItem(
      value: 'item2',
      child: Text('Item 2'),
    ),
  ],
  value: selectedValue,
  onChanged: (value) => setState(() => selectedValue = value),
  placeholder: 'Select option',
)
```

## Variants

HuxDropdown supports four visual variants through the `HuxButtonVariant` enum:

### Primary

The default variant with a filled background using the primary color.

<img src="https://mintcdn.com/thehuxdesign/rQ2qJI8cg-lXeGhU/images/dropdown/dropdown-primary.png?fit=max&auto=format&n=rQ2qJI8cg-lXeGhU&q=85&s=b9103e09d0b9a0827c180ba99c2982a9" alt="Primary Dropdown" width="1400" height="300" data-path="images/dropdown/dropdown-primary.png" />

```dart theme={null}
HuxDropdown(
  items: [
    HuxDropdownItem(
      value: 'item1',
      child: Text('Item 1'),
    ),
    HuxDropdownItem(
      value: 'item2',
      child: Text('Item 2'),
    ),
  ],
  value: selectedValue,
  onChanged: (value) => setState(() => selectedValue = value),
  placeholder: 'Select option',
  variant: HuxButtonVariant.primary,
)
```

### Secondary

A subtle variant with a light background and border.

<img src="https://mintcdn.com/thehuxdesign/rQ2qJI8cg-lXeGhU/images/dropdown/dropdown-secondary.png?fit=max&auto=format&n=rQ2qJI8cg-lXeGhU&q=85&s=81c91a2d5ed2bcd1bf83336c7a561b29" alt="Secondary Dropdown" width="1400" height="300" data-path="images/dropdown/dropdown-secondary.png" />

```dart theme={null}
HuxDropdown(
  items: [
    HuxDropdownItem(
      value: 'item1',
      child: Text('Item 1'),
    ),
    HuxDropdownItem(
      value: 'item2',
      child: Text('Item 2'),
    ),
  ],
  value: selectedValue,
  onChanged: (value) => setState(() => selectedValue = value),
  placeholder: 'Select option',
  variant: HuxButtonVariant.secondary,
)
```

### Outline

A transparent dropdown with only a border outline.

<img src="https://mintcdn.com/thehuxdesign/rQ2qJI8cg-lXeGhU/images/dropdown/dropdown-outline.png?fit=max&auto=format&n=rQ2qJI8cg-lXeGhU&q=85&s=c29f3b2fd682174940e28cdfbc48cdca" alt="Outline Dropdown" width="1400" height="300" data-path="images/dropdown/dropdown-outline.png" />

```dart theme={null}
HuxDropdown(
  items: [
    HuxDropdownItem(
      value: 'item1',
      child: Text('Item 1'),
    ),
    HuxDropdownItem(
      value: 'item2',
      child: Text('Item 2'),
    ),
  ],
  value: selectedValue,
  onChanged: (value) => setState(() => selectedValue = value),
  placeholder: 'Select option',
  variant: HuxButtonVariant.outline,
)
```

### Ghost

A minimal transparent dropdown without borders.

<img src="https://mintcdn.com/thehuxdesign/rQ2qJI8cg-lXeGhU/images/dropdown/dropdown-ghost.png?fit=max&auto=format&n=rQ2qJI8cg-lXeGhU&q=85&s=70c593b9380765272484fdf8ea3ac866" alt="Ghost Dropdown" width="1400" height="300" data-path="images/dropdown/dropdown-ghost.png" />

```dart theme={null}
HuxDropdown(
  items: [
    HuxDropdownItem(
      value: 'item1',
      child: Text('Item 1'),
    ),
    HuxDropdownItem(
      value: 'item2',
      child: Text('Item 2'),
    ),
  ],
  value: selectedValue,
  onChanged: (value) => setState(() => selectedValue = value),
  placeholder: 'Select option',
  variant: HuxButtonVariant.ghost,
)
```

## States

### Default

Shows the placeholder text when no value is selected.

<img src="https://mintcdn.com/thehuxdesign/rQ2qJI8cg-lXeGhU/images/dropdown/dropdown-default.png?fit=max&auto=format&n=rQ2qJI8cg-lXeGhU&q=85&s=e04d3089cf65a3465b680e93f224c841" alt="Dropdown Default" width="1400" height="300" data-path="images/dropdown/dropdown-default.png" />

```dart theme={null}
HuxDropdown<String>(
  items: [
    HuxDropdownItem(
      value: 'item1',
      child: Text('Item 1'),
    ),
    HuxDropdownItem(
      value: 'item2',
      child: Text('Item 2'),
    ),
  ],
  value: null,
  onChanged: (value) => setState(() => selectedValue = value),
  placeholder: 'Select option',
)
```

### Expanded

Shows the dropdown panel with options.

<img src="https://mintcdn.com/thehuxdesign/rQ2qJI8cg-lXeGhU/images/dropdown/dropdown-expanded.png?fit=max&auto=format&n=rQ2qJI8cg-lXeGhU&q=85&s=3d46586a985733373472c5c8a23f9c55" alt="Dropdown Expanded" width="1400" height="430" data-path="images/dropdown/dropdown-expanded.png" />

```dart theme={null}
HuxDropdown<String>(
  items: [
    HuxDropdownItem(
      value: 'item1',
      child: Text('Item 1'),
    ),
    HuxDropdownItem(
      value: 'item2',
      child: Text('Item 2'),
    ),
    HuxDropdownItem(
      value: 'item3',
      child: Text('Item 3'),
    ),
  ],
  value: selectedValue,
  onChanged: (value) => setState(() => selectedValue = value),
  placeholder: 'Select option',
)
```

### Selected

Shows the selected option.

<img src="https://mintcdn.com/thehuxdesign/rQ2qJI8cg-lXeGhU/images/dropdown/dropdown-selected.png?fit=max&auto=format&n=rQ2qJI8cg-lXeGhU&q=85&s=90c8ad91a43311faf3d28571d3afb676" alt="Dropdown Selected" width="1400" height="300" data-path="images/dropdown/dropdown-selected.png" />

```dart theme={null}
HuxDropdown<String>(
  items: [
    HuxDropdownItem(
      value: 'item1',
      child: Text('Item 1'),
    ),
    HuxDropdownItem(
      value: 'item2',
      child: Text('Item 2'),
    ),
  ],
  value: 'Item 1',
  onChanged: (value) => setState(() => selectedValue = value),
  placeholder: 'Select option',
)
```

### Disabled

Prevents user interaction.

<img src="https://mintcdn.com/thehuxdesign/rQ2qJI8cg-lXeGhU/images/dropdown/dropdown-disabled.png?fit=max&auto=format&n=rQ2qJI8cg-lXeGhU&q=85&s=15c502ebbd203e2260f2425ae3ecb099" alt="Dropdown Disabled" width="1400" height="300" data-path="images/dropdown/dropdown-disabled.png" />

```dart theme={null}
HuxDropdown<String>(
  items: [
    HuxDropdownItem(
      value: 'item1',
      child: Text('Item 1'),
    ),
    HuxDropdownItem(
      value: 'item2',
      child: Text('Item 2'),
    ),
  ],
  value: selectedValue,
  onChanged: null, // or enabled: false
  placeholder: 'Select option',
  enabled: false,
)
```

## Sizes

HuxDropdown supports three size variants through the `HuxButtonSize` enum:

### Small

Compact size for tight spaces (32px height).

<img src="https://mintcdn.com/thehuxdesign/rQ2qJI8cg-lXeGhU/images/dropdown/dropdown-small.png?fit=max&auto=format&n=rQ2qJI8cg-lXeGhU&q=85&s=f9fbf22a59316cec2071fcaa5e888c93" alt="Small Dropdown" width="1400" height="300" data-path="images/dropdown/dropdown-small.png" />

```dart theme={null}
HuxDropdown<String>(
  items: [
    HuxDropdownItem(
      value: 'item1',
      child: Text('Item 1'),
    ),
    HuxDropdownItem(
      value: 'item2',
      child: Text('Item 2'),
    ),
  ],
  value: selectedValue,
  onChanged: (value) => setState(() => selectedValue = value),
  placeholder: 'Select option',
  size: HuxButtonSize.small,
)
```

### Medium

Default size for most use cases (40px height).

<img src="https://mintcdn.com/thehuxdesign/rQ2qJI8cg-lXeGhU/images/dropdown/dropdown-medium.png?fit=max&auto=format&n=rQ2qJI8cg-lXeGhU&q=85&s=4f362733ddaed123b84bcb7e6f11f4f4" alt="Medium Dropdown" width="1400" height="300" data-path="images/dropdown/dropdown-medium.png" />

```dart theme={null}
HuxDropdown<String>(
  items: [
    HuxDropdownItem(
      value: 'item1',
      child: Text('Item 1'),
    ),
    HuxDropdownItem(
      value: 'item2',
      child: Text('Item 2'),
    ),
  ],
  value: selectedValue,
  onChanged: (value) => setState(() => selectedValue = value),
  placeholder: 'Select option',
  size: HuxButtonSize.medium, // Default
)
```

### Large

Prominent size for important selections (48px height).

<img src="https://mintcdn.com/thehuxdesign/rQ2qJI8cg-lXeGhU/images/dropdown/dropdown-large.png?fit=max&auto=format&n=rQ2qJI8cg-lXeGhU&q=85&s=a3c888ec4593488b36001acd4b10cd21" alt="Large Dropdown" width="1400" height="300" data-path="images/dropdown/dropdown-large.png" />

```dart theme={null}
HuxDropdown<String>(
  items: [
    HuxDropdownItem(
      value: 'item1',
      child: Text('Item 1'),
    ),
    HuxDropdownItem(
      value: 'item2',
      child: Text('Item 2'),
    ),
  ],
  value: selectedValue,
  onChanged: (value) => setState(() => selectedValue = value),
  placeholder: 'Select option',
  size: HuxButtonSize.large,
)
```

## With Icons

Enhance dropdown items with icons.

<img src="https://mintcdn.com/thehuxdesign/rQ2qJI8cg-lXeGhU/images/dropdown/dropdown-icons.png?fit=max&auto=format&n=rQ2qJI8cg-lXeGhU&q=85&s=4ceb0ffdcf2361805141acc4248b2f59" alt="Dropdown with icons" width="1400" height="430" data-path="images/dropdown/dropdown-icons.png" />

```dart theme={null}
HuxDropdown<String>(
  items: [
    HuxDropdownItem(
      value: 'user',
      child: Row(
        children: [
          Icon(FeatherIcons.user, size: 16),
          SizedBox(width: 8),
          Text('User'),
        ],
      ),
    ),
    HuxDropdownItem(
      value: 'settings',
      child: Row(
        children: [
          Icon(FeatherIcons.settings, size: 16),
          SizedBox(width: 8),
          Text('Settings'),
        ],
      ),
    ),
  ],
  value: selectedValue,
  onChanged: (value) => setState(() => selectedValue = value),
  placeholder: 'Select option',
)
```

## Using Item Widget as Value

By default, HuxDropdown extracts and displays text from the selected item's widget. The `useItemWidgetAsValue` parameter allows you to display the complete item widget (including icons, badges, and complex layouts) as the selected value.

```dart theme={null}
HuxDropdown<String>(
  useItemWidgetAsValue: true, // Display full widget instead of just text
  items: [
    HuxDropdownItem(
      value: 'user',
      child: Row(
        children: [
          Icon(LucideIcons.user, size: 16),
          SizedBox(width: 8),
          Text('User'),
        ],
      ),
    ),
    HuxDropdownItem(
      value: 'settings',
      child: Row(
        children: [
          Icon(LucideIcons.settings, size: 16),
          SizedBox(width: 8),
          Text('Settings'),
        ],
      ),
    ),
  ],
  value: selectedValue,
  onChanged: (value) => setState(() => selectedValue = value),
  placeholder: 'Select option',
)
```

With this feature enabled, the selected value will show the complete widget with all its visual elements (icons, badges, custom layouts), providing a richer visual experience compared to text-only representation.

## Custom Colors

Override the primary color of the dropdown.

<img src="https://mintcdn.com/thehuxdesign/rQ2qJI8cg-lXeGhU/images/dropdown/dropdown-custom.png?fit=max&auto=format&n=rQ2qJI8cg-lXeGhU&q=85&s=45e04202fc7ded90fe90a8b8f8d341ad" alt="Custom Dropdown" width="1400" height="300" data-path="images/dropdown/dropdown-custom.png" />

```dart theme={null}
HuxDropdown(
  primaryColor: Colors.purple,
  // ...
)
```

## API Reference

### HuxDropdown Properties

| Property               | Type                       | Default           | Description                                                 |
| ---------------------- | -------------------------- | ----------------- | ----------------------------------------------------------- |
| `items`                | `List<HuxDropdownItem<T>>` | **required**      | List of dropdown items                                      |
| `value`                | `T?`                       | `null`            | Currently selected value                                    |
| `onChanged`            | `ValueChanged<T>?`         | `null`            | Called when selection changes                               |
| `placeholder`          | `String`                   | `'Select option'` | Text shown when no value is selected                        |
| `variant`              | `HuxButtonVariant`         | `outline`         | Visual style of the dropdown                                |
| `size`                 | `HuxButtonSize`            | `medium`          | Size of the dropdown                                        |
| `primaryColor`         | `Color?`                   | `null`            | Optional primary color override                             |
| `enabled`              | `bool`                     | `true`            | Whether the dropdown is enabled                             |
| `maxHeight`            | `double`                   | `200`             | Maximum height of the dropdown panel                        |
| `useItemWidgetAsValue` | `bool`                     | `false`           | Display the complete item widget instead of extracting text |

### HuxDropdownItem Properties

| Property | Type     | Default      | Description                         |
| -------- | -------- | ------------ | ----------------------------------- |
| `value`  | `T`      | **required** | The value associated with this item |
| `child`  | `Widget` | **required** | The widget to display for this item |

## Accessibility

HuxDropdown includes several accessibility features:

### Automatic Contrast

Text color is automatically calculated to ensure WCAG AA compliance (4.5:1 contrast ratio) against any background color.

### Keyboard Navigation

* Arrow keys to navigate items
* Enter/Space to open/close and select
* Escape to close dropdown

### Focus States

Proper focus management and visible focus indicators.

### Semantic Labels

Clear labels and roles for screen readers.

## Best Practices

<AccordionGroup>
  <Accordion title="Choose the Right Size" icon="ruler">
    * Use **Large** for primary selection fields
    * Use **Medium** for most standard forms
    * Use **Small** for compact interfaces or filters
  </Accordion>

  <Accordion title="Clear Labels" icon="type">
    * Use descriptive placeholders
    * Group related dropdowns logically
    * Consider adding helper text for complex selections
  </Accordion>

  <Accordion title="Item Organization" icon="list">
    * Keep items concise
    * Use icons to enhance visual scanning
    * Order items logically (e.g., alphabetically)
  </Accordion>
</AccordionGroup>

## Examples

<CardGroup cols={2}>
  <Card title="Form Building" icon="file-text" href="/examples/form-building">
    See dropdowns in action within forms
  </Card>

  <Card title="Custom Theming" icon="palette" href="/advanced/theming">
    Apply custom colors and themes
  </Card>

  <Card title="Accessibility" icon="accessibility" href="/advanced/accessibility">
    Ensure your dropdowns are accessible
  </Card>

  <Card title="Data Visualization" icon="chart-line" href="/examples/data-visualization">
    Use dropdowns for data filtering
  </Card>
</CardGroup>