Flutter Dropdown Button

A highly customizable dropdown package for Flutter with overlay-based rendering, smooth animations, and specialized variants for different content types.

pub package License: MIT

Features

  • 🎨 Highly Customizable: Complete control over appearance and behavior
  • 📱 Overlay-based Rendering: Better positioning and visual effects
  • ✨ Smooth Animations: Scale and fade effects with configurable timing
  • 🎯 Outside-tap Dismissal: Automatic closure when tapping outside
  • 📏 Dynamic Width: Fixed, min/max width constraints, or content-based sizing
  • 📐 Independent Menu Width: Set menu width separately from button with min/max constraints and alignment control
  • 📝 Text Overflow Control: Ellipsis, fade, clip, or visible overflow options
  • 🎭 Multiple Variants: Generic BasicDropdownButton and specialized TextOnlyDropdownButton
  • 🎨 Shared Theme System: Consistent styling across all dropdown variants
  • 📜 Custom Scrollbar: Scrollbar theming with colors, thickness, and visibility options
  • ♿ Accessibility Support: Screen reader friendly with proper semantics

Screenshots

Basic Text Dropdown Icon + Text Dropdown with Hover
Basic Text Dropdown
Simple text options with customizable styles		 Icon + Text Dropdown
Rich content with icons and hover effects

Variants

BasicDropdownButton

Generic dropdown supporting any widget as items with complete customization.

TextOnlyDropdownButton

Specialized dropdown for text content with precise text rendering control.

Quick Start

Add to your pubspec.yaml:

dependencies:
  flutter_dropdown_button: ^1.4.8

Import the package:

import 'package:flutter_dropdown_button/flutter_dropdown_button.dart';

Basic Usage

BasicDropdownButton

BasicDropdownButton<String>(
  items: [
    DropdownItem(
      value: 'apple',
      child: Row(
        children: [
          Icon(Icons.apple),
          SizedBox(width: 8),
          Text('Apple'),
        ],
      ),
    ),
    DropdownItem(
      value: 'banana',
      child: Text('Banana'),
    ),
  ],
  value: selectedValue,
  hint: Text('Select a fruit'),
  onChanged: (value) {
    setState(() {
      selectedValue = value;
    });
  },
)

TextOnlyDropdownButton

TextOnlyDropdownButton(
  items: [
    'Short',
    'Medium length text',
    'Very long text that demonstrates overflow behavior',
  ],
  value: selectedText,
  hint: 'Select an option',
  maxWidth: 200,
  config: TextDropdownConfig(
    overflow: TextOverflow.ellipsis,
    maxLines: 1,
  ),
  onChanged: (value) {
    setState(() {
      selectedText = value;
    });
  },
)

Advanced Features

Custom Theme

TextOnlyDropdownButton(
  // ... other properties
  theme: DropdownStyleTheme(
    dropdown: DropdownTheme(
      borderRadius: 12.0,
      elevation: 4.0,
    ),
    scroll: DropdownScrollTheme(
      thickness: 8.0,
      thumbColor: Colors.blue,
    ),
  ),
)

Text Configuration

TextOnlyDropdownButton(
  // ... other properties
  config: TextDropdownConfig(
    overflow: TextOverflow.fade,
    maxLines: 2,
    textStyle: TextStyle(fontSize: 16),
    textAlign: TextAlign.center,
  ),
)

Dynamic Width

BasicDropdownButton<String>(
  // ... other properties
  maxWidth: 300,        // Maximum width constraint
  minWidth: 150,        // Minimum width constraint
  // OR
  width: 250,           // Fixed width
)

Menu Width & Alignment

TextOnlyDropdownButton(
  // ... other properties
  width: 120,              // Button width
  minMenuWidth: 250,       // Menu minimum width (wider than button)
  maxMenuWidth: 400,       // Menu maximum width
  menuAlignment: MenuAlignment.left,  // left (default), center, or right
)

Documentation

For detailed documentation and advanced usage examples, see:

Example

Check out the example app for a comprehensive demonstration of all features and customization options.

Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG.md for a detailed list of changes and version history.

Libraries

flutter_dropdown_button