blzr.bootstrap-select

This Blazor bootstap select component is inspired by the js bootstrap-select, rewritten using C# as a Razor Component.

There is no dependency with JavaScript.

To see it in action, visit https://rob-newman.github.io/blzr.bootstrap-select/

Getting Setup

You can install the package via the NuGet package manager just search for Blzr.BootstrapSelect. You can also install via powershell using the following command.

Install-Package Blzr.BootstrapSelect

Or via the dotnet CLI.

dotnet add package Blzr.BootstrapSelect

1. Register Services

You will need to register the Blzr.BootstrapSelect service in your application

Blazor WebAssembly

Add the following line to your applications Program.Main method.

builder.Services.AddBootstrapSelect();

Blazor Server

Add the following line to your applications Startup.ConfigureServices method.

services.AddBootstrapSelect();

2. Add Imports

Add the following to your _Imports.razor

@using Blzr.BootstrapSelect

3. Add reference to style sheet(s)

Add the following line to the head tag of your _Host.cshtml (Blazor Server app) or index.html (Blazor WebAssembly).

We ship both minified and unminified CSS.

For minified use:

<link href="_content/Blzr.BootstrapSelect/blzr-bootstrap-select.min.css" rel="stylesheet" />

For unminified use:

<link href="_content/Blzr.BootstrapSelect/blzr-bootstrap-select.css" rel="stylesheet" />

Presumably, you already have bootstrap css referenced in your project. If not, use:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@4.5.3/dist/css/bootstrap.min.css" integrity="sha384-TX8t27EcRE3e/ihU7zmQxVncDAy5uIKz4rEkgIXeMed4M0jlfIDPvg6uqKI2xXr2" crossorigin="anonymous">

Defaults

The following system wide defaults can be configured as part of the service registration

ShowSearch (Default: false) - Determines if the search box should be displayed. When true, adds a search box to the top of the drop down (works in conjunction with ShowSearchThreshold)
ShowSearchThreshold (Default: 0) - The threshold to determine the number of options that must exists before the search box is displayed
SearchPlaceholderText (Default: "Search") - The placeholder text displayed in the search box
SearchNotFoundText (Default: "No matching results") - The text displayed if no options match a search term
DelayValueChangedCallUntilClose (Default: false) - For multi's only, whether to delay calling ValueChanged until after the select is closed (default will fire after each option is selected/deselected)
SelectedTextFormat (Default: SelectedTextFormats.Values) - Specifies how the selection is displayed with a multi select. Values displays a list of the selected options (separated by MultiSeparator). Static simply displays the select element's placeholder text. Count displays the total number of selected options. CountGreaterThan behaves like Values until the number of selected options is greater than SelectedTextFormatCount where it then behaves like Count
SelectedTextFormatCount (Default: 0) - If SelectedTextFormat is CountGreaterThan, ths is the number of options that must be selected for the Count format to be applied
MultiSelectedText (Default: "{0} of {1} selected") - Specifies the text to display when the SelectedTextFormat is count. {0} is replaced with the number of selected items. {1} is replaced with the total number of options
MultiSeparator (Default: ", ") - The separator used for multi selected text when the format is Values
ShowPlaceholder (Default: false) - For singles only, determines if the placeholder text should be displayed
MultiPlaceholderText (Default: "Nothing selected") - The text to display as the placeholder for multi's
SinglePlaceholderText (Default: "Select...") - The text to display as the placeholder for singles
ShowTick (Default: false) - Whether to show the checkmark on singles
MaxSelectionsText (Default: "Limit reached ({0} items max)") - The text to display if the max number of selections is met. {0} is replaced with the MaxSelections parameter
SearchStyle (Default: SearchStyles.Contains) - When set to SearchStyles.Contains, searching will reveal options that contain the searched text. When set to SearchStyles.StartsWith, searching will reveal options that start with the searched text
ShowActions (Default: false) - For multi's only. When set, adds two buttons to the top of the dropdown menu (Select All and Deselect All)
SelectAllText (Default: "Select All") - The text to display on the select all button
DeselectAllText (Default: "Deselect All") - The text to display on the deselect all button
ButtonStyle (Default: ButtonStyles.Default) - The button class to use to style the select button

Example

builder.Services.AddBootstrapSelect(defaults =>
                {
                    defaults.ShowSearch = true;
                    defaults.SearchPlaceholderText = "Find";
                    defaults.ShowSearchThreshold = 10;
                    defaults.SearchNotFoundText = "Can't find any";
                    defaults.DelayValueChangedCallUntilClose = true;
                    defaults.SelectedTextFormat = SelectedTextFormats.CountGreaterThan;
                    defaults.SelectedTextFormatCount = 2;
                    defaults.MultiSelectedText = "{0} selected";
                    defaults.MultiSeparator = "|";
                    defaults.ShowPlaceholder = true;
                    defaults.MultiPlaceholderText = "Pick some";
                    defaults.SinglePlaceholderText = "Pick one";
                    defaults.ShowTick = true;
                    defaults.MaxSelectionsText = "Too Many ({0} is max!)";
                    defaults.SearchStyle = SearchStyles.StartsWith;
                    defaults.ShowActions = true;
                    defaults.SelectAllText = "All of them";
                    defaults.DeselectAllText = "None of them";
                    defaults.ButtonStyle = ButtonStyles.Success;
                });

Usage

Basic Example

@page "/"

<BootstrapSelect TItem="Country" Data="@countries" TextField="@((item) => item.Name)" 
                 ValueField="@((item) => item.Id.ToString())" TType="string" />

@code {
    private IList<Country> countries;

    protected override void OnInitialized()
    {
        countries = new List<Country> {
            new Country { Id = 1, Name = "United Kingdom" },
            new Country { Id = 2, Name = "United States" },
            new Country { Id = 3, Name = "Germany" },
            new Country { Id = 4, Name = "France" },
            new Country { Id = 5, Name = "China" }
        };
    }

    public class Country
    {
        public int Id { get; set; }

        public string Name { get; set; }
    }
}

Parameters

TItem (Required) - The underlying type of the objects used in the Data collection
TType (Required) - The underlying type of the Value field. Currently supported is: string, int, IEnumerable<string>, IEnumerable<int>
Data (Required) - The Data to use to build the drop down options from
TextField (Required) - The Func to select the Text value from each item within Data
ValueField (Required) - The Func to select the Value value from each item within Data
SubTextField (Optional) - The Func to select the SubText value from each item within Data. SubText is displayed as text-muted.
IconField (Optional) - The Func to select the Icon (css-class) value from each item within Data. Icon is displayed in front of dropdown item.
OptGroupField (Optional) - The Func to select the Opt Group value from each item within Data. If this is supplied, opt groups will be displayed, and its assumed that the Data will be sorted so that all items from the same opt group are positioned together
KeyWordsField (Optional) - The Func to select the Key Words list from each item within Data. If this is supplied, the key words will be included when performing serching
Id (Optional) - Html Id to be added to the element
Value (Optional) - An initial value for the select. Can be used for 2 way binding using @bind-value
ValueChanged (Optional) - An EventCallback to be called when the value changes
IsMultiple (Optional. Default false) - Determines if the select should be a single or multi
ShowSearch (Optional. Default: Uses system wide Defaults) - Determines if the search box should be displayed. When true, adds a search box to the top of the drop down (works in conjunction with ShowSearchThreshold)
ShowSearchThreshold (Optional. Default: Uses system wide Defaults) - The threshold to determine the number of options that must exists before the search box is displayed
DelayValueChangedCallUntilClose (Optional. Default: Uses system wide Defaults) - For multi's only, whether to delay calling ValueChanged until after the select is closed (default will fire after each option is selected/deselected)
SelectedTextFormat (Optional. Default: Uses system wide Defaults) - Specifies how the selection is displayed with a multi select. Values displays a list of the selected options (separated by a ,). Static simply displays the select element's placeholder text. Count displays the total number of selected options. CountGreaterThan behaves like Values until the number of selected options is greater than SelectedTextFormatCount
SelectedTextFormatCount (Optional. Default: Uses system wide Defaults) - If SelectedTextFormat is CountGreaterThan, ths is the number if options that must be selected until the message is displayed
ShowPlaceholder (Optional. Default: Uses system wide Defaults) - For singles only, determines if the placeholder text should be displayed
PlaceholderText (Optional. Default: Uses system wide Defaults) - The placeholder text
Width (Optional) - If supplied, will be used to add a width to the element
CssClass (Optional) - Additional classes to be added to the element
Label (Optional) - A label to added to the element
ValidationFor (Optional) - A Expression to provide the validation information. Can only be used if component is within an EditForm
ShowTick (Optional. Default: Uses system wide Defaults) - Whether to show the checkmark on singles
MaxSelections (Optional) - For multi's only, if supplied, limit the number of options that can be selected
SearchStyle (Optional. Default: Uses system wide Defaults) - When set to SearchStyles.Contains, searching will reveal options that contain the searched text. When set to SearchStyles.StartsWith, searching will reveal options that start with the searched text
ShowActions (Optional. Default: Uses system wide Defaults) - For multi's only. When set, adds two buttons to the top of the dropdown menu (Select All and Deselect All)
ButtonStyle (Optional. Default: Uses system wide Defaults) - The button class to use to style the select button
Disabled (Default: false) - Option for disabling the button dropdown element.

See the code in the index page within samples for more examples

Preview builds and NuGet feed

All official release packages are published to the official and public NuGet feed using the official version number.

Preview builds (builds from the main branch) produce unofficial pre-release packages which can be pulled from the project's NuGet feed on GitHub.

These packages are being versioned using a datetime string (year.month & day.hour &minute - all with leading zeros removed) as the package version.

All other builds, such as builds triggered by pull requests produce a NuGet package which can be downloaded as an artifact from the individual GitHub action using the above versioning.

Contributing

Everyone is welcome to contribute to Blzr.BootstrapSelect. Please take a moment to review the contributing guidelines.

License

Licensed under the MIT license.

Rob-Newman/blzr.bootstrap-select