Skip to main content

​
Examples

Basic dropdown field example

Simple dropdown field with a label.

NeoDropdownField(
  label: "Product Category",
  selected: "clothing",
  sections: [
    NeoDropdownFieldSection(
      children: [
        NeoDropdownFieldItem(
          id: "electronics",
          label: "Electronics",
        ),
        NeoDropdownFieldItem(
          id: "clothing",
          label: "Clothing", 
        ),
        NeoDropdownFieldItem(
          id: "books",
          label: "Books",
        ),
      ],
    ),
  ],
  onChanged: (value) {
    // Handle selection change
  },
),

​
Properties

​
Required

​
selected
T
required
The currently selected value(s). For single-select, use String? (e.g., selected: "item-id" or selected: null). For multi-select, use Set<String> (e.g., selected: {"item1", "item2"}). The generic type T determines the selection mode.
​
onChanged
ValueChanged<T>
required
Callback function called when the selection changes. Receives the selected value(s) matching the generic type T. For single-select, receives String?. For multi-select, receives Set<String>.
​
sections
List<NeoDropdownFieldSection>
required
A list of sections containing the dropdown options. Each section groups related items together.

​
Content

​
label
String
The label text displayed above the dropdown field.
​
placeholder
String
default:"Select an option"
The placeholder text shown when no item is selected.

​
Layout

​
fixedHeight
bool
default:"true"
Whether the dropdown should have a fixed height or expand to fit content. When true, provides a scrollable area for long lists.
​
isSearchable
bool
default:"false"
Whether to enable search functionality within the dropdown. When true, adds a sticky search field at the top of the dropdown.
​
searchPlaceholder
String
default:"Search..."
The placeholder text for the search field. Only relevant when isSearchable is true.
​
autofocusSearchOnOpen
bool
default:"true"
When isSearchable is true, automatically focuses the search field when opening the dropdown.

​
State

​
allowDeselect
bool
default:"false"
Whether users can deselect the currently selected item by clicking it again. When true, clicking the selected item calls onChanged with null.
​
isEnabled
bool
default:"true"
Controls whether the dropdown is interactive. When false, the field dims, ignores input and focus, and shows a forbidden cursor.

​
Validation

​
errorText
String
Error message to display below the dropdown field. When provided, the field shows an error state with red styling.

​
Section Properties

The NeoDropdownFieldSection class represents grouped sections within the dropdown:

​
Required

​
children
List<NeoDropdownFieldItem>
required
A list of items within this section.

​
Content

​
label
String
The section header text. If not provided, the section will not display a header.

​
Item Properties

The NeoDropdownFieldItem class represents individual selectable options:

​
Required

​
id
String
required
A unique identifier for the item. This value is passed to the onChanged callback when selected. Must be unique across all items.
​
label
String
required
The display text for the item.

​
Content

​
description
String
Additional descriptive text displayed below the label for extra context.
​
icon
PhosphorIconData Function(PhosphorIconsStyle)
An optional icon to display before the label.
​
isDescriptionInline
bool
default:"false"
Whether to display the description inline with the label instead of below it.

​
Best Practices

  • Width Constraints: Always provide width constraints to prevent layout issues by wrapping in ConstrainedBox, SizedBox, Expanded, etc.
  • Unique IDs: Ensure all item IDs are unique across all sections to prevent errors
  • Error Handling: Use errorText to provide clear validation feedback when e.g. the field is required
  • Deselection: Enable allowDeselect for optional fields where “no selection” is a valid state. (E.g. filter fields)
  • Multi-Select: Use NeoDropdownField<Set<String>> for multi-select scenarios. The dropdown stays open after selection, allowing multiple items to be selected.

​
Integration Notes

  • Generic Type: The widget is generic and supports two modes:
    • Single-select: NeoDropdownField<String?> or NeoDropdownField<String> (use nullable for optional fields)
    • Multi-select: NeoDropdownField<Set<String>> (automatically enables multi-select behavior)
  • ID Validation: The widget validates that all item IDs are unique and non-empty. Invalid IDs will trigger errors.
Last modified on November 21, 2025