Modal select for Ionic Framework based on $ionicModal
See all docs and examples on the project site.
We also have a simple Codepen demo.
- supports long list of object via collection-repeat
- optional search bar
- supports unsetting the chosen value (optional)
- customizable modal classes, modal header and footer classes
- customizable buttons text
Get the files from github or install from bower:
bower install ionic-modal-select
Include ionic-modal-select.js
or its minified version in your index.html:
<script src="lib/ionic-modal-select/ionic-modal-select.js"></script>
Add the module ionic-modal-select
to your application dependencies:
angular.module('starter', ['ionic', 'ionic-modal-select'])
And you're ready to go.
This directive will transform the element into a modal select: when clicking the element a select dialog will be open, with options presented in a clickable list. Once the user clicks on an option, it will be set on the bound model.
For this to work the following conditions must apply:
- The element you use this directive must be clickable.
- The directive requires ngModel to be set on the element
- The directive expects an inner element of class "option" to define the options template
The final value bound to your model will be determined as follow:
- if you set the attribute
option-getter
will be set asgetterFunction(selectedItem)
- if you set the attribute
option-property
will be set asselectedItem[propertyName]
- otherwise it will be set as the full object
option | meaning | accepted values | default |
---|---|---|---|
options |
List of options to choose from | Array | |
options-expression |
The expression indicating how to enumerate a the options collection, of the format variable in expression – where variable is the user defined loop variable and expression is a scope expression giving the collection to enumerate. For example: `album in artist.albums or album in artist.albums |
orderBy:'name'`. | expression |
option-getter |
Optional method to get the value from the chosen item | function | not set |
option-property |
Optional property name to get as model value from the chosen item | string | not set |
modal-class |
The class for the modal (set on <ion-modal-view> |
string | '' |
selected-class |
The class applied to the currently selected option (if any) in the modal list | string | 'option-selected' |
on-select |
Callback triggered on object select. Takes two arguments, newValue and oldValue with obvious meaning. |
function call with arguments newValue and oldValue |
not set |
on-reset |
Callback triggered when value is resetted using the relevant ui interface. Takes no arguments. | function call | not set |
modal-title |
The title shown on the modal header | string | 'Select an option' |
header-footer-class |
The class for header and footer of the modal | string | 'bar-stable' |
cancel-button |
Text of the button for closing the modal without changing the value | string | 'Cancel' |
reset-button |
Text of the button for unsetting value in the modal dialog | string | 'Reset' |
hide-reset |
Hides the button for unsetting value in the modal dialog | string. Set to 'true' for hiding the button | false |
use-collection-repeat |
Forces use of collection-repeat or ng-repeat for rendering options in the modal. | string "true", "false" | not set (automatically set according to number of options and short-list-break attribute) |
short-list-break |
The maximum number of item in list to be rendered with ng-repeat .(if use-collection-repeat is not set) If the list has a number of options greater than this attribute it will be rendered with ionic collection-repeat directive instead. (see also load-list-message option) |
integer | 10 |
load-list-message |
Message to be shown when loading a long list of options in the modal | string | 'Loading' |
has-search |
Whether to show a search bar to filter options. | set to "true" for showing the search bar | undefined |
sub-header-class |
Class to be applied to the subheader containing the search bar (makes sense only if has-search="true ) |
string | 'bar-stable' |
cancel-search-button |
Text for the button for clearing search text (makes sense only if has-search="true ) |
string | 'Clear' |
clear-search-on-select |
Tells the directive to not clear the search bar content after user selection. Set to false to prevent clearing the search text. |
boolean | true |
The modal-select
directive must be provided with a set of options to choose from
This can be done in two ways:
- via the
options
attribute, that accepts an array of values or objects. The directive will watch for changes in this array and modify its options accordingly. - via the
options-expression
attribute, that accepts an expression similar to what you would use with ioniccollection-repeat
directive, of the formatvariable in expression
– where variable is the user defined loop variable and expression is a scope expression giving the collection to enumerate. For example:album in artist.albums or album in artist.albums | orderBy:'name'
. This allows you to apply ordering or filtering without acting on the original array.
This directive expects to find a single inner element of class "option" that is used to define the template of the options that can be selected. Options will be rendered as items into a list in the modal (The content of each option, rendered with your template, is wrapped in an element of class 'item item-text wrap' and the original ".option" element is removed).
For example:
<button class="button button-positive" modal-select ng-model="someModel" options="selectables" modal-title="Select a number">
Select it
<div class="option">
{{option}}
</div>
</button>
Will be rendered in the modal as :
<div class="item item-text-wrap">
{{option}}
</div>
From version 1.1.0 you can include a search bar into the modal for filtering options by simply adding the attribute has-search="true"
to your modal-select
element.
Filtering is implemented with the angular filter
filter, which searches recursively in all properties of the objects passed in as options. This means that you cannot search on "computed properties" right now. For example if you are using a custom setter you will be only able to search the original properties of the options.
### Examples
This example shows a modal for choosing a number between 1 and 5.
In your controller:
$scope.selectables = [1,2,3,4,5];
In your template:
<button class="button button-positive" modal-select ng-model="someModel" options="selectables" modal-title="Select a number">
Select it
<div class="option">
{{option}}
</div>
</button>
To include a search bar in the previous example, just add has-search="true"
:
<button class="button button-positive" modal-select ng-model="someModel" options="selectables" modal-title="Select a number" has-search="true">
Select it
<div class="option">
{{option}}
</div>
</button>
In the following example we use some objects as options.
In your controller:
$scope.selectables = [
{ name: "Mauro", role : "navigator"},
{ name: "Silvia", role : "chef"},
{ name: "Merlino", role : "canaglia"}
];
We'll explore different possibilities we have with this options.
If we do not set option-getter
or option-property
attributes, the model is assigned to the full option object when an option is selected.
<button class="button button-positive" modal-select ng-model="someModel" options="selectables" modal-title="Select a character">
Select it
<div class="option">
{{option.name}} ({{option.role}})
</div>
</button>
If option-property
attribute is set to a string, the bound model assigned that property of the option object when an option is selected. For example if we set option-getter="name"
, we get back the 'name' property of our options.
<button class="button button-positive" modal-select ng-model="someModel" options="selectables" modal-title="Select a character" option-property="name">
Select it
<div class="option">
{{option.name}} ({{option.role}})
</div>
</button>
If a function call is passed via option-getter
attribute, the bound model assignment is done by calling this function with the selected option as the only argument (named 'option'). For example if we do this in our controller:
$scope.getOption = function(option){
return option.name + ":" + option.role;
};
<button class="button button-positive" modal-select ng-model="someModel" options="selectables" modal-title="Select a character" option-getter="getOption(option)">
Select it
<div class="option">
{{option.name}} ({{option.role}})
</div>
</button>
We get back the phrase "Mauro:navigator", "Silvia:chef" or "Merlino:canaglia" if we click the previous defined options.
More examples on the project site.
This software package is available for free with a MIT license, but if you find it useful and want support its development consider buying a copy on the Ionic Marketplace for just a few bucks.