​
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

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',
)

​
Variants

HuxDropdown supports four visual variants through the HuxButtonVariant enum:

​
Primary

The default variant with a filled background using the primary color. Primary Dropdown 
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',
  variant: HuxButtonVariant.primary,
)

​
Secondary

A subtle variant with a light background and border. Secondary Dropdown 
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',
  variant: HuxButtonVariant.secondary,
)

​
Outline

A transparent dropdown with only a border outline. Outline Dropdown 
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',
  variant: HuxButtonVariant.outline,
)

​
Ghost

A minimal transparent dropdown without borders. Ghost Dropdown 
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',
  variant: HuxButtonVariant.ghost,
)

​
States

​
Default

Shows the placeholder text when no value is selected. Dropdown Default 
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',
)

​
Expanded

Shows the dropdown panel with options. Dropdown Expanded 
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',
)

​
Selected

Shows the selected option. Dropdown Selected 
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',
)

​
Disabled

Prevents user interaction. Dropdown Disabled 
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',
  enabled: false,
)

​
Sizes

HuxDropdown supports three size variants through the HuxButtonSize enum:

​
Small

Compact size for tight spaces (32px height). Small Dropdown 
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',
  size: HuxButtonSize.small,
)

​
Medium

Default size for most use cases (40px height). Medium Dropdown 
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',
  size: HuxButtonSize.medium, // Default
)

​
Large

Prominent size for important selections (48px height). Large Dropdown 
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',
  size: HuxButtonSize.large,
)

​
With Icons

Enhance dropdown items with icons. Dropdown with icons 
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',
)

​
Custom Colors

Override the primary color of the dropdown. Custom Dropdown 
HuxDropdown(
  primaryColor: Colors.purple,
  // ...
)

​
API Reference

​
HuxDropdown Properties

PropertyTypeDefaultDescription
itemsList<HuxDropdownItem<T>>requiredList of dropdown items
valueT?nullCurrently selected value
onChangedValueChanged<T>?nullCalled when selection changes
placeholderString'Select'Text shown when no value is selected
variantHuxButtonVariantoutlineVisual style of the dropdown
sizeHuxButtonSizemediumSize of the dropdown
primaryColorColor?nullOptional primary color override
enabledbooltrueWhether the dropdown is enabled
maxHeightdouble200Maximum height of the dropdown panel

​
HuxDropdownItem Properties

PropertyTypeDefaultDescription
valueTrequiredThe value associated with this item
childWidgetrequiredThe 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

​
Examples

Form Building

See dropdowns in action within forms

Custom Theming

Apply custom colors and themes

Accessibility

Ensure your dropdowns are accessible

Data Visualization

Use dropdowns for data filtering