v2.5.12
Select single or multiple values from a list.
This Select component is an improvement on our Dropdown component and offers more stripped down options with a nicer look. If you
are currently using the Dropdown component in your forms for basic user input collection, you can simply replace x-bladewind.dropdown
with x-bladewind::select and everything will work fine.
The data attribute is what really drives the BladewindUI select component.
This attribute expects an array to be passed to it. Let's look at the basic structure of such an array using a list of five countries.
We will build on this array structure as we go further in this documentation.
<?php
$countries = [
[ 'label' => 'Benin', 'value' => 'bj' ],
[ 'label' => 'Burkina Faso', 'value' => 'bf' ],
[ 'label' => 'Ghana', 'value' => 'gh' ],
[ 'label' => 'Nigeria', 'value' => 'ng' ],
[ 'label' => 'Kenya', 'value' => 'ke' ]
];
This structure is all you need to render a BladewindUI select.
The default array keys used to render the select are label and value.
<x-bladewind::select
name="country"
:data="$countries" />
data to the component. Note there is no colon before the data attribute and in this case the data is passed as a json encoded string.
<x-bladewind::select
name="country"
data="{{ json_encode($countries) }}" />
<x-bladewind::select
name="country2"
placeholder="What is your nationality"
:data="$countries" />
Of course it is not feasible to always rewrite your arrays to use the value and label keys expected by the component. There is a solution.
Assuming we changed our array to the structure below.
<?php
$countries = [
[ 'country' => 'Benin', 'code' => 'bj' ],
[ 'country' => 'Burkina Faso', 'code' => 'bf' ],
[ 'country' => 'Ghana', 'code' => 'gh' ],
[ 'country' => 'Nigeria', 'code' => 'ng' ],
[ 'country' => 'Kenya', 'code' => 'ke' ]
];
We changed our array keys from label and value to country and code. To render the select now, you just need to set the label_key and value_key attributes.
Using our array above we will end up with label_key="country" and value_key="code".
<x-bladewind::select
name="country_mixed"
label_key="country"
value_key="code"
:data="$countries" />
Just for some perspective, what we are trying to mimic here is the html implementation of a select form element.
<select name="country"...>
<option value="gh">Ghana</option>
</select>
Like with the regular HTML <select> field, it is possible to have an item selected by default when the page loads. Useful when editing records.
<x-bladewind::select
name="country-select"
selected_value="gh"
placeholder="What is your nationality"
:data="$countries" />
Setting a select as required appends a red asterisk to the placeholder text.
<x-bladewind::select
name="country-select2"
required="true"
placeholder="What is your nationality"
:data="$countries" />
A disabled select has a 50% opacity and a cursor indicating the field cannot be accessed.
<x-bladewind::select
name="country-dis"
disabled="true"
placeholder="What is your nationality"
:data="$countries" />
A readonly select is quite visible but cannot be opened to view the list of items.
<x-bladewind::select
name="country-ro"
readonly="true"
placeholder="What is your nationality"
:data="$countries" />
This is just a simple way for users who are displaying list of countries to display flags next to each country name.
This implementation was ported from Semantic UI library's flags feature.
Flags are rendered using the country's ISO code. Example: Ghana has an ISO code of GH. Nigeria has an ISO code of NG.
You will need to specify the flag_key attribute on the select. This should be the name of the key in your array that has the country codes.
Still working with our $countries array from above, our select code will now be
<x-bladewind::select
name="country"
label_key="country"
value_key="code"
flag_key="code"
:data="$countries" />
<link href="{{ asset('vendor/bladewind/css/flags.css') }}" rel="stylesheet" />
You may wish to include images in your select list. For example, your app allows you to assign tasks to employees. You may want your employee list to have the pictures of each person next to their name.
You will need to specify the image_key attribute on the select. This should be the name of the key in your array that has the image urls.
Let us create a new array of employees with the needed information.
<?php
$staff =
[
[
'id' => '1001',
'name' => 'Adam Nsiah',
'picture' => '/path/to/the/image/file'
],
[
'id' => '1005',
'name' => 'Alfred Rowe',
'picture' => '/path/to/the/image/file'
],
[
'id' => '1002',
'name' => 'Abdul Razak Ibrahim',
'picture' => '/path/to/the/image/file'
],
[
'id' => '1003',
'name' => 'Michael K. Ocansey',
'picture' => '/path/to/the/image/file'
],
[
'id' => '1004',
'name' => 'Michael Sarpong',
'picture' => '/path/to/the/image/file'
],
]
<x-bladewind::select
name="staff"
placeholder="Assign task to"
label_key="name"
value_key="id"
image_key="picture"
:data="$staff" />
Assuming we had a very long list of items in our select, say all countries of the world, or list of employees, it will be tedious to scroll down the list to find what you are looking for.
Set the following attribute searchable="true" to make the Select component searchable. This is turned off by default.
Let's now increase our list of countries from five to ten. The new array will be:
<?php
$countries = [
[ 'country' => 'Benin', 'code' => 'bj' ],
[ 'country' => 'Burkina Faso', 'code' => 'bf' ],
[ 'country' => 'Cameroon', 'code' => 'cm' ],
[ 'country' => 'Congo', 'code' => 'cd' ],
[ 'country' => 'Gambia', 'code' => 'gm' ],
[ 'country' => 'Ghana', 'code' => 'gh' ],
[ 'country' => 'Ivory Coast', 'code' => 'ci' ],
[ 'country' => 'Nigeria', 'code' => 'ng' ],
[ 'country' => 'Kenya', 'code' => 'ke' ]
[ 'country' => 'Togo', 'code' => 'tg' ],
];
<x-bladewind::select
name="country4"
searchable="true"
label_key="country"
value_key="code"
flag_key="code"
:data="$countries" />
There are instances where you need to select more than one item from the select component. This is possible by setting the attribute
multiple="true". Unlike the single select, multiple selects do not automatically close when you select items.
This is because we technically do not know how many items you are selecting and if you are done.
To close a multiple select just click anywhere on the page outside the component.
Left and right navigation arrows are displayed only when some of the selected items are out of view. You can ignore the arrows and scroll left and right using your mouse. This will be a 2 finger scroll on Macs.
<x-bladewind::select
name="country-multi"
searchable="true"
label_key="country"
value_key="code"
flag_key="code"
multiple="true"
max_selectable="3"
:data="$countries" />
If you try to select more than 3 items from the select component above, you will not be able to.
This is achieved by setting the
max_selectable attribute. The default value is -1, which means there is no limit on selection.
Once you set a positive integer, the restriction on selection will be applied. You can set what error message should be displayed when the user tries to select more than is allowed.
You can set the max_error_message attribute.
You can auto select some of the items in the component by default, for example when in edit mode. To select multiple items, you will need to specify them as a comma separated list.
<x-bladewind::select
name="country-multi2"
searchable="true"
selected_value="gh, gm, ci, bf"
label_key="country"
value_key="code"
flag_key="code"
multiple="true"
:data="$countries" />
There could be cases when your data will not come from an API call or array. You may want to manually build the Select options. Say for gender, you simply want 3 options. Male, female, other. It is possible to make these items into an array but honestly array-ing simple things like this can get tedious --fast. The Select component has a child component that allows you to do this.
Let us consider the example below. The important trade-off here is to set data="manual".
<x-bladewind::select name="gender" placeholder="Select Gender" data="manual">
<x-bladewind::select-item label="Male" value="male" />
<x-bladewind::select-item label="Female" value="female" />
<x-bladewind::select-item label="Prefer not to say" value="other" />
</x-bladewind::select>
The manual Select can inherit all the cool features of an array-based Select. Can be searchable or even multiple selection.
<x-bladewind::select
name="tags"
placeholder="Tags for this music"
multiple="true"
searchable="true" data="manual">
<x-bladewind::select-item label="Pop" value="pop" image="/path/to/image" />
<x-bladewind::select-item label="Hip" value="hip" flag="gh" />
<x-bladewind::select-item label="Trendy" value="trendy" flag="ng" />
<x-bladewind::select-item label="GenZ" value="genz" image="/path/to/image" />
<x-bladewind::select-item label="Trance" value="trance" />
<x-bladewind::select-item label="For Coder's" value="devs" />
</x-bladewind::select>
The example above allows for multiple selection of items, it's searchable and mixes flags and images, just to show you that all features are possible even when manually building the Select items.
Every BladewindUI select component you display creates as part of the select html the following hidden form field
<input type="hidden" name="the-select-name-you-provided" />. When you select an item from the select, the hidden input field is updated with the value of what you selected. The value will be whatever you specified as your value_key. When you submit a form that has any BladewindUI select, you can access the value of the select by specifying the name you used on the select. Consider the example below.
<form ...>
...
<x-bladewind::select name="country" ... />
</form>
After submitting the form the value of the country select can be accessed using any of the following ways permitted in Laravel.
$request->get('country');
$request->input('country');
$request->country;
<input type="hidden" name="country_multi" value="gh,ci,bf,gm" />
It is possible to execute a JavaScript custom function when an item is selected.
The custom function is executed in addition to the default BladewindUI action of writing the selected value to a hidden field. Building on our countries example above, let's say you want to prepend a mobile number field with the dialing code
of the selected country. This can be done via a custom function. You can define a custom function by setting onselect="function_name".
You only need to specify the name of the function without parenthesis and parameters. Example: onselect="prependDialingCode".
The value and label of the selected item are passed to the custom function and executed like so: onselect="prependDialingCode(value, label, all_values)".
The third parameter all_values is useful when you are expecting multiple values to be selected. All the selected values are passed as a comma separated list.
Your function therefore needs to be defined with three parameters (if you intend to use all three). Let's consider a more detailed example below (where we only make use of the value parameter).
<div class="grid grid-cols-2 gap-4">
<x-bladewind::select
name="cusfxns"
placeholder="Your country"
data="manual"
onselect="prependDialingCode">
<x-bladewind::select-item label="Burkina Faso" value="bf" />
<x-bladewind::select-item label="Ghana" value="gh" />
<x-bladewind::select-item label="Nigeria" value="ng" />
</x-bladewind::select>
<x-bladewind::input
name="mobile"
numeric="true"
prefix="+xxx"
suffix="device-phone-mobile"
suffix_is_icon="true"
transparent_prefix="false"
placeholder="Mobile" />
</div>
// javascript
const dialing_codes = {
'gh' : '+233',
'ng' : '+234',
'bf' : '+226'
}
prependDialingCode = (value) => {
domEl('.mobile-prefix').innerText = eval(`dialing_codes.${value}`);
}
The input field above has name="mobile" and also has a prefix="+xxx".
Bladewind names all prefixes after their input element so, the prefix field in the mobile input will have class="mobile-prefix". Even though
Bladewind passes both 'value' and 'label' to custom functions specified on Selects, in this example the prependDialingCode
function only accepts 'value' because the 'label' is not needed.
There are those moments when you need to interact with a Select component from JavaScript. The Bladewind Select component exposes 3 methods that help you to do just that. When you create a Select component and provide a name, BladewindUI initializes the component in JavaScript using the name you provided.
// the following component declaration
<x-bladewind::select name="country-multiple" placeholder="Select a country" />
// will be initialized in JavaScript as
const bw_country_multiple = new BladewindSelect('country_multiple', 'Select a country');
Note how the name passed to the component has been prefixed with bw_
and all dashes '-' replaced with underscores '_'. This variable is now accessible to you in JavaScript and represents the Select component.
The following methods can be performed on the Select component now, from JavaScript...
| Method | Description |
|---|---|
| enable | Enables the select and makes it clickable. bw_country_multiple.enable(); |
| disable | Disables the select and makes it non-clickable. There is a known issue with this when used on multiple select components that already have values selected. The user can click on the close icons next to the selected values to remove them.
bw_country_multiple.disable(); |
| reset | Removes any selected values from the component. This also empties the hidden input field associated with the component.
bw_country_multiple.reset(); |
| selectByValue(value) | Select one of the component values. The value you pass needs to exist in the Select's list of items else the command will simply be ignored.
This does not work for multiple values yet. You can use it on a mutiple select to select multiple values but you will need to call the method multiple times.
bw_country_multiple::selectByValue('gh');
bw_country_multiple::selectByValue('ng');
|
| filter(element, value) | Filter the items in <element> based on <value>. element is the name of the target select component to be filtered. By default, one select component triggers filtering on another select component.
However, a component can trigger filtering on itself if the value is not coming from another select component.
bw_continents.filter('countries', 'AF');
bw_countries.filter('countries', 'EU');
|
| clearFilter(element, value) | Clear all filtering in <element> based on <value>. The component is reset if <value> is blank.
bw_continents.clearFilter('countries', 'AF');
bw_countries.clearFilter('countries');
|
<x-bladewind::select name="from-js" placeholder="Your country" data="manual">
<x-bladewind::select-item label="Burkina Faso" value="bf" />
<x-bladewind::select-item label="Ghana" value="gh" />
<x-bladewind::select-item label="Nigeria" value="ng" />
</x-bladewind::select>
<div class="space-x-4 text-center">
<x-bladewind.button size="small" type="secondary"
onclick="bw_from_js::selectByValue('gh')">
Select Ghana
</x-bladewind.button>
<x-bladewind.button size="small" type="secondary"
onclick="bw_from_js::selectByValue('ng')">
Select Nigeria
</x-bladewind.button>
<x-bladewind.button size="small" type="secondary"
onclick="bw_from_js.disable()">
Disable
</x-bladewind.button>
<x-bladewind.button size="small" type="secondary"
onclick="bw_from_js.reset()">
Reset
</x-bladewind.button>
<x-bladewind.button size="small" type="secondary"
onclick="bw_from_js.enable()">
Enable
</x-bladewind.button>
</div>
In this next example (inspired by this comment) we will filter an employee directory based on what departments are selected in the multi select component. Each employee card in the employee directory below is generated using the BladewindUI Contact card component.
Let's break down the code for the example above. First we build the array of employees. This example uses an array. You may have your data coming directly from the database or other.
$employees = [
[
'name' => 'Michael Ocansey',
'email' => 'mike@demo.com',
'position' => 'CTO',
'department' => 'tech',
'dp' => 'me.jpeg',
'mobile' => '+233244123456'
],
...
];
Next, we build our multiple Select component with non-dynamic data.
Note line 3 where we pass the name of the function responsible for filtering the data to the onselect attribute.
<x-bladewind::select
name="department"
onselect="filterEmployees"
placeholder="filter by department"
data="manual"
multiple="true">
<x-bladewind::select-item label="Field Workers" value="field" />
<x-bladewind::select-item label="Finance" value="finance" />
<x-bladewind::select-item label="Tech" value="tech" />
<x-bladewind::select-item label="Marketing" value="marketing" />
<x-bladewind::select-item label="Operations" value="operations" />
</x-bladewind::select>
We then build the employee records from our array. This example uses the contact card component, but you could use the table component to achieve the same results. How the data is displayed is completely up to you.
<div class="grid grid-cols-2 gap-4">
@foreach($employees as $employee)
@php
$dp = ($employee['dp']!=='') ? "/assets/images/".$employee['dp'] : '';
$position = ucfirst($employee['department']) . ' > ' . $employee['position'];
@endphp
<x-bladewind::contact-card
:name="$employee['name']"
:position="$position"
:email="$employee['email']"
:mobile="$employee['mobile']"
:image="$dp" />
@endforeach
</div>
Finally, the Javascript for filtering the cards. Every BladewindUI contact card component has the class bw-contact-card.
Our Javascript targets this class to access all employee cards. When a department is selected, we search through each card
and hide any cards that do not contain the selected department(s) in their innerText. Because multiple departments can be selected,
we need to dynamically build our regular expression for finding the selected departments in the cards.
filterEmployees = (value, label, all_values) => {
// get all employee cards available in the DOM
let employee_cards = domEls('.bw-contact-card');
// replace every , with | so our regex will look like /(tech|finance)/ig
let keywords = all_values.replaceAll(',','|');
let regex = new RegExp( `(${keywords})`, 'ig' );
// go through each card and hide any that doesn't match selection
employee_cards.forEach((el) => {
(! el.innerText.match(regex) ) ? hide(el, true) : unhide(el, true);
});
}
Let's dig right into an example. Let's say you have two select components, continents and countries. You want to display a list of countries based on which continent was selected. The Select component provides an easy way to handle this kind of filtering, without having to whip up your own Javascript logic.
To make this possible we will need to introduce two new attributes. filter and filter_by.
Let us take a look at the code. We start by defining the array that will populate the continents select component.
// this array populates the country dropdown.
// all countries in this array are displayed when no continent is selected
$countries = [
[ 'name' => 'Ghana', 'value' => 'gh', 'continent_code' => 'af' ],
[ 'name' => 'Nigeria', 'value' => 'ng', 'continent_code' => 'af' ],
[ 'name' => 'Kenya', 'value' => 'ke', 'continent_code' => 'af' ],
[ 'name' => 'China', 'value' => 'ch', 'continent_code' => 'as' ],
[ 'name' => 'Thailand', 'value' => 'th', 'continent_code' => 'as' ],
[ 'name' => 'Japan', 'value' => 'jp', 'continent_code' => 'as' ],
[ 'name' => 'Canada', 'value' => 'ca', 'continent_code' => 'na' ],
[ 'name' => 'Jamaica', 'value' => 'jm', 'continent_code' => 'na' ],
[ 'name' => 'Honduras', 'value' => 'hn', 'continent_code' => 'na' ],
[ 'name' => 'Netherlands', 'value' => 'nd', 'continent_code' => 'eu' ],
[ 'name' => 'Norway', 'value' => 'nw', 'continent_code' => 'eu' ],
[ 'name' => 'Poland', 'value' => 'pl', 'continent_code' => 'eu' ],
];
Next is the continents select component. This time we used a manual select instead of generating this from an array because it is just a list of 4 continents.
Take note however, of the filter="continent-country" attribute. continent-country is the name of the select component we want to filter.
<!--- the continents select component. --->
<x-bladewind::select name="continent" placeholder="Select Continent"
filter="continent-country"
data="manual">
<x-bladewind::select-item label=Africa" value="af" />
<x-bladewind::select-item label="Asia" value="as" />
<x-bladewind::select-item label="Europe" value="eu" />
<x-bladewind::select-item label="North America" value="na" />
</x-bladewind::select>
Next we introduced filter_by="continent_code" when creating our continent-country select component.
When this attribute is defined, all BladewindUI does is to add a data-filter-value attribute to the HTML generated for the Select component's items.
Whatever value is defined for filter_by must exist as a key in the data you are populating the component with.
You can tell from our example array above, there is a key called continent_code.
The items in the continents select component have values that match continent_code.
For example the line for Africa has a value of af. Selecting this will filter the countries select component and keep all items whose continent_code match af.
<!--- the countries select component. --->
<x-bladewind::select
name="continent-country"
placeholder="Select Country"
searchable="true"
data="json_encode($countries)"
filter_by="continent_code"
label_key="name"
value_key="name">
The earlier example filtered our countries select component based on which continent was selected from our continent's select component.
You may not always want your filtering to be based on a value from one select component but probably just some arbitrary value passed from a link, button or other component.
The select component exposes a filter() method that allows for runtime filtering.
In this example, clicking on a tag filters the list of countries. This is achieved by calling the filter() method on the target select component. Each tag calls a
filterCountries() Javascript function, passing the value of the continent as the parameter. Africa for example passes the parameter af as filterCountries('af').
<div class="bg-slate-100 sm:grid sm:grid-cols-2 gap-6 flex items-center">
<div class="space-x-2">
<a href="javascript:filterCountries('af')">
<x-bladewind::tag label="africa" color="purple" class="cursor-pointer" />
</a>
<a href="javascript:filterCountries('as')">
<x-bladewind::tag label="asia" color="purple" class="cursor-pointer" />
</a>
...
</div>
<x-bladewind::select
name="continent-country2"
placeholder="Select Country"
searchable="true"
data="json_encode($countries)"
label_key="name"
value_key="value"
filter_by="continent_code" />
</div>
Below is the script called by the tags. Note line 3 where we call the filter() function on the continent-country2 select component.
We need to prefix the component name with bw_ and also change all dashes in the component name to underscores. continent-country2 becomes continent_country2.
Replacing dashes with underscores is not required if you already named your select component with underscores.
Also note how in this case we called the filter() on the same component that we are targeting. This is because we are not triggering the filtering from another select component.
<script>
filterCountries = (continent) => {
// this is where we actually tell the component to filter
bw_continent_country2.filter('continent_country2', continent);
}
</script>
It is possible to use the plain old HTML <select> element and apply the BladewindUI bw-raw-select class to change the style to look just like all the other BladewindUI form components.
This option has no searchability and does only what the HTML select element is capable of doing.
<select name="age" class="bw-raw-select">
<option value="">Are you above 18?</option>
<option value="yes">Yep! I am</option>
<option value="no">Nope but tell no one</option>
<option value="idk">I'd rather not say</option>
</select>
The table below shows a comprehensive list of all the attributes available for the Dropdown component.
| Option | Default | Available Values |
|---|---|---|
| name | bw-select | This name is assigned to the hidden input created for the select. The name is then accessed when the select is submitted in a form. |
| placeholder | Select One | Default text displayed on the select |
| onselect | blank | Custom function to call when an item in the select is selected. This should just be the name of the custom function, without parenthesis. For example assignToProject.
The component appends the selected value and label to the function call as assignToProject(value, label) |
| :data | [] | Array of elements to be displayed in the component. This should be an array. See above examples. Ignore this attribute if you prefer to use data instead. |
| data | [] | Json encoded array of elements to be displayed in the component. Ignore this attribute if you prefer to use :data instead.. |
| value_key | value | Which key in your array should the select pick its values from. |
| label_key | label | Which key in your array should the select pick its values from. |
| flag_key | blank | When using the select with flags, which key in your array should the select pick the country ISO codes from. Flags are only rendered using the countries ISO codes. |
| image_key | blank | When using the select with images, which key in your array should the select pick its images from. |
| data_serialize_as | blank | This is better explained with an example. In a form your select has name="country". When the form is submitted the select's value can be accessed as $request->country.
If for some reason you want your select to have its name but pass its value with a different name, set data_serialize_as. Picking up on the example, if we set, data_serialize_as="country_name", when the form is submitted
we can access the value of the select as $request->country_name.
|
| required | false | Determines if an asterisk should be appended to the placeholder text to indicate the field is required. true false. |
| selected_value | blank | Determines which value from the array should be selected by default when the select loads. Useful when editing content. If you want an item in your array whose value=13 to be selected, set selected_value="13".
You can also set multiple values to be selected selected_value="to do, in progress, done" |
| searchable | false | Makes the select either searchable or not. A search box is placed above the select items when set to true. true false. |
| disabled | false | Specifies if select should be disabled or not.true false. |
| readonly | false | Specifies if select should be readonly or not.true false. |
| multiple | false | Specifies if multiple items can be selected.true false. |
| add_clearing | true | Specifies if a 12px margin should be applied to the bottom of the select for spacing. Useful in forms. All BladewindUI form elements have this for uniformity.true false. |
| max_selectable | -1 | What is the maximum number of items that can be selected. -1 means no maximum. This is only applied when multiple="true" positive integers |
| max_error | Please select only %s items | Message to display if user tries to select more than is allowed by truemax_selectable. %s is replaced with the number specified in max_selectable |
| filter | blank | The name of the select component that needs to be filtered. See above example. |
| filter_by | blank | Which key in the target select component's data, should be used in filtering its items. |
| modular | false | Determines if script tags sued within the component should have type="module". Useful sometimes when working with Vite js.
true true
|
When manually listing select items, the following attributes are available
| Option | Default | Available Values |
|---|---|---|
| value | value | Value of the item. |
| label | label | Label of the item. |
| flag | blank | ISO code of country whose flag to display. |
| image | blank | URL of image to display for the item. |
| selected | false | Determines if the item should be selected or not. true false |
| max_selectable | -1 | What is the maximum number of items that can be selected. -1 means no maximum. positive integers |
| max_error | Please select only %s items | Message to display is user tries to select more than is allowed by truemax_selectable. %s is replaced with the number specified in max_selectable |
<x-bladewind::select
name="country"
placeholder="What is your nationality"
onselect="confirmSelection"
data="{{ json_encode($countries)}} "
value_key="code"
label_key="country"
flag_key="code"
image_key=""
disabled="false"
readonly="true"
data_serialize_as="country_id"
required="true"
selected_value="1001"
max_selectable="3"
searchable="true"
filter="countries",
filter_by="continent_id"
/>
resources > views > components > bladewind > select.blade.phppublic/vendor/bladewind/assets/js/select.js