Selection in .NET MAUI Autocomplete (SfAutocomplete)

29 Jun 202524 minutes to read

The .NET MAUI Autocomplete allows user to select single or multiple items. The selection mode can be set by using the SelectionMode property. There are two different selection modes: Single and Multiple.

Single selection

The Autocomplete allows the user to select an item by entering the value using the keyboard, then selecting from the drop-down list by clicking the item. The selected item can be retrieved from the SelectedItem property.

//Model.cs
public class SocialMedia
{
    public string Name { get; set; }
    public int ID { get; set; }
}

//ViewModel.cs
public class SocialMediaViewModel
{
    public ObservableCollection<SocialMedia> SocialMedias { get; set; }
    public ObservableCollection<SocialMedia> SelectedItemsList { get; set; }
    public ObservableCollection<object> SelectedValueList { get; set; }

    public SocialMediaViewModel()
    {
        this.SocialMedias = new ObservableCollection<SocialMedia>();
        this.SocialMedias.Add(new SocialMedia() { Name = "Facebook", ID = 0 });
        this.SocialMedias.Add(new SocialMedia() { Name = "Google Plus", ID = 1 });
        this.SocialMedias.Add(new SocialMedia() { Name = "Instagram", ID = 2 });
        this.SocialMedias.Add(new SocialMedia() { Name = "LinkedIn", ID = 3 });
        this.SocialMedias.Add(new SocialMedia() { Name = "Skype", ID = 4 });
        this.SocialMedias.Add(new SocialMedia() { Name = "Telegram", ID = 5 });
        this.SocialMedias.Add(new SocialMedia() { Name = "Televzr", ID = 6 });
        this.SocialMedias.Add(new SocialMedia() { Name = "Tik Tok", ID = 7 });
        this.SocialMedias.Add(new SocialMedia() { Name = "Tout", ID = 8 });
        this.SocialMedias.Add(new SocialMedia() { Name = "Tumblr", ID = 9 });
        this.SocialMedias.Add(new SocialMedia() { Name = "Twitter", ID = 10 });
        this.SocialMedias.Add(new SocialMedia() { Name = "Vimeo", ID = 11 });
        this.SocialMedias.Add(new SocialMedia() { Name = "WhatsApp", ID = 12 });
        this.SocialMedias.Add(new SocialMedia() { Name = "YouTube", ID = 13 });

        SelectedItemsList = new ObservableCollection<SocialMedia>();
        this.SelectedItemsList.Add(SocialMedias[0]);
        this.SelectedItemsList.Add(SocialMedias[2]);
        this.SelectedItemsList.Add(SocialMedias[4]);

        this.SelectedValueList = new ObservableCollection<object>();
        this.SelectedValueList.Add(SocialMedias[0].ID); 
        this.SelectedValueList.Add(SocialMedias[4].ID);
    }
}
<editors:SfAutocomplete x:Name="autocomplete"
                        ItemsSource="{Binding SocialMedias}"
                        DisplayMemberPath="Name"
                        TextMemberPath="Name" />
SfAutocomplete autocomplete = new SfAutocomplete()
{
    DisplayMemberPath = "Name",
    TextMemberPath = "Name",
    MinimumPrefixCharacters = 3,
    TextSearchMode = AutocompleteTextSearchMode.StartsWith,
    ItemsSource = socialMediaViewModel.SocialMedias
};

The following gif image illustrates the result of the above code:

.NET MAUI Autocomplete with single selection mode.

Multiple selection

The Autocomplete allows user to select multiple values from the drop-down list by setting the SelectionMode property as Multiple.

The selected items can be changed programmatically by using the SelectedItems property. This property allows both getting and setting of the selected items in the Autocomplete control.

Also there are two ways to display multi-selection items in the AutoComplete control using MultiSelectionDisplayMode property. By default MultiSelectionDisplayMode is Token.

<editors:SfAutocomplete x:Name="autoComplete"
                SelectionMode="Multiple"
                ItemsSource="{Binding SocialMedias}"
                SelectedItems="{Binding SelectedItemsList}"
                DisplayMemberPath="Name"
                TextMemberPath="Name" />
SfAutocomplete autocomplete = new SfAutocomplete()
{
    SelectionMode = AutocompleteSelectionMode.Multiple,
    ItemsSource = socialMediaViewModel.SocialMedias
    SelectedItems = socialMediaViewModel.SelectedItemsList,
    DisplayMemberPath = "Name",
    TextMemberPath = "Name"
};

Delimiter

When setting MultiSelectionDisplayMode to Delimiter, the selected items can be separated by the desired character specified as the delimiter. We can set the delimiter text to any preferred character using the DelimiterText property. By default DelimiterText is “,”.

<editors:SfAutocomplete x:Name="autoComplete" 
                         ItemsSource="{Binding SocialMedias}"
                         SelectionMode="Multiple"
                         MultiSelectionDisplayMode="Delimiter"
                         DelimiterText="/"
                         MaxDropDownHeight="250"
                         DisplayMemberPath="Name"
                         TextMemberPath="Name"
                         Placeholder="Enter Media" />
SfAutocomplete autocomplete = new SfAutocomplete()
{
    ItemsSource = socialMediaViewModel.SocialMedias,
    SelectionMode = AutocompleteSelectionMode.Multiple,
    MultiSelectionDisplayMode = AutocompleteMultiSelectionDisplayMode.Delimiter,
    DelimiterText = "/",
    MaxDropDownHeight = 250,
    DisplayMemberPath = "Name",
    TextMemberPath = "Name",
    Placeholder = "Enter Media"
};

.NET MAUI Autocomplete with MultiSelectionDisplayMode as Delimiter.

Token

Multi-selection token mode has two different layouts to display the selected items by setting TokensWrapMode property.

Wrap mode

When the TokensWrapMode is set to Wrap, the selected items will be wrapped to the next line of the SfAutocomplete.

<editors:SfAutocomplete x:Name="autoComplete" 
             ItemsSource="{Binding SocialMedias}"
             SelectionMode="Multiple"
             MaxDropDownHeight="250"
             DisplayMemberPath="Name"
             Placeholder="Enter Media"
             TextMemberPath="Name"
             TokensWrapMode="Wrap" />
SfAutocomplete autoComplete = new SfAutocomplete
{
    ItemsSource = socialMediaViewModel.SocialMedias,
    DisplayMemberPath = "Name",
    TextMemberPath = "Name",
    Placeholder = "Enter Media",
    SelectionMode = AutocompleteSelectionMode.Multiple,
    MaxDropDownHeight = 250,
    TokensWrapMode = AutoCompleteTokensWrapMode.Wrap
};

.NET MAUI Autocomplete with TokensWrapMode as wrap.

None Mode

When the TokensWrapMode is set to None, the selected item will be wrapped in a horizontal orientation.

<editors:SfAutoComplete x:Name="autoComplete" 
             ItemsSource="{Binding SocialMedias}"
             DisplayMemberPath="Name"
             TextMemberPath="Name"
             Placeholder="Enter Media"
             SelectionMode="Multiple"
             MaxDropDownHeight="250"
             TokensWrapMode="None" />
SfAutocomplete autoComplete = new SfAutocomplete
{
    ItemsSource = socialMediaViewModel.SocialMedias,
    SelectionMode = AutocompleteSelectionMode.Multiple,
    MaxDropDownHeight = 250,
    DisplayMemberPath = "Name",
    Placeholder = "Enter Media",
    TextMemberPath = "Name",
    TokensWrapMode = AutoCompleteTokensWrapMode.None
};

.NET MAUI Autocomplete with TokensWrapMode as none.

Selection changing notification

When a user attempts to select an item from the drop-down list, the SelectionChanging event is triggered. This event allows developers to intercept the selection process, providing an opportunity to cancel or modify the selection based on predefined criteria.

The SelectionChangingEventArgs provides essential data related to the selection-changing event:

  • CurrentSelection - Contains the item that are about to be selected.
  • PreviousSelection - Contains the item that were previously selected.
  • Cancel - Allows preventing the selection change when set to true.
<editors:SfAutocomplete x:Name="autocomplete"
                        ItemsSource="{Binding SocialMedias}"
                        TextMemberPath="Name"
                        DisplayMemberPath="Name"
                        SelectionChanging="OnSelectionChanging"/>
SfAutoComplete autocomplete = new SfAutoComplete
{
    ItemsSource = socialMediaViewModel.SocialMedias,
    TextMemberPath = "Name",
    DisplayMemberPath = "Name"
};
autocomplete.SelectionChanging += OnSelectionChanging;

The SelectionChanging event can be handled as follows:

private async void OnSelectionChanging(object sender, Syncfusion.Maui.Inputs.SelectionChangingEventArgs e)
{
    await DisplayAlert("Alert", "Selecting Item has changing", "Ok");
}

The following gif image illustrates the result of the above code:

.NET MAUI Autocomplete selection changing event notification.

Selection changed notification

When an item is selected from the drop-down list, the SelectionChanged event is triggered. The SelectionChanged event contains the newly selected and removed items in the AddedItems and RemovedItems properties. The SelectionChanged Event contains the following properties:

  • AddedItems - Contains the item that were currently selected.
  • RemovedItems - Contains the item that were unselected.
<editors:SfAutocomplete x:Name="autocomplete"
                        ItemsSource="{Binding SocialMedias}"
                        TextMemberPath="Name"
                        DisplayMemberPath="Name"
                        SelectionChanged="OnSelectionChanged"/>
SfAutocomplete autocomplete = new SfAutocomplete()
{
    ItemsSource = socialMediaViewModel.SocialMedias,
    TextMemberPath = "Name",
    DisplayMemberPath = "Name",
};
autocomplete.SelectionChanged += OnSelectionChanged;

The SelectionChanged event can be handled as follows:

private async void OnSelectionChanged(object sender, Syncfusion.Maui.Inputs.SelectionChangedEventArgs e)
{
    await DisplayAlert("Alert", "Selected Item has changed", "Ok");
}

The following gif image illustrates the result of the above code:

.NET MAUI Autocomplete selection changed event notification.

NOTE

SelectionChanged event arguments CurrentSelection and PreviousSelection marked as “Obsolete”. You can use the AddedItems and RemovedItems event arguments.

Selected value

The SelectedValue property in a Autocomplete control allows you to get or set the selected value based on the SelectedItem or SelectedItems depending on the selection mode. The SelectedValuePath property specifies which property of the selected item is used to populate the SelectedValue.

In single selection mode, the SelectedValue property holds the value defined by the SelectedValuePath property, such as “ID”. When the SelectedItem returns the entire object (e.g., SocialMedia), the SelectedValue contains the value of SocialMedia.ID field.

<StackLayout>
    <editors:SfAutocomplete x:Name="autocomplete"
                            MaxDropDownHeight="250"
                            TextMemberPath="Name"
                            DisplayMemberPath="Name"
                            ItemsSource="{Binding SocialMedias}"
                            SelectedValuePath="ID"
                            SelectionChanged="OnSelectionChanged"/>
    <HorizontalStackLayout>
        <Label x:Name="labelTitle" Text="SelectedValue :" />
        <Label x:Name="selectedValue" />
    </HorizontalStackLayout>
</StackLayout>
SfAutocomplete autocomplete = new SfAutocomplete
{
    MaxDropDownHeight = 250,
    TextMemberPath = "Name",
    DisplayMemberPath = "Name",
    ItemsSource = socialMediaViewModel.SocialMedias,
    SelectedValuePath = "ID"
};
autocomplete.SelectionChanged += OnSelectionChanged;

Label labelTitle = new Label { Text = "SelectedValue :" };
Label selectedValue = new Label();

HorizontalStackLayout horizontalLayout = new HorizontalStackLayout()
{
    Children = { labelTitle, selectedValue }
};

StackLayout mainLayout = new StackLayout
{
    Children = { autocomplete, horizontalLayout }
};
private void OnSelectionChanged(object sender, Syncfusion.Maui.Inputs.SelectionChangedEventArgs e)
{
    selectedValue.Text = autocomplete.SelectedValue.ToString();
}

The following gif image illustrates the result of the above code:

.NET MAUI Autocomplete single selected value.

In multi-selection mode, the SelectedValue is a collection of values derived from the SelectedItems based on the SelectedValuePath property such as “ID”, the SelectedValue will contains a list of IDs (e.g., SocialMedia.ID) corresponding to the selected SocialMedia items.

<StackLayout>
    <editors:SfAutocomplete x:Name="autocomplete"
                            MaxDropDownHeight="250"
                            TextMemberPath="Name"
                            DisplayMemberPath="Name"
                            ItemsSource="{Binding SocialMedias}"
                            SelectionMode="Multiple"
                            SelectedValuePath="ID"
                            SelectedValue="{Binding SelectedValueList}"
                            SelectionChanged="OnSelectionChanged"/>
    <HorizontalStackLayout>
        <Label x:Name="labelTitle" Text="SelectedValue count :"/>
        <Label x:Name="selectedValue"/>
    </HorizontalStackLayout>
</StackLayout>
SfAutocomplete autocomplete = new SfAutocomplete
{
    MaxDropDownHeight = 250,
    TextMemberPath = "Name",
    DisplayMemberPath = "Name",
    ItemsSource = socialMediaViewModel.SocialMedias,
    SelectionMode = AutocompleteSelectionMode.Multiple,
    SelectedValuePath = "ID",
    SelectedValue = socialMediaViewModel.SelectedValueList
};
autocomplete.SelectionChanged += OnSelectionChanged;

Label labelTitle = new Label { Text = "SelectedValue count :" };
Label selectedValue = new Label();

HorizontalStackLayout horizontalLayout = new HorizontalStackLayout()
{
    Children = { labelTitle, selectedValue }
};

StackLayout mainLayout = new StackLayout
{
    Children = { autocomplete, horizontalLayout }
};
private void OnSelectionChanged(object sender, Syncfusion.Maui.Inputs.SelectionChangedEventArgs e)
{
    if(autocomplete != null && autocomplete.SelectedValue is IList<object> value)
    {
        selectedValue.Text = value.Count.ToString();
    }
}

The following gif image illustrates the result of the above code:

.NET MAUI Autocomplete multiple selected value.

NOTE

If the SelectedValuePath is not specified, the SelectedValue will be the same as the SelectedItem or SelectedItems, depending on the selection mode.

Hide clear button in the Autocomplete

By default, the clear button X will be displayed in the editor of the Autocomplete control, which can be used to clear the entered input. Hide the clear button in Autocomplete control using the IsClearButtonVisible property. The default value of IsClearButtonVisible property value is true.

<editors:SfAutocomplete x:Name="autocomplete"
                        IsClearButtonVisible="false"
                        ItemsSource="{Binding SocialMedias}"
                        DisplayMemberPath="Name"
                        TextMemberPath="Name" />
SfAutocomplete autocomplete = new SfAutocomplete
{
    IsClearButtonVisible = false,
    ItemsSource = socialMediaViewModel.SocialMedias,
    DisplayMemberPath = "Name",
    TextMemberPath = "Name"
};

The following image illustrates the result of the above code:

.NET MAUI Autocomplete is clear button visible.

Is Drop-Down Open

In the Autocomplete control, the drop-down can be opened or closed programmatically by using the IsDropDownOpen property. The default value of the IsDropDownOpen property is false.

<editors:SfAutocomplete x:Name="autocomplete"
                        ItemsSource="{Binding SocialMedias}"
                        IsDropDownOpen = "true";
                        DisplayMemberPath="Name"
                        TextMemberPath="Name">
</editors:SfAutocomplete>
SfAutocomplete autocomplete = new SfAutocomplete
{
    ItemsSource = socialMediaViewModel.SocialMedias,
    IsDropDownOpen = true,
    DisplayMemberPath = "Name",
    TextMemberPath = "Name"
};

Clear Selected Items

Users can remove selected items and input text using the Clear method in the Autocomplete control.

autocomplete.Clear();