OpenMaui.SearchablePicker 1.0.3

OpenMaui.SearchablePicker

A searchable, themeable drop-in replacement for the native MAUI <Picker> control.
Works in XAML and C#. Supports any data model. No wrapper types needed.

---

Table of Contents

1. Installation
2. One-Time Setup
3. Quick Start
4. Using in XAML
5. Using in C#
6. Customizing Colors
7. Global Theme
8. All Properties Reference
9. SearchablePickerOptions Reference
10. FAQ

---

Installation

dotnet add package OpenMaui.SearchablePicker

Or search Maui.SearchablePicker in the NuGet Package Manager inside Visual Studio / Rider.

---

One-Time Setup

Open your MauiProgram.cs and add one line:

using Maui.SearchablePicker.Extensions;

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

    builder
        .UseMauiApp<App>()
        .UseMauiSearchablePicker();   // ← add this

    return builder.Build();
}

That's all the setup you ever need.

---

Quick Start

Your model (no changes required)

public class Country
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Code { get; set; }
}

Your ViewModel

public partial class MyViewModel : ObservableObject
{
    public List<Country> Countries { get; } = new()
    {
        new Country { Id = 1, Name = "Australia",      Code = "AU" },
        new Country { Id = 2, Name = "United Kingdom", Code = "UK" },
        new Country { Id = 3, Name = "United States",  Code = "US" },
    };

    [ObservableProperty]
    private Country? selectedCountry;
}

XAML

xmlns:sp="clr-namespace:Maui.SearchablePicker.Controls;assembly=Maui.SearchablePicker"

<sp:SearchablePicker
    Title="Select Country"
    ItemsSource="{Binding Countries}"
    DisplayMemberPath="Name"
    SelectedItem="{Binding SelectedCountry, Mode=TwoWay}" />

Tap the control → searchable popup opens → user picks → SelectedCountry in your ViewModel updates automatically.

---

Using in XAML

Namespace declaration

Add this to the root element of your XAML page or view:

xmlns:sp="clr-namespace:Maui.SearchablePicker.Controls;assembly=Maui.SearchablePicker"

Minimal usage

<sp:SearchablePicker
    Title="Select an option"
    ItemsSource="{Binding MyList}"
    DisplayMemberPath="Name"
    SelectedItem="{Binding SelectedItem, Mode=TwoWay}" />

Full usage with all options

<sp:SearchablePicker
    Title="Select Country"
    ItemsSource="{Binding Countries}"
    DisplayMemberPath="Name"
    SelectedItem="{Binding SelectedCountry, Mode=TwoWay}"

    PlaceholderColor="#AAAAAA"
    SelectedTextColor="#1C1C1C"
    PickerBorderColor="#CCCCCC"
    PickerBackgroundColor="White"

    ChevronColor="#17375E"
    ChevronSource="my_arrow_icon.png"

    PopupTitleBarColor="#17375E"
    PopupTitleTextColor="White"
    PopupSearchBorderColor="#17375E"
    PopupItemTextColor="#1C1C1C"
    PopupDividerColor="#17375E"
    PopupCancelColor="#17375E"
    PopupCancelText="Cancel"
    PopupSearchPlaceholder="Search..." />

Reacting to selection in code-behind

<sp:SearchablePicker
    x:Name="CountryPicker"
    Title="Select Country"
    ItemsSource="{Binding Countries}"
    DisplayMemberPath="Name"
    SelectedItemChanged="OnCountryChanged" />

private void OnCountryChanged(object sender, object? selected)
{
    if (selected is Country country)
        Console.WriteLine($"Selected: {country.Name}");
}

---

Using in C#

Show a searchable picker from any page

using Maui.SearchablePicker.Extensions;

// Inside any Page method or code-behind
var selected = await this.ShowSearchablePickerAsync(
    title: "Select Country",
    items: countries,               // IList<Country>
    displaySelector: c => c.Name   // which property to display
);

// selected is Country? — null if the user cancelled or tapped outside
if (selected != null)
    Console.WriteLine($"User picked: {selected.Name}");

With custom colors

var selected = await this.ShowSearchablePickerAsync(
    title: "Select Country",
    items: countries,
    displaySelector: c => c.Name,
    options: new SearchablePickerOptions
    {
        TitleBarColor    = Colors.Teal,
        TitleTextColor   = Colors.White,
        ItemTextColor    = Colors.DarkSlateGray,
        CancelButtonText = "Close"
    }
);

From a ViewModel — via service injection (recommended for MVVM)

// MauiProgram.cs — already registered by UseMauiSearchablePicker()
// No extra registration needed.

public class MyViewModel
{
    private readonly ISearchablePickerService _picker;

    public MyViewModel(ISearchablePickerService picker)
    {
        _picker = picker;
    }

    [RelayCommand]
    private async Task SelectCountry()
    {
        var result = await _picker.ShowAsync(
            title: "Select Country",
            items: Countries,
            displaySelector: c => c.Name
        );

        if (result != null)
            SelectedCountry = result;
    }
}

From a ViewModel — via event bridge (alternative)

// ViewModel
public class MyViewModel
{
    public event Action<IList<Country>>? RequestCountryPicker;

    [RelayCommand]
    private void SelectCountry() => RequestCountryPicker?.Invoke(Countries);

    public void OnCountrySelected(Country? country)
    {
        if (country != null) SelectedCountry = country;
    }
}

// Code-behind
public partial class MyPage : ContentPage
{
    public MyPage(MyViewModel vm)
    {
        InitializeComponent();
        BindingContext = vm;
        vm.RequestCountryPicker += ShowCountryPicker;
    }

    private async void ShowCountryPicker(IList<Country> countries)
    {
        var selected = await this.ShowSearchablePickerAsync(
            title: "Select Country",
            items: countries,
            displaySelector: c => c.Name
        );
        ((MyViewModel)BindingContext).OnCountrySelected(selected);
    }
}

---

Customizing Colors

All color properties have built-in defaults — you only set what you want to change.

Per-control (XAML inline)

<sp:SearchablePicker
    PopupTitleBarColor="DarkSlateBlue"
    PopupItemTextColor="DimGray"
    PopupDividerColor="LightGray"
    PopupCancelText="Dismiss"
    ... />

Per-control (code)

CountryPicker.PopupTitleBarColor = Colors.DarkSlateBlue;
CountryPicker.PopupCancelText = "Dismiss";

---

Global Theme

Set colors once in MauiProgram.cs — every SearchablePicker in the app automatically inherits them.

builder.UseMauiSearchablePicker(defaults: new SearchablePickerOptions
{
    TitleBarColor         = Colors.DarkSlateBlue,
    TitleTextColor        = Colors.White,
    SearchBorderColor     = Colors.DarkSlateBlue,
    ItemTextColor         = Colors.DimGray,
    DividerColor          = Colors.LightGray,
    CancelButtonColor     = Colors.DarkSlateBlue,
    CancelButtonText      = "Close",
    SearchPlaceholderText = "Type to filter..."
});

Priority chain (highest wins):

Per-control Popup* props  →  Global defaults  →  Built-in fallbacks

---

All Properties Reference

Control appearance properties

These control how the picker looks on your page (the closed/idle state).

---

Title

Type: string | Default: "Select..."

The placeholder text shown when nothing is selected. Also the popup's header title.

<sp:SearchablePicker Title="Select a Country" ... />

---

ItemsSource

Type: IEnumerable | Default: null

The list of items to display. Accepts any collection — List<T>, ObservableCollection<T>, arrays, etc.

<sp:SearchablePicker ItemsSource="{Binding Countries}" ... />

---

DisplayMemberPath

Type: string | Default: null (falls back to .ToString())

The name of the property on each item to display as text in the popup list and in the control when selected.

<sp:SearchablePicker DisplayMemberPath="Name" ... />

---

SelectedItem

Type: object | Binding: TwoWay | Default: null

The currently selected item. Bind two-way to your ViewModel property. Updates automatically when the user picks.

<sp:SearchablePicker SelectedItem="{Binding SelectedCountry, Mode=TwoWay}" ... />

---

SelectedIndex

Type: int | Binding: TwoWay | Default: -1

Zero-based index of the selected item. -1 means nothing is selected.

<sp:SearchablePicker SelectedIndex="{Binding SelectedIndex, Mode=TwoWay}" ... />

---

PlaceholderColor

Type: Color | Default: #AAAAAA

Colour of the Title text when nothing is selected.

<sp:SearchablePicker PlaceholderColor="#999999" ... />

---

SelectedTextColor

Type: Color | Default: #1C1C1C

Colour of the text when an item is selected.

<sp:SearchablePicker SelectedTextColor="DarkSlateGray" ... />

---

PickerBorderColor

Type: Color | Default: #CCCCCC

Border colour of the control in its idle state.

<sp:SearchablePicker PickerBorderColor="#17375E" ... />

---

PickerBackgroundColor

Type: Color | Default: White

Background colour of the control in its idle state.

<sp:SearchablePicker PickerBackgroundColor="#F5F5F5" ... />

---

ChevronSource

Type: ImageSource | Default: built-in ▼

Replace the default dropdown arrow with a custom icon. Accepts file name, URI, or FontImageSource.

<sp:SearchablePicker ChevronSource="my_arrow.png" ... />

---

ChevronColor

Type: Color | Default: #17375E

Colour of the default built-in chevron. Has no effect when ChevronSource is set.

<sp:SearchablePicker ChevronColor="Teal" ... />

---

SelectedItemChanged (event)

Type: EventHandler<object?>

Fires when the user selects an item. Argument is the selected model object, or null if cancelled.

<sp:SearchablePicker SelectedItemChanged="OnCountryChanged" ... />

private void OnCountryChanged(object sender, object? selected)
{
    if (selected is Country c) MyLabel.Text = c.Name;
}

---

Popup appearance properties (Popup*)

These control how the popup looks when opened. All have default fallbacks — set only what you need.

Property	Type	Default	What it controls
PopupTitleBarColor	Color	#17375E	Header bar background
PopupTitleTextColor	Color	White	Header title text
PopupSearchBorderColor	Color	#17375E	Search box border
PopupSearchPlaceholder	string	"Search..."	Search box placeholder
PopupItemTextColor	Color	#1C1C1C	List item text
PopupDividerColor	Color	#17375E	Divider between items
PopupCancelColor	Color	#17375E	Cancel button colour
PopupCancelText	string	"Cancel"	Cancel button label

---

SearchablePickerOptions Reference

Used with UseMauiSearchablePicker(defaults: ...) for global theme, or passed to ShowSearchablePickerAsync().
All properties are optional — null means use the built-in fallback.

new SearchablePickerOptions
{
    TitleBarColor         = Colors.Teal,
    TitleTextColor        = Colors.White,
    SearchBorderColor     = Colors.Teal,
    SearchPlaceholderText = "Type to filter...",
    ItemTextColor         = Colors.DimGray,
    DividerColor          = Colors.LightGray,
    CancelButtonColor     = Colors.Teal,
    CancelButtonText      = "Close"
}

Property	Type	Default	Description
TitleBarColor	Color?	#17375E	Popup header background
TitleTextColor	Color?	White	Popup header text
SearchBorderColor	Color?	#17375E	Search box border
SearchPlaceholderText	string?	"Search..."	Search box placeholder
ItemTextColor	Color?	#1C1C1C	List item text
DividerColor	Color?	#17375E	Divider line
CancelButtonColor	Color?	#17375E	Cancel button
CancelButtonText	string?	"Cancel"	Cancel label

---

FAQ

Q: Do I need to change my data models?
No. Pass any existing list directly. Use DisplayMemberPath to specify which property to show.

Q: What if my items don't have a named property to display?
Leave DisplayMemberPath unset — the picker calls .ToString() on each item automatically.

Q: Can I use this purely from a ViewModel with no code-behind?
Yes. Inject ISearchablePickerService (auto-registered by UseMauiSearchablePicker()):

var result = await _picker.ShowAsync("Select", items, x => x.Name);

Q: What happens when the user taps outside the popup?
The popup closes, SelectedItem does not change, and ShowSearchablePickerAsync() returns null.

Q: How do I pre-select an item?
Bind SelectedItem to a pre-populated ViewModel property, or set SelectedIndex="0" in XAML.

Q: Does search run on multiple properties?
Not in v1.0 — search filters on DisplayMemberPath only. Multi-property search is planned for v1.1.

---

License

GPL v3 — see LICENSE.