Expert guidance for developing the flutter_dropdown_button package - a highly customizable Flutter dropdown with overlay-based rendering, smart positioning, and specialized variants for different content types.
Expert guidance for working with the `flutter_dropdown_button` Flutter package - a highly customizable dropdown system with overlay-based rendering and smart positioning.
This Flutter package provides two main dropdown variants with shared architecture:
Both variants leverage a shared `DropdownMixin` that eliminates code duplication and provides consistent behavior.
1. **DropdownMixin** (`src/dropdown_mixin.dart`)
- Provides ~150 lines of shared functionality between variants
- Smart positioning logic (auto-opens upward when space below is insufficient)
- Animation management (scale and opacity)
- Overlay lifecycle management
- Outside-tap dismissal
- Dynamic height adjustment to prevent screen overflow
2. **DropdownTheme** (`src/dropdown_theme.dart`)
- Shared theme system for consistent styling
3. **TextDropdownConfig** (`src/text_dropdown_config.dart`)
- Text-specific configuration for overflow, styling, and alignment
4. **DropdownItem** (`src/dropdown_item.dart`)
- Generic model for BasicDropdownButton items
```
lib/
├── flutter_dropdown_button.dart # Main export file
└── src/
├── basic_dropdown_button.dart # Generic dropdown widget
├── text_only_dropdown_button.dart # Text-specific dropdown widget
├── dropdown_mixin.dart # Shared functionality mixin
├── dropdown_theme.dart # Shared theme system
├── text_dropdown_config.dart # Text-specific configuration
└── dropdown_item.dart # Item model for BasicDropdownButton
```
When working on the package:
```bash
flutter pub get
flutter analyze
flutter pub run flutter_lints
dart format .
flutter test
flutter test test/flutter_dropdown_button_test.dart
```
When testing changes in the example app:
```bash
cd example && flutter run
cd example && flutter build web
```
Unlike Flutter's built-in `DropdownButton`, these widgets use `OverlayEntry` for better positioning control and visual effects. This allows for:
The `DropdownMixin.calculateDropdownPosition()` method implements intelligent positioning:
1. Calculates available space above and below the button
2. Prefers to open downward if sufficient space exists
3. Falls back to opening upward if more space is available above
4. Dynamically adjusts height when space is constrained
5. Ensures minimum visibility of items
When modifying positioning logic, ensure these behaviors are preserved.
Both dropdown variants use coordinated scale and opacity animations for smooth open/close transitions. The animation state is managed through the `DropdownMixin`.
1. **Determine scope**: Is this feature specific to one variant or shared across both?
- If shared → add to `DropdownMixin`
- If text-specific → add to `TextOnlyDropdownButton` or `TextDropdownConfig`
- If generic widget-specific → add to `BasicDropdownButton`
2. **Update documentation**: All changes must be reflected in relevant documentation files:
- `documentation/api_reference.md` - API changes
- `documentation/theming.md` - Styling changes
- `documentation/text_configuration.md` - Text config changes
- `documentation/migration.md` - Breaking changes
3. **Test in example app**: Always verify changes in `example/` before publishing
**IMPORTANT**: This package follows semantic versioning.
1. **Naming Changes**: When renaming public APIs or classes:
- Update ALL documentation files in `documentation/`
- Update `README.md`
- Update `CHANGELOG.md` with breaking change notice
- Bump major version in `pubspec.yaml`
2. **Historical Context**: Version 1.0.0 included these breaking changes:
- `CustomDropdown` → `BasicDropdownButton`
- `TextOnlyDropdown` → `TextOnlyDropdownButton`
When refactoring to reduce duplication:
1. Check if functionality exists in both `BasicDropdownButton` and `TextOnlyDropdownButton`
2. If yes, consider moving to `DropdownMixin`
3. Preserve all existing behavior - the mixin pattern eliminated ~150 lines of duplicate code without changing functionality
4. Run `flutter analyze` and `flutter test` after refactoring
The package has comprehensive documentation in `documentation/`:
When making ANY changes to public APIs, ensure corresponding documentation is updated.
- Example: `* **FEAT**: Added new animation option`
- Example: `* **FIX**: Corrected positioning on small screens`
- Example: `* **BREAKING**: Renamed CustomDropdown to BasicDropdownButton`
1. **Run analysis before committing**:
```bash
flutter analyze
dart format .
```
2. **Follow existing patterns**: Both dropdown variants should maintain consistent API design
3. **Preserve overlay behavior**: The overlay-based rendering is a key differentiator - don't regress to Flutter's built-in approach
4. **Maintain mixin benefits**: Keep shared logic in `DropdownMixin` to avoid duplication
1. Add property to `DropdownTheme` class in `src/dropdown_theme.dart`
2. Update both dropdown variants to use the new property
3. Document in `documentation/theming.md`
4. Add example usage in `example/lib/main.dart`
5. Update `CHANGELOG.md` with `* **FEAT**: ...`
6. Bump minor version in `pubspec.yaml`
1. Locate issue in `DropdownMixin.calculateDropdownPosition()`
2. Test fix across both dropdown variants
3. Verify in example app with various screen sizes
4. Update `CHANGELOG.md` with `* **FIX**: ...`
5. Bump patch version in `pubspec.yaml`
1. Modify `TextOnlyDropdownButton` or `TextDropdownConfig`
2. Update `documentation/text_configuration.md`
3. Add examples to `example/lib/main.dart`
4. Update `CHANGELOG.md`
5. Bump appropriate version in `pubspec.yaml`
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/flutter-dropdown-button/raw