Aquila.MultiSelectComboBox 1.0.1

Absolutely! Here’s a complete user guide / README for your Aquila.MultiSelectComboBox library, written as an open-source friendly, production-ready README.md that you can include in your NuGet project.

Aquila.MultiSelectComboBox

Multi-select ComboBox / Dropdown control for .NET MAUI (net9 / net10) Author: Aquila Innovations License: MIT

A fully customizable MultiSelect ComboBox for .NET MAUI, supporting images, search, select all / clear buttons, and full color theming. Works on Android, iOS, macOS Catalyst, Windows.

Features

• Multi-select dropdown with ObservableCollection binding

• Supports customizable placeholder, summary format

• Customizable colors for:

  • ComboBox box
  • Dropdown popup background
  • Buttons (OK / Select All / Clear)
  • CheckBox

• Searchable popup

• Select All / Clear buttons

• Two-way binding for SelectedItems

• Exposes SelectedIds and SelectedValues (read-only)

• Works with any IEnumerable<object>

• Minimal dependencies (only CommunityToolkit.Maui)

Installation

1. Add NuGet package:

dotnet add package Aquila.MultiSelectComboBox

2. Make sure your MAUI project has CommunityToolkit.Maui 14.x installed for net10:

<PackageReference Include="CommunityToolkit.Maui" Version="14.0.0" />

3. In MauiProgram.cs, add:

using CommunityToolkit.Maui;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();

        builder
            .UseMauiApp<App>()
            .UseMauiCommunityToolkit();

        return builder.Build();
    }
}

Usage

XAML Example

<ContentPage
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:controls="clr-namespace:Aquila.MultiSelectComboBox.Controls;assembly=Aquila.MultiSelectComboBox"
    x:Class="AquilaTestMultiselectCombo.MainPage">

    <VerticalStackLayout Padding="20" Spacing="20">

        <controls:MultiSelectComboBoxControl
            x:Name="TestComboBox"
            ItemsSource="{Binding Fruits}"
            SelectedItems="{Binding SelectedFruits, Mode=TwoWay}"
            Placeholder="Select fruits..."
            SummaryFormat="{0} fruits selected"
            BoxBackgroundColor="AliceBlue"
            BoxTextColor="DarkBlue"
            PopupBackgroundColor="Beige"
            ButtonBackgroundColor="LightGreen"
            ButtonTextColor="DarkGreen"
            CheckBoxColor="Red"
            HeightRequest="60"
            />

        <Label Text="Selected Fruits:" FontAttributes="Bold" />
        <CollectionView ItemsSource="{Binding SelectedFruits}">
            <CollectionView.ItemTemplate>
                <DataTemplate>
                    <Label Text="{Binding}" />
                </DataTemplate>
            </CollectionView.ItemTemplate>
        </CollectionView>

    </VerticalStackLayout>
</ContentPage>

ViewModel Example

using System.Collections.ObjectModel;

public class MainPageViewModel
{
    public ObservableCollection<string> Fruits { get; set; } = new ObservableCollection<string>
    {
        "Apple", "Banana", "Orange", "Mango", "Grapes", "Pineapple", "Strawberry"
    };

    public ObservableCollection<object> SelectedFruits { get; set; } = new ObservableCollection<object>();
}

Bindable Properties

Methods

• UpdateSummary() → refreshes the summary label based on current selection
• OpenPopup() → opens the dropdown popup (internal, triggered on tap)

Customization

• Use BoxBackgroundColor and BoxTextColor for the main combo box look.
• Use PopupBackgroundColor for the dropdown panel background.
• Use ButtonBackgroundColor and ButtonTextColor for buttons.
• Use CheckBoxColor for checkboxes.
• All properties are bindable, so you can dynamically change colors at runtime.

Notes

• MAUI does not support RelativeSource bindings like WPF. Bind to the control via x:Reference or set colors in code-behind.
• Popup requires CommunityToolkit.Maui for ShowPopup().
• Works on Android, iOS, Mac Catalyst, Windows 10+.

Example Screenshot

(Optional: Add screenshot of MultiSelectComboBox in use)

License

MIT License — free to use, modify, and redistribute.

I can also generate a full markdown with embedded “How to add images, hexagon clipping, and display images in the ComboBox” so your library matches your original spec with photos.

Do you want me to add that advanced version next?