Dropdown

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

Variants

HuxDropdown supports four visual variants through the HuxButtonVariant enum:

Primary

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

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.

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.

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.

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.

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.

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.

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.

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).

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).

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).

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.

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

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.

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.

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.

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

Choose the Right Size

Use Large for primary selection fields
Use Medium for most standard forms
Use Small for compact interfaces or filters

Clear Labels

Use descriptive placeholders
Group related dropdowns logically
Consider adding helper text for complex selections

Item Organization

Keep items concise
Use icons to enhance visual scanning
Order items logically (e.g., alphabetically)

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

Getting Started

Components

Advanced

Overview

Basic Usage

Variants

Primary

Secondary

Outline

Ghost

States

Default

Expanded

Selected

Disabled

Sizes

Small

Medium

Large

With Icons

Using Item Widget as Value

Custom Colors

API Reference

HuxDropdown Properties

HuxDropdownItem Properties

Accessibility

Automatic Contrast

Keyboard Navigation

Focus States

Semantic Labels

Best Practices

Examples

Form Building

Custom Theming

Accessibility

Data Visualization

​Overview

​Basic Usage

​Variants

​Primary

​Secondary

​Outline

​Ghost

​States

​Default

​Expanded

​Selected

​Disabled

​Sizes

​Small

​Medium

​Large

​With Icons

​Using Item Widget as Value

​Custom Colors

​API Reference

​HuxDropdown Properties

​HuxDropdownItem Properties

​Accessibility

​Automatic Contrast

​Keyboard Navigation

​Focus States

​Semantic Labels

​Best Practices

​Examples

Form Building

Custom Theming

Accessibility

Data Visualization

Overview

Basic Usage

Variants

Primary

Secondary

Outline

Ghost

States

Default

Expanded

Selected

Disabled

Sizes

Small

Medium

Large

With Icons

Using Item Widget as Value

Custom Colors

API Reference

HuxDropdown Properties

HuxDropdownItem Properties

Accessibility

Automatic Contrast

Keyboard Navigation

Focus States

Semantic Labels

Best Practices

Examples