Table of content

• Introduction
• The user interface
• Common Properties
• Styles
  • MultiSelectionComboBox-Styles
  • ItemContainer-Styles
  • SelectedItemContainer-Styles
• Selection
  • SelectionMode
  • SelectedItemsOrder
• Text processing
  • Separator
  • Custom text
    • Customize the overlay
  • Selecting items from text input
    • Basic Example
    • Custom ObjectToStringComparer Example
  • Adding new items from text input
    • Basic Example
    • Custom StringToObjectParser Example

Introduction

The MultiSelectionComboBox is like a normal ComboBox, but instead of limit the selection to one item, the user is allowed to select multiple items.

The user interface

Common Properties

This control has all properties which are known from the normal ComboBox and in addition the following properties.

Styles

MultiSelectionComboBox-Styles

MahApps ships two build in styles for this control.

The default style (MahApps.Styles.MultiSelectionComboBox) wraps the selected items, if not all fits into a single line:

If you want a single line you can use MahApps.Styles.MultiSelectionComboBox.Horizontal which will show a horizontal ScrollViewer, if not all items fit into the available space.

ItemContainer-Styles

MahApps ships two build in styles for the item container visible when the DropDown is open.

The default style (MahApps.Styles.MultiSelectionComboBoxItem) looks like the one from the normal ComboBox.

If you want to present CheckBoxes to the user you can use the MahApps.Styles.MultiSelectionComboBoxItem.CheckBox style:

SelectedItemContainer-Styles

Also for this MahApps ships two build in styles. Please note that these are only applied if IsEditable=false.

The default one wraps each item in a nugget like container:

If you want to provide an option to remove from the selected items you can use MahApps.Styles.MulitselectionComboBoxSelectedItem.Removeable which will add a delete button next to each item:

Selection

SelectionMode

The MultiSelectionComboBox supports all SelectionModes which are known from other controls with multi selection support (for example ListBox).

SelectedItemsOrder

This enum defines how the selected items should be presented to the user. The following values are possible:

Text processing

Separator

The Separator is used to concatenate the selected items into one single string. if the text comes from user input, the Separator is also used to split the input string into fragments which will be used to select the requested items.

Custom text

If the text entered into the editable TextBox does not match the string representation of the SelectedItems, the DropDown will show an overlay above the Items and will disable selection. This will prevent loss any user input. The property HasCustomText will be set to true in this case.

Build-in overlay

Customize the overlay

If you don't like the build-in overlay, you can roll your own as shown below.

<mah:MultiSelectionComboBox ItemsSource="{Binding Animals}"
                            IsEditable="True"
                            Text="CustomText" >
    <mah:MultiSelectionComboBox.DisabledPopupOverlayContentTemplate>
        <DataTemplate>
            <!-- Note: mah:MultiSelectionComboBox.ClearContentCommand will reset the text to match the SelectedItems representation if executed -->
            <Button Background="{DynamicResource MahApps.Brushes.Accent4}" 
                    BorderThickness="0"
                    Command="{x:Static mah:MultiSelectionComboBox.ClearContentCommand}">
                <TextBlock Text="🤷" 
                           VerticalAlignment="Center" 
                           HorizontalAlignment="Center" 
                           FontSize="50" />
            </Button>
        </DataTemplate>
    </mah:MultiSelectionComboBox.DisabledPopupOverlayContentTemplate>
</mah:MultiSelectionComboBox>

The result will look like this:

Selecting items from text input

If the control is editable and you have set a ObjectToStringComparer, the MultiSelectionComboBox will try to select the items from the user input. The build-in comparer will compare the input string fragments with the objects string representation while taking the StringComparison into account.

Basic Example

<!--
    - The Separator must be defined for automatic item selection.
    - The SelectItemsFromTextInputDelay is optional. If it is set to -1,
      it means the items will be selected only after LostFocus.
    - The EditableTextStringComparision is optional.
    - We use the build in comparer (DefaultObjectToStringComparer), but you can also use your own.
-->

<mah:MultiSelectionComboBox ItemsSource="{Binding Animals}"            
                            SelectionMode="Multiple"
                            IsEditable="True"
                            Separator=", "
                            SelectItemsFromTextInputDelay="200"
                            EditableTextStringComparision="OrdinalIgnoreCase"
                            ObjectToStringComparer="{mah:DefaultObjectToStringComparer}" />

Custom ObjectToStringComparer Example

You can use any class that implements the ICompareObjectToString interface to compare your items to the entered text. For this example lets assume you have the following class User where you want to select the items by Userame or MailAddress.

public class User
{
    public string Username {get; set;}
    public string Name {get; set;}
    public string GivenName {get; set;}
    public string MailAddress {get; set;}
}

We can now implement the interface as shown below:

public class MyUserToStringComparer : ICompareObjectToString
{
    // This function is expected to be implemented. Returns true if the item matches, otherise false.
    public bool CheckIfStringMatchesObject(
        string? input,                      // The text fragment to test 
        object? objectToCompare,            // The item to test for match
        StringComparison stringComparison,  // The string comparison to use
        string? stringFormat)               // The string format to use
    {
        // we cast the object to compare to a user.
        var user = objectToCompare as User;
        
        // if the input is null or the user is null we return false. 
        if (input is null || user is null)
        {
            return false;
        }
        
        // If either the Username or the MailAddress matches the provided  
        // input string we return true, otherwise we return false.
        return input.Equals(user.Username, stringComparison) 
               || input.Equals(user.MailAddress, stringComparison);
    }
}

Adding new items from text input

If the control is editable and you have set a StringToObjectParser, the MultiSelectionComboBox will try to create a new item if the item was not found (see Selecting items from text input). The build-in parser will try to use reflection to create a new item from the input string, but you can also provide your own implementation.

Basic Example

<mah:MultiSelectionComboBox ItemsSource="{Binding Animals}"
                            SelectionMode="Multiple"
                            IsEditable="True"
                            Separator=", "
                            SelectItemsFromTextInputDelay="200"
                            EditableTextStringComparision="OrdinalIgnoreCase"
                            ObjectToStringComparer="{mah:DefaultObjectToStringComparer}" 
                            StringToObjectParser="{x:Static mah:DefaultStringToObjectParser.Instance}" />

Custom StringToObjectParser Example

You can use any class that implements the IParseStringToObject interface to parse the user input to a new object. The interface has one member called TryCreateObjectFromString. Let's assume we have a List<string> called Animals. The user can add new animals, but before adding a new animal, we want the user to confirm the input.

public class MyObjectParser : IParseStringToObject
{
    // This function is expected to be implemented. Returns true if the item could be created, otherise false.
    public bool TryCreateObjectFromString(
        string? input,                      // The input string to parse
        out object? result,                 // return the object here if successful, otherwise return null
        CultureInfo? culture = null,        // The culture which should be used to parse. This parameter is optional
        string? stringFormat = null,        // The string format to apply. This parameter is optional
        Type? elementType = null)           // The Type to which the input should be converted to. This parameter is optional
    {
        // if we got an empty string, we return false and set the result to null
        if (string.IsNullOrWhiteSpace(input))
        {
            result = null;
            return false;
        }

        // We ask the user for confirmation
        if (MessageBox.Show(
            $"Do you want to add \"{input}\" to the animals list?", 
            "Add Animal", 
            MessageBoxButtons.YesNo) == DialogResult.Yes)
        {
            // The user accepted this item. As our List contains only strings, we can just return the input string.
            result = input;  
            return true;
        }
        else
        {
            result = null;
            return false;
        }
    }
}