App Dropdown Picker

A feature-rich Flutter dropdown picker with local search, remote API support, pagination, and customizable UI.

---

Features

• ✅ Local items — Simple static list mode.
• ✅ Remote API — Load items dynamically from an API endpoint.
• ✅ Search — Client-side filtering (local) or debounced API search (remote).
• ✅ Pagination — Infinite scroll for large remote datasets.
• ✅ Smart overlay — Opens upward when space is limited below.
• ✅ Scroll-to-selected — Automatically scrolls to the selected item.
• ✅ 17 color parameters — All customizable, defaults from colorScheme.
• ✅ Generic <T> — Works with any data model.

Installation

dependencies:
  app_dropdown_picker: ^0.1.0

Then run:

flutter pub get

Quick Start

Basic (local items)

import 'package:app_dropdown_picker/app_dropdown_picker.dart';

AppDropdownPicker<String>(
  title: 'Pilih Kota',
  fieldHint: 'Pilih kota',
  items: [
    AppPickerItem(value: '1', label: 'Jakarta'),
    AppPickerItem(value: '2', label: 'Bandung'),
    AppPickerItem(value: '3', label: 'Surabaya'),
  ],
  selectedValue: selectedCity,
  onItemSelected: (item) {
    setState(() => selectedCity = item?.value);
  },
)

With Remote API

AppDropdownPicker<MyModel>(
  title: 'Pilih User',
  fieldHint: 'Cari user...',
  enableSearch: true,
  searchHint: 'Cari nama...',
  dataUrl: '/api/users',
  baseUrl: 'https://example.com', // required if dataUrl is relative
  httpClient: myDioInstance,      // optional, defaults to Dio()
  itemFromJson: MyModel.fromJson,
  itemValue: (m) => m.id.toString(),
  itemLabel: (m) => m.name,
  onItemSelected: (item) {
    // item?.data is MyModel
  },
)

With Pagination

AppDropdownPicker<MyModel>(
  ...
  enableRemotePagination: true,
  remotePageSize: 10,
  dataSelector: (data) => data['items'] as List,
)

Customization

AppDropdownPicker<String>(
  ...
  // Labels
  clearLabel: 'Hapus',
  retryLabel: 'Muat ulang',
  noDataLabel: 'Data kosong',
  allLoadedLabel: 'Semua data termuat',
  // Colors
  primaryColor: Colors.blue,
  backgroundColor: Colors.white,
  borderColor: Colors.grey.shade300,
  errorColor: Colors.red,
)

Example

A complete working example is available in the example/ directory.

cd example/
flutter run

API Reference

AppDropdownPicker Parameters

Parameter	Type	Default	Description
title	String	required	Dropdown title
items	List<AppPickerItem<T>>	[]	Local items list
selectedValue	String?	null	Currently selected value
onItemSelected	ValueChanged<AppPickerItem<T>?>	required	Selection callback
onClear	VoidCallback?	null	Additional clear callback
onDataSelected	ValueChanged<T?>?	null	Typed data callback
clearLabel	String	'Clear'	Clear button text
fieldHint	String	'Pilih opsi'	Placeholder text
showCheckmark	bool	true	Show checkmark icon
enableSearch	bool	false	Show search field
searchHint	String	'Cari...'	Search field hint
maxHeight	double	300	Overlay max height
textAlign	TextAlign	start	Label text alignment
dataUrl	String?	null	Remote API endpoint
dataSelector	Function?	null	API response data extractor
itemFromJson	Function?	null	JSON → typed model factory
itemValue	Function?	null	Typed model → value string
itemLabel	Function?	null	Typed model → label string
queryParameters	Map?	null	Static query parameters
queryParametersBuilder	Function?	null	Dynamic query parameters
searchQueryParamName	String	'search'	Search query param name
searchDebounce	Duration	500ms	Search debounce duration
enableRemotePagination	bool	false	Enable pagination
remotePageParamName	String	'page'	Page param name
remotePageSizeParamName	String	'size'	Page size param name
remotePageSize	int	5	Items per page
minRemoteSearchLength	int	2	Min chars before search
httpClient	dio.Dio?	null	Custom HTTP client
baseUrl	String?	null	Base URL for relative URLs
retryLabel	String	'Coba lagi'	Retry button text
noDataLabel	String	'Tidak ada data'	Empty state text
allLoadedLabel	String	'Semua data sudah dimuat'	Pagination end text

Color Parameters

All color parameters default to Theme.of(context).colorScheme values, so the dropdown adapts to your app's theme automatically.

Parameter	Default from colorScheme	Description
backgroundColor	Colors.white	Dropdown panel background
borderColor	outline	Inactive border
activeBorderColor	primary	Active/focused border
labelColor	onSurface	Text color
hintColor	onSurfaceVariant	Placeholder/hint text
selectedColor	primary	Selected item text
selectedBgColor	primaryContainer	Selected item background
checkColor	primary	Checkmark icon
headerColor	primary	Header title
clearButtonColor	onSurfaceVariant	Clear button
errorColor	error	Error message
disabledColor	outlineVariant	Disabled item background
searchBgColor	surfaceContainerHighest	Search field background
searchIconColor	onSurfaceVariant	Search icon
primaryColor	primary	Arrow icon / refresh
shadowColor	Colors.black(15%)	Overlay shadow
dividerColor	Theme.dividerColor	Section dividers

Requirements

• Dart SDK: >=3.0.0 <4.0.0
• Flutter: >=3.10.0
• Dio: ^5.0.0

License

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