FilterButton and ComboBox Convergence

This document provides a technical analysis of the feature convergence between FilterButton and ComboBox components. The epic's objective was to establish feature parity and create a unified architectural foundation while preserving each component's distinct use cases and interaction patterns.

Epic: FECORE-325

✨ What's New

The following capabilities have been newly added or significantly enhanced as part of the FECORE-325 epic:

FilterButtonV2 - Newly Added Features

• Empty State Customization - Full control over empty state presentation
• Tabs Support - Organize options in tabbed interfaces (newly added to FilterButtonV2)
• Infinite Loading - Progressive data loading for large datasets
• Render Item - Custom option rendering capabilities
• Creatable Options - Create new options on the fly
• Virtualization - Performance optimization for large lists
• Shift Selection - Select multiple items with Shift key
• Async Search - Server-side search integration
• Description in Options - Rich option descriptions
• Icons & App Icons - Visual option indicators

ComboBox - Newly Added Features

• Empty State Customization - Enhanced empty state management
• Loading More Data / Infinite Loading - Progressive data loading
• Render Item - Custom option rendering
• Virtual Infinite Loading - Performance optimization for large option lists
• Custom Sorting - Advanced sorting capabilities with sortPredicate, disableSort, and disableSelectedSort

Feature Comparison

tip

Quick Reference: Features marked with ✨ in the comparison table below indicate newly added capabilities.

Feature	FilterButton V1	FilterButton V2	ComboBox (Before)	ComboBox (After)
Apply/Reset Buttons	✅	✅	❌	❌
Async Loading	✅	✅	✅	✅
Async Search	❌	✅ ✨	✅	✅
Clearable	❌	❌	✅	✅
Creatable Options	❌	✅ ✨	✅	✅
Custom Filter	❌	❌	✅	✅
Custom List Component	✅	✅	❌	❌
Custom Sorting	✅	✅	❌	✅ ✨
Description in Options	❌	✅ ✨	✅	✅
Disabled Items/Options	✅	✅	✅	✅
Empty State Customization	❌	✅ ✨	❌	✅ ✨
Format Option Label	❌	❌	✅	✅
Group Labels	✅	✅	✅	✅
Icons & App Icons	❌	✅ ✨	✅	✅
Infinite Loading	❌	✅ ✨	❌	✅ ✨
Loading State	✅	✅	✅	✅
Mode Shifter	✅	✅	❌	❌
Multi-Creatable	❌	❌	✅	✅
Multiple Selection	✅	✅	✅	✅
onSelectionChange	✅	✅	❌	❌
Render Item	❌	✅ ✨	❌	✅ ✨
Search	✅	✅	✅	✅
Shift Selection	❌	✅ ✨	✅	✅
Tabs Support	❌	✅ ✨	✅	✅
Virtualization	❌	✅ ✨	✅	✅

Major Architectural Changes

1. CustomOption Component

The introduction of the CustomOption component represents a fundamental architectural shift toward component composition and code reuse. This shared component abstracts the common rendering logic for option items, serving as the rendering layer for both FilterButton and ComboBox.

Responsibilities:

• Rendering logic for checkbox, radio, and checkIcon selection types
• Icon and App Icon integration
• Description text rendering
• Platform icon display
• Disabled state management
• Custom styling support
• Keyboard navigation and accessibility (ARIA attributes)
• Sub-items rendering

Benefits:

• Single Source of Truth: Centralized option rendering logic ensures consistency
• Reduced Maintenance Burden: Bug fixes and enhancements propagate to both components
• Type Safety: Shared TypeScript interfaces ensure type consistency
• Performance: Optimized rendering logic benefits both components

2. FilterButton Migration to FilterButtonV2

note

Migration Recommendation: FilterButtonV2 is the recommended component for new implementations. It incorporates all merged features, improved performance, and better TypeScript support. The original FilterButton remains available for backward compatibility during migration periods.

FilterButtonV2 was introduced as the next-generation implementation of FilterButton, incorporating all merged features and establishing a more robust, extensible API. This migration provides:

• Enhanced API Design: More intuitive prop structure and better TypeScript support
• Improved Performance: Optimized rendering and state management
• Better Integration: Seamless integration with CustomOption and shared utilities
• Future-Proof Architecture: Designed to accommodate future feature additions

The original FilterButton remains available for backward compatibility, but new implementations should use FilterButtonV2.

Migration Guide

FilterButton to FilterButtonV2

Key Migration Steps:

1. Replace FilterButton import with FilterButtonV2
2. Convert group items from flat array with isGroupLabel to nested object structure
3. Update TypeScript types if using custom item types
4. Test selection behavior, especially with group items

Note: FilterButtonV2 uses normalized group structure (nested objects) instead of isGroupLabel flag, providing enhanced API design, improved performance, and better integration with CustomOption component.

Upcoming Features

The following features are planned or currently in progress as part of the FECORE-325 epic. These enhancements will be delivered in future releases:

info

Status: Check the FECORE-325 epic and its child tickets for the latest implementation status and timelines.

Planned Enhancements

• Readonly Items: Support for readonly options that cannot be deselected in FilterButtonV2

Summary

The FECORE-325 epic successfully established feature parity between FilterButton and ComboBox through architectural consolidation. The introduction of the CustomOption component as a shared rendering foundation eliminated code duplication while ensuring consistent behavior. FilterButtonV2, incorporating all merged features and optimized performance, is the recommended component for new implementations.