Aquila.MultiSelectComboBox 1.0.3

# Aquila MultiSelectComboBox

**Modern multi-select combo box / dropdown for .NET MAUI**  
with profile pictures, search, full-row selection, and support for large lists (5,000+ items).

![Demo](docs/images/demo.gif)  
*(add your real screenshot or animated GIF here)*

## Features

- Circular avatars / profile images
- Real-time search & filtering
- Tap anywhere on row to select/deselect
- Select All / Clear / OK buttons
- Customizable colors & appearance
- Optimized performance for thousands of items
- Two-way binding (`ObservableCollection`)
- Uses CommunityToolkit.Maui Popup

## Installation

1. Add the project reference to your MAUI app
2. Add namespace in XAML:

```xml
xmlns:controls="clr-namespace:Aquila.MultiSelectComboBox.Controls;assembly=Aquila.MultiSelectComboBox"

Quick Example

<controls:MultiSelectComboBoxControl
    ItemsSource="{Binding Employees}"
    SelectedItems="{Binding SelectedEmployees, Mode=TwoWay}"
    DisplayMemberPath="FullName"
    ImageMemberPath="PhotoUrl"
    Placeholder="Select team members…"
    SummaryFormat="{}{0} selected"
    HeightRequest="56"
    HorizontalOptions="FillAndExpand"

/* Recommended professional colors */
    BoxBackgroundColor="#FFFFFF"
    BoxTextColor="#1F2937"
    PopupBackgroundColor="#F9FAFB"
    ButtonBackgroundColor="#3B82F6"
    ButtonTextColor="#FFFFFF"
    CheckBoxColor="#3B82F6" />

See User Guide → for full documentation, properties, themes, troubleshooting and large-list tips.

Screenshots

(add 2–4 screenshots here – popup open, selected items, search active, dark mode if supported)

License

MIT

Made with ❤️ in Coimbatore

### USER_GUIDE.md (detailed user documentation)

```markdown
# Aquila MultiSelectComboBox – User Guide

**Version:** 1.0 (February 2026)  
**Target:** .NET MAUI apps (Android, iOS, Windows, macOS)

## Table of Contents

1. [Overview](#overview)
2. [Installation](#installation)
3. [Basic Usage](#basic-usage)
4. [All Properties](#all-properties)
5. [Recommended Color Themes](#recommended-color-themes)
6. [Working with Images](#working-with-images)
7. [Large Lists (5,000+ items)](#large-lists-optimization)
8. [UX Features](#ux-features)
9. [Troubleshooting](#troubleshooting)
10. [Sample Models & ViewModels](#sample-code)

## Overview

A customizable, high-performance multi-select control that looks and behaves like a modern combo box with:

- Summary text when collapsed
- Popup with search, select-all, clear, and OK
- Support for images (URLs, local files, MAUI resources)
- Full row tap to toggle selection
- Good accessibility & touch targets

## Installation

### Step 1 – Add project reference

In your MAUI app → right-click Dependencies → Add Project Reference → select `Aquila.MultiSelectComboBox`

### Step 2 – Add XAML namespace

```xml
xmlns:controls="clr-namespace:Aquila.MultiSelectComboBox.Controls;assembly=Aquila.MultiSelectComboBox"

Step 3 – (Recommended) Add converters to App.xaml

<Application.Resources>
    <conv:StringToImageSourceConverter x:Key="StringToImageSourceConverter" />
    <conv:IsNotNullConverter x:Key="IsNotNullConverter" />
</Application.Resources>

Basic Usage

<controls:MultiSelectComboBoxControl
    x:Name="MemberSelector"
    ItemsSource="{Binding TeamMembers}"
    SelectedItems="{Binding SelectedMembers, Mode=TwoWay}"
    DisplayMemberPath="Name"
    ImageMemberPath="AvatarUrl"
    Placeholder="Select members…"
    SummaryFormat="{}{0} member(s) selected"
    HeightRequest="54"
    HorizontalOptions="FillAndExpand" />

// ViewModel example
[ObservableProperty]
ObservableCollection<Member> teamMembers = new() { ... };

[ObservableProperty]
ObservableCollection<object> selectedMembers = new();

All Properties

Recommended Color Themes (2025–2026 professional look)

1. Modern Corporate Blue (most recommended)

BoxBackgroundColor="#FFFFFF"
BoxTextColor="#1F2937"
PopupBackgroundColor="#F9FAFB"
ButtonBackgroundColor="#3B82F6"
ButtonTextColor="#FFFFFF"
CheckBoxColor="#3B82F6"

2. Clean Neutral Gray

BoxBackgroundColor="#FFFFFF"
BoxTextColor="#111827"
PopupBackgroundColor="#F3F4F6"
ButtonBackgroundColor="#4B5563"
ButtonTextColor="#FFFFFF"
CheckBoxColor="#6366F1"

3. Slate + Teal (modern SaaS)

BoxBackgroundColor="#FFFFFF"
BoxTextColor="#0F172A"
PopupBackgroundColor="#F8FAFC"
ButtonBackgroundColor="#0EA5E9"
ButtonTextColor="#FFFFFF"
CheckBoxColor="#0EA5E9"

Working with Images

• Supply full URLs (https://...) or MAUI resource names (avatar1.png)
• Uses StringToImageSourceConverter → handles both
• Circular clipping is built-in (48×48 dp recommended)

Tip: Provide fallback image in your model:

public string AvatarUrl => string.IsNullOrEmpty(_avatar) ? "default_user.png" : _avatar;

Large Lists (5,000+ items) – Optimization Notes

• Popup opens immediately (loading is async)
• Full list is cached once → search is fast
• Avoid unnecessary bindings inside DataTemplate
• If still slow → consider debouncing search (can be added later)

UX Features

• Tap row (photo + name + checkbox area) → toggles selection
• Checkbox is disabled (IsEnabled=false) to prevent double events
• Search filters in real-time
• Select All / Clear apply to all items (not just visible)
• Dismiss popup by tapping outside

Troubleshooting

Sample Models

public class Member
{
    public string Name { get; set; } = "";
    public string? AvatarUrl { get; set; }
}