SearchableTextFieldAppi

A powerful text field widget with built-in dropdown search, filtering capabilities, and extensive customization options.

Overview

SearchableTextFieldAppi combines a text input field with a searchable dropdown menu, providing users with an intuitive way to select from a list of options. It supports both web and mobile platforms with adaptive UI patterns - dropdown menus on web and bottom sheets on mobile.

Features

• 🔍 Real-time Search - Filter items as you type
• 📱 Platform Adaptive - Dropdown on web, bottom sheet on mobile
• 🎨 Rich Customization - Colors, images, gradients support
• ✅ Form Integration - Built-in validation and form field support
• 🖼️ Visual Elements - Support for SVG images and color indicators
• 🎯 Flexible Selection - Clear selection, initial values, read-only mode
• ♿ Accessibility - Focus management and screen reader support

Basic Usage

SearchableTextFieldAppi(
  context: context,
  list: ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry'],
  onChanged: (selectedValue) {
    print('Selected: $selectedValue');
  },
  textFieldStyle: TextFieldParamsAppi(
    hint: 'Search fruits...',
    lable: 'Select Fruit',
    mandatory: true,
  ),
)

Properties

Property	Type	Default	Description
context	BuildContext	required	Build context for the widget
list	List<String>	required	List of items to search and select from
onChanged	Function(String?)	required	Callback when selection changes
textFieldStyle	TextFieldParamsAppi	required	Text field styling and behavior parameters
dropdownColor	Color?	null	Background color of dropdown/bottom sheet
dropdownTextColor	Color?	null	Text color in dropdown items
dropdownTextStyle	Style?	null	Text styling for dropdown items
focussedSuffixicon	Widget?	null	Custom suffix icon when focused
onlyDropDown	bool?	null	Force dropdown mode (web-style) on all platforms
bottomSheetHeight	double?	null	Custom height for bottom sheet
radius	double?	null	Border radius for dropdown/bottom sheet
dropdownHeight	double?	null	Maximum height of dropdown menu
offset	Offset?	null	Position offset for dropdown
bottomsheetTitle	String?	null	Title for bottom sheet
imageList	List<String>?	null	SVG image URLs for each list item
colorList	List<String>?	null	Color hex codes for each list item
textSize	double?	null	Font size for dropdown text

Examples

Basic Searchable Field

SearchableTextFieldAppi(
  context: context,
  list: ['Option 1', 'Option 2', 'Option 3'],
  onChanged: (value) {
    setState(() {
      selectedValue = value;
    });
  },
  textFieldStyle: TextFieldParamsAppi(
    hint: 'Search options...',
    lable: 'Select Option',
  ),
)

With Images and Colors

SearchableTextFieldAppi(
  context: context,
  list: ['Red', 'Green', 'Blue'],
  imageList: [
    'https://example.com/red-icon.svg',
    'https://example.com/green-icon.svg',
    'https://example.com/blue-icon.svg',
  ],
  colorList: ['FF0000', '00FF00', '0000FF'],
  onChanged: (value) {
    print('Selected color: $value');
  },
  textFieldStyle: TextFieldParamsAppi(
    hint: 'Choose a color...',
    lable: 'Color Selection',
    mandatory: true,
  ),
)

With Validation

SearchableTextFieldAppi(
  context: context,
  list: countries,
  onChanged: (value) {
    selectedCountry = value;
  },
  textFieldStyle: TextFieldParamsAppi(
    hint: 'Search countries...',
    lable: 'Country',
    mandatory: true,
    validator: (value) {
      if (value == null || value.isEmpty) {
        return 'Please select a country';
      }
      return null;
    },
    widgetKey: GlobalKey<FormFieldState<String>>(),
  ),
)

Custom Styling

SearchableTextFieldAppi(
  context: context,
  list: items,
  dropdownColor: Colors.grey[100],
  dropdownTextColor: Colors.black87,
  onChanged: (value) {
    handleSelection(value);
  },
  textFieldStyle: TextFieldParamsAppi(
    hint: 'Type to search...',
    lable: 'Custom Styled Field',
    headingTextStyle: Style(
      $text.style.fontSize(16),
      $text.style.fontWeight(FontWeight.w600),
      $text.style.color(Colors.blue),
    ),
    border: OutlineInputBorder(
      borderRadius: BorderRadius.circular(12),
      borderSide: BorderSide(color: Colors.blue),
    ),
  ),
)

Read-Only Mode

SearchableTextFieldAppi(
  context: context,
  list: options,
  onChanged: (value) {
    // Handle selection
  },
  textFieldStyle: TextFieldParamsAppi(
    hint: 'Select option...',
    lable: 'Read-Only Field',
    readOnly: true,
    initialValue: 'Pre-selected Option',
  ),
)

Advanced Features

Platform-Specific Behavior

The widget automatically adapts to the platform:

• Web: Shows dropdown menu
• Mobile: Shows bottom sheet for better touch interaction

You can force dropdown mode on all platforms:

SearchableTextFieldAppi(
  // ... other properties
  onlyDropDown: true, // Forces dropdown on mobile too
)

Image and Color Support

Display visual indicators alongside text options:

SearchableTextFieldAppi(
  context: context,
  list: ['Gradient Option', 'Solid Option'],
  colorList: [
    'FF0000,0000FF', // Gradient: red to blue
    '00FF00',        // Solid green
  ],
  // ... other properties
)

Form Integration

Integrate with Flutter forms for validation:

Form(
  key: formKey,
  child: Column(
    children: [
      SearchableTextFieldAppi(
        context: context,
        list: options,
        onChanged: (value) {
          formData['selection'] = value;
        },
        textFieldStyle: TextFieldParamsAppi(
          widgetKey: GlobalKey<FormFieldState<String>>(),
          validator: (value) {
            if (value == null || value.isEmpty) {
              return 'This field is required';
            }
            return null;
          },
        ),
      ),
      ElevatedButton(
        onPressed: () {
          if (formKey.currentState!.validate()) {
            // Process form
          }
        },
        child: Text('Submit'),
      ),
    ],
  ),
)

TextFieldParamsAppi Integration

The widget uses TextFieldParamsAppi for comprehensive text field configuration:

textFieldStyle: TextFieldParamsAppi(
  hint: 'Search hint text',
  lable: 'Field Label',
  mandatory: true,
  heading: 'Section Heading',
  headingAlignment: MainAxisAlignment.start,
  headingPaddingDown: 8.0,
  initialValue: 'Default Value',
  validator: customValidator,
  widgetKey: fieldKey,
  preffixxicon: Icon(Icons.search),
  suffixIcon: Icon(Icons.arrow_drop_down),
  readOnly: false,
  border: customBorder,
  focussedBorder: customFocusedBorder,
  errorBorder: customErrorBorder,
)

Best Practices

1. Performance: For large lists (>100 items), consider implementing pagination or server-side filtering
2. Accessibility: Always provide meaningful labels and hints
3. Validation: Use built-in validation for required fields
4. Images: Optimize SVG images for better performance
5. Colors: Use consistent color schemes across your app

Related Widgets

• TextFieldAppi - For basic text input
• DropDownMenuAppi - For simple dropdown selection
• DropDownCustomMenuFieldAppi - For advanced dropdown features

Migration Notes

When upgrading from basic text fields:

1. Wrap your existing validation logic in TextFieldParamsAppi
2. Replace onChanged callbacks to handle string values
3. Update styling properties to use the new parameter structure

Ready for advanced search functionality? Check out DropDownCustomMenuFieldAppi for even more customization options!