Flagstrap

A lightwieght jQuery plugin for creating Bootstrap 4 compatible country select boxes with flags.

Usage

Basic

<form class="form-horizontal">
	<div class="form-group">
        <label>Select Country</label><br>
        <div class="flagstrap" data-input-name="country"></div>
    </div>
</form>

<script>
    $('.flagstrap').flagStrap();
</script>

Options

Using Data Attributes

This example will create a Flagstrap Dropdown giving the input field the name of country with all countries available and Germany pre selected and in a scrollable dropdown with max-height of 250px.

<form>
    <div class="form-group">
        <label>Select Country</label><br>
        <div id="flagstrap2"
             data-input-name="country2"
             data-selected-country="DE"
             data-button-size="btn-md"
             data-button-type="btn-default"
             data-scrollable-height="250px"
             data-scrollable="true">
        </div>
    </div>
</form>

<script>
    $('#flagstrap2').flagStrap();
</script>

Using Instance Options

This example will create a Flagstrap Dropdown giving the input field the name of country with only Australia, USA and Canada as available options and no pre selection.

<form class="form-horizontal">
    <div class="form-group">
        <label>Select Country</label><br>
        <div id="flagstrap3"></div>
    </div>
</form>

<script>
    $('#flagstrap3').flagStrap({
        countries: {
            "AU": "Australia",
            "GB": "United Kingdom",
            "US": "United States"
        },
        inputName: 'country',
        buttonSize: "btn-lg",
        buttonType: "btn-primary",
        scrollable: false,
        scrollableHeight: "350px",
        onSelect: function(value, element) {
            //
        },
        placeholder: {
            value: "",
            text: "Please select a country"
        }
    });
</script>

Setting value of widget after creation

You cannot set the value of the widget using the val() method on the underlying select, as this does not notify the plugin of the change.

Passing a string value to the plugin instead of an object will change value of the underlying select and update the UI display. The string passed should be the country code of the country to select.

The example below will take the flagstrap widget created in the example above and change its selected value to the United States.

<script>
    $('#flagstrap3').flagStrap('US');
</script>

Making it searchable

You can probably use any search plugin you like, but here's how you could do it, using https://github.com/stidges/jquery-searchable.

<script>
    $('#flagstrap4').flagStrap({
        searchable: true,
        searchPlaceholder: 'Type to search for countries...',
        searchClass: 'text-light bg-dark',
        onDomReady: function() {
            $('#flagstrap4 ul').searchable({
                selector: 'li',
                childSelector: 'a',
                searchField: '#flagstrap4 input:first',
                searchType: 'default'
            })
        }
    });
</script>

Note: The rendered input element already has the form-control class added.

Options

Name	Type	Default	Description
inputName	string	uniquely generated	the `name` attribute for the actual `select` input
inputId	string	uniquely generated	the `id` attribute for the actual `select` input
buttonSize	string	"btn-md"	The bootstrap button size `class` for this drop down
buttonType	string	"btn-default"	The bootstrap button type `class` for this drop down
scrollable	boolean	false	Scrollable or full height drop down
scrollableHeight	string	"250px"	`max-height` for the scrollable drop down
searchable	boolean	false	Embed an search input element into the button. This element has no search functionality out of the box - you'd have to use an actual search plugin like https://github.com/stidges/jquery-searchable
searchPlaceholder	string	"Search country"	Placeholder text in the search input element.
searchAutoComplete	string	Randomly generated string	Turns OFF autocomplete by setting the search input element autocomplete property to some random string. This is currently the best option for actually disabling autocomplete on an input element - browser support is sketchy at best.
searchClass	string	"FancySearchElement"	Add one or more classes to the search input element.
countries	object	(all)	Only show specific countries Example: {"GB": "United Kingdom", "US": "United States"} will only show the USA and UK.
selectedCountry	string		Set (single) selected country. "GB" or "US" ...
onSelect	function	null	This callback gets called each time the select is changed. It receives two parameters, the new value, and the select element.
onDomReady	function	null	This callback gets called as the last thing, before the plugin returns.
onPostSelect	function	null	This callback gets called as the last thing, after an item in the list is clicked.
placeholder	bool|object	{value: "", text: "Please select a country"}	Set the placeholder value and text. To disable the placeholder define as (boolean) false.

Contributors

This project was created by Alex Carter. I owe many thanks to the following people who have helped make flagstrap even better.

• Matthew Machuga
• TJ Miller
• Mads Jensen