Smart Chip Field #

A production-ready Flutter package that provides a Gmail-style chip input field. Perfect for email recipients, tags, and multi-select inputs with proper backspace handling.

✨ Features #

• Gmail-Style Backspace Behavior: First press highlights, second press deletes
• Smart Chip Creation: Auto-converts text to chips on Space, Enter, Comma, or Semicolon
• Custom Validation: Built-in email validator with extensible validation system
• Full Customization: Custom chip builders, separators, and styling
• Keyboard Support: Proper handling of physical keyboard events
• No WidgetSpan Issues: Uses a dual-layer architecture that avoids Flutter's text selection limitations

🎯 The Problem This Solves #

Existing chip input packages (like chip_inputs_textfield) struggle with backspace behavior because they use WidgetSpan, which Flutter's text selection system treats as a single character. This causes chips to convert back to text instead of being deleted.

Smart Chip Field solves this by using a dual-layer architecture where chips are real widgets alongside the text field, not embedded within it.

📦 Installation #

Add this to your pubspec.yaml:

dependencies:
  smart_chip_field: ^1.0.0

Then run:

flutter pub get

🚀 Quick Start #

import 'package:smart_chip_field/smart_chip_field.dart';

SmartChipField(
  hintText: 'Add recipients',
  validator: ChipValidators.email,
  separators: const [',', ' ', ';'],
  onChanged: (chips) {
    print('Current chips: $chips');
  },
)

📖 Usage Examples #

Basic Email Input #

SmartChipField(
  hintText: 'To: Add recipients',
  validator: ChipValidators.email,
  onChanged: (emails) {
    setState(() {
      _recipients = emails;
    });
  },
)

Custom Validator #

SmartChipField(
  hintText: 'Add tags',
  validator: (value) {
    if (value.length < 3) return 'Tag must be at least 3 characters';
    if (value.contains(' ')) return 'Tags cannot contain spaces';
    return null; // Valid
  },
)

Custom Chip Design #

SmartChipField(
  chipBuilder: (text, onDelete) {
    return Container(
      padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 6),
      decoration: BoxDecoration(
        color: Colors.purple.shade100,
        borderRadius: BorderRadius.circular(20),
      ),
      child: Row(
        mainAxisSize: MainAxisSize.min,
        children: [
          Icon(Icons.tag, size: 16),
          const SizedBox(width: 4),
          Text(text),
          const SizedBox(width: 4),
          GestureDetector(
            onTap: onDelete,
            child: Icon(Icons.close, size: 16),
          ),
        ],
      ),
    );
  },
)

Pre-filled Chips #

SmartChipField(
  initialChips: const [
    'john@example.com',
    'jane@example.com',
  ],
  validator: ChipValidators.email,
)

🎨 Customization Options #

🧪 Built-in Validators #

Email Validator #

SmartChipField(
  validator: ChipValidators.email,
)

No Spaces Validator #

SmartChipField(
  validator: ChipValidators.noSpaces,
)

Combine Multiple Validators #

String? multiValidator(String value) {
  final emailError = ChipValidators.email(value);
  if (emailError != null) return emailError;

  if (value.contains('test')) {
    return 'Test emails not allowed';
  }

  return null;
}

⌨️ Keyboard Behavior #

• Space / Enter / Comma: Creates a chip from current text
• Backspace (first press): Highlights the last chip
• Backspace (second press): Deletes the highlighted chip
• Click chip: Deletes the chip immediately
• Type while chip highlighted: Unhighlights and continues typing

🏗️ Architecture #

Unlike traditional approaches that embed chips in text using WidgetSpan, Smart Chip Field uses:

1. Chip Layer: Real widgets in a Wrap layout
2. Input Layer: Standard TextField for text entry
3. Event Interceptor: Focus.onKeyEvent to handle backspace before TextField processes it

This architecture completely avoids Flutter's text selection limitations with WidgetSpan.

🐛 Common Issues #

Issue: Chips not creating on space #

Solution: Make sure separators includes ' ' (space character)

Issue: Validation not working #

Solution: Your validator must return null for valid input, and a String error message for invalid input

Issue: Custom chip builder not showing #

Solution: Ensure your chipBuilder returns a complete widget and calls the onDelete callback

📄 License #

MIT License - see LICENSE file for details

🤝 Contributing #

Contributions are welcome! Please open an issue or submit a pull request.

📧 Support #

If you find this package helpful, please give it a ⭐ on GitHub and a 👍 on pub.dev!

For bugs or feature requests, please open an issue.