Skip to main content

​
Examples

  • Basic Usage
  • With Icons
  • Searchable
  • With Descriptions
  • Error State
Basic dropdown field example

Simple dropdown field with a label.

NeoDropdownField(
  label: "Product Category",
  selectedId: "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

​
selectedId
String?
required
The ID of the currently selected item. Use null when no item is selected.
​
onChanged
ValueChanged<String?>
required
Callback function called when the selection changes. Receives the ID of the selected item, or null if selection is cleared.
​
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)

​
Integration Notes

  • ID Validation: The widget validates that all item IDs are unique and non-empty. Invalid IDs will trigger errors.
⌘I