autocomplete_tag_editor 1.0.7

SDKflutter
Platformandroidioswindowslinuxmacosweb

A Flutter widget for tag input with autocomplete functionality

AutoCompleteTagEditor

Pub Version License: MIT

A versatile Flutter tag input widget with autocomplete suggestions, custom tag creation capabilities, and smooth animations.

Example

Features

  • 🏷️ Generic Type Support - Works with String or any custom object type
  • 🔍 Smart Autocomplete - Filter suggestions as you type
  • ✨ Custom Tag Creation - Allow new tags not in suggestions
  • 📱 Responsive Layout - Automatic line wrapping for tags
  • 🎨 Customizable UI - Match your app's theme
  • 🧩 Overlay Suggestions - Position-aware dropdown list
  • ✅ Validation Support - Built-in input validation
  • ⚡ Performance - Efficient filtering and rendering

Installation

Add to your pubspec.yaml:

dependencies:
  autocomplete_tag_editor: ^1.0.6

Basic Usage

String Tags with Customization

AutoCompleteTagEditor<String>(
  suggestions: ['Flutter', 'Dart', 'Firebase'],
  value: const ['Flutter'],
  displayValueBuilder: (option) => option,
  allowCustomTags: true,
  onTagsChanged: (tags) => print('Selected tags: $tags'),
  inputDecoration: InputDecoration(
    labelText: 'Add Tags',
    border: OutlineInputBorder(),
  ),
)

Custom Type Tags

class TagData {
  final String id;
  final String name;

  TagData(this.id, this.name);
}

AutoCompleteTagEditor<TagData>(
  suggestions: [
    TagData('1', 'Mobile'),
    TagData('2', 'Web'),
  ],
  value: const [],
  displayValueBuilder: (option) => option.name,
  allowCustomTags: true,
  onCreateCustomTag: (input) => TagData(Uuid().v4(), input),
)

Advance Usage

Custom Tag Design

AutoCompleteTagEditor<String>(
  tagBuilder: (context, tag, onDeleted) => Container(
    padding: const EdgeInsets.symmetric(horizontal: 8, vertical: 4),
    decoration: BoxDecoration(
      color: Colors.blue[100],
      borderRadius: BorderRadius.circular(16),
    ),
    child: Row(
      mainAxisSize: MainAxisSize.min,
      children: [
        Text(tag),
        IconButton(
          icon: const Icon(Icons.close, size: 16),
          onPressed: onDeleted,
        ),
      ],
    ),
  ),
)

Custom Suggestion Design

AutoCompleteTagEditor<String>(
  suggestionItemBuilder: (context, suggestion, onSelected) => Card(
    child: ListTile(
      leading: const Icon(Icons.tag),
      title: Text(suggestion),
      trailing: const Icon(Icons.add_circle),
      onTap: onSelected,
    ),
  ),
)

Custom Filter Logic

AutoCompleteTagEditor<String>(
  suggestionFilter: (suggestion, query) {
    // Implement custom filtering logic
    return suggestion.toLowerCase().startsWith(query.toLowerCase());
  },
)

Parameters

ParameterTypeRequiredDescription
suggestionsListNoAvailable options for autocomplete
valueListNoInitially selected tags
displayValueBuilderDisplayValueBuilderYes*Converts T instance to display string
inputDecorationInputDecorationNoDecoration for the input field
textStyleTextStyleNoCustom text style for the input field
allowCustomTagsboolNoEnable creation of tags not in suggestions (default: false)
onCreateCustomTagCreateCustomTagNoRequired when using non-String types with allowCustomTags=true
onTagsChangedValueChanged<List>NoCallback when tags change
tagBuilderTagBuilderNoCustom widget builder for tags
suggestionItemBuilderSuggestionItemBuilderNoCustom widget builder for suggestion items
suggestionFilterSuggestionFilterNoCustom filtering logic for suggestions
maxSuggestionCountintNoMaximum number of suggestions to show (default: 5)
minimumSpaceRequiredBelowintNoMinimum space needed below input to show suggestions (default: 300)
onFocusChangeValueChangedNoCallback when input field focus changes

What's New in 1.0.6

  • 🎯 Enhanced Focus Management

    • Smart focus handling with better tap interactions
    • New onFocusChange callback to track input field focus state
    • Improved focus restoration after tag operations
  • ⚡ Performance Improvements

    • Cached suggestion filtering for better performance
    • Smart overlay rebuilds to minimize unnecessary updates
    • Efficient tag state management
  • 🎨 UI/UX Enhancements

    • Smoother animations for overlay transitions
    • Better keyboard interaction handling
    • Improved cursor visibility and styling
    • Dynamic overlay positioning considering keyboard visibility
    • More responsive tag operations (add/remove)
  • 💪 Stability Improvements

    • Better state cleanup on widget disposal
    • More reliable focus and overlay management
    • Improved handling of widget updates

Important Notes

⚠️ Type Safety Requirements

  • When using custom types (T != String) with allowCustomTags: true, you must provide onCreateCustomTag
  • displayValueBuilder must be provided for custom Types

🎯 Tag Creation Behavior

  • Tags can be created by typing and pressing the comma key (,)
  • Tags are also created when the input field loses focus (if allowCustomTags is true)
  • Duplicate tags are prevented automatically

💡 UI Considerations

  • The widget uses Flutter's overlay system for suggestions
  • Suggestions list automatically positions above the input if there isn't enough space below (controlled by minimumSpaceRequiredBelow)
  • Input field automatically expands with content
  • Maximum suggestions shown can be limited using maxSuggestionCount

🔧 State Management

  • Parent widgets should manage the selected tags state if needed
  • Use onTagsChanged to track tag additions/removals

Example App

See the /example directory for a complete implementation. The example demonstrates:

  • String tag implementation
  • Custom object type tags
  • Custom styling
  • Validation scenarios
  • Error handling

Contributing

Contributions are welcome! Please follow these steps:

  • Fork the repository
  • Create your feature branch
  • Commit your changes
  • Push to the branch
  • Create a new Pull Request