Picker
Picker is a powerful component that allows you to create custom overlay pickers which looks like iOS native picker.
Picker could be used as inline component or as overlay. Overlay Picker will be automatically converted to Popover on tablets (iPad).
Picker App Methods
Let’s look at related App methods to work with Picker:
app.picker.create(parameters)- create Picker instance
- parameters - object. Object with picker parameters
Method returns created Picker’s instance
app.picker.destroy(el)- destroy Picker instance
- el - HTMLElement or string (with CSS Selector) or object. Picker element or Picker instance to destroy.
app.picker.get(el)- get Picker instance by HTML element
- el - HTMLElement or string (with CSS Selector). Picker element.
Method returns Picker’s instance
app.picker.close(el)- close Picker
- el - HTMLElement or string (with CSS Selector). Picker element to close.
Method returns Picker’s instance
For example:
var picker = app.picker.create({
inputEl: '#picker-input',
cols: [
{
values: ['apple', 'orange', 'banana'],
displayValues: ['Apple', 'Orange', 'Banana'],
}
]
});
Picker Parameters
Let’s look on list of all available Picker parameters:
Parameter | Type | Default | Description |
---|---|---|---|
rotateEffect | boolean | false | Enables 3D rotate effect |
momentumRatio | number | 7 | Larger values produces more momentum when you release picker after fast touch and move |
mousewheel | boolean | true | Enables ability to scroll through picker values with mousewheel |
updateValuesOnMomentum | boolean | false | Updates picker and input values during momentum |
updateValuesOnTouchmove | boolean | true | Updates picker and input values during touch move |
updateValuesOnMousewheel | boolean | true | Updates picker and input values during mousewheel scrolling |
freeMode | boolean | false | Disables snapping on values |
value | array | Array with initial values. Each array item represents value of related column | |
formatValue | function (values, displayValues) | Function to format input value, should return new/formatted string value. values and displayValues are arrays where each item represents value/display value of related column | |
cols | array | Array with columns. Each array item represents object with column parameters | |
Container/opener-specific parameters | |||
containerEl | string HTMLElement | String with CSS selector or HTMLElement where to place generated Picker HTML. Use only for inline picker | |
openIn | string | auto | Can be auto , popover (to open picker in popover), sheet (to open in sheet modal). In case of auto will open in sheet modal on small screens and in popover on large screens. |
backdrop | boolean | Enables backdrop for Picker container (Popover or Sheet) (dark semi transparent layer behind). By default it uses default value based on how it is opened (in Sheet or Popover). | |
sheetPush | boolean | false | Enables Picker sheet to push view/s behind on open |
sheetSwipeToClose | boolean | false | Enables ability to close Picker sheet with swipe |
inputEl | string or HTMLElement | String with CSS selector or HTMLElement with related input element | |
scrollToInput | boolean | true | Scroll viewport (page-content) to input when picker opened |
inputReadOnly | boolean | true | Sets “readonly” attribute on specified input |
cssClass | string | Additional CSS class name to be set on picker element | |
closeByOutsideClick | boolean | true | If enabled, picker will be closed by clicking outside of picker or related input element |
toolbar | boolean | true | Enables picker toolbar |
toolbarCloseText | string | Done | Text for Done/Close toolbar button |
routableModals | boolean | true | Will add opened picker to router history which gives ability to close picker by going back in router history and set current route to the picker modal |
url | string | select/ | Picker modal URL that will be set as a current route |
view | object | View where to set routing when routableModals enabled. Defaults to parent view of inputEl or main view if not found parent view | |
Render Functions | |||
renderToolbar | function | Function to render toolbar. Must return toolbar HTML string | |
render | function | Function to render whole picker. Must return picker full HTML string | |
Events | |||
on | object | Object with events handlers. For example:
|
Note that all following parameters can be used in global app parameters under picker
property to set defaults for all pickers. For example:
var app = new Framework7({
picker: {
rotateEffect: true,
openIn: 'popover',
}
});
Column Parameters
When we configure Picker we need to pass cols
parameter. It is an array where each item is an object with column parameters:
Parameter | Type | Default | Description |
---|---|---|---|
values | array | Array with string columns values | |
displayValues | array | Array with string columns values that will be displayed in Picker. If not specified, it will display values from values parameter | |
cssClass | string | Additional CSS class name to be set on column HTML container | |
textAlign | string | Text alignment of column values, could be “left”, “center” or “right” | |
width | number | Column width in px. Useful if you need to fix column widths in picker with dependent columns. By default, calculated automatically | |
divider | boolean | false | Defines column that should be used as a visual divider, that doesn’t have any values |
content | string | Should be specified for divider-column (divider:true ) with content of the column | |
onChange | function(picker, value, displayValue) | Callback function that will be executed when picker value changed. |
Picker Methods & Properties
After we initialize Picker we have its initialized instance in variable (like picker
variable in examples above) with helpful methods and properties:
Properties | |
---|---|
picker.app | Link to global app instance |
picker.containerEl | Picker wrapping container HTML element (when inline picker is in use) |
picker.$containerEl | Dom7 instance with picker wrapping container HTML element (when inline picker is in use) |
picker.el | Picker HTML element |
picker.$el | Dom7 instance with picker HTML element |
picker.inputEl | Picker input HTML element (passed in inputEl parameter) |
picker.$inputEl | Dom7 instance with picker input HTML element (passed in inputEl parameter) |
picker.value | Array where each item represents current selected value for each column |
picker.cols | Array with specified Picker columns. Each column also has its own methods and properties (look below) |
picker.opened | true if Picker is currently opened |
picker.inline | true when inline picker is in use |
picker.url | Picker URL (that was passed in url parameter) |
picker.view | Picker View (that was passed in view parameter) or found parent view |
picker.params | Object with initialization parameters |
Methods | |
picker.setValue(values, duration) | Set new picker value. values is array where each item represents value for each column. duration - transition duration in ms |
picker.getValue() | Returns current picker value |
picker.addValue() | Adds value to the values array. Useful in case if multiple selection is enabled (with multiple: true parameter) |
picker.open() | Open Picker |
picker.close() | Close Picker |
picker.destroy() | Destroy Picker instance and remove all events |
picker.on(event, handler) | Add event handler |
picker.once(event, handler) | Add event handler that will be removed after it was fired |
picker.off(event, handler) | Remove event handler |
picker.off(event) | Remove all handlers for specified event |
picker.emit(event, …args) | Fire event on instance |
Column Methods & Properties
Each column in picker.cols
array also has its own useful methods and properties.
//Get first column
var col = picker.cols[0];
Properties | |
---|---|
col.el | Column HTML element |
col.$el | Dom7 instance with column HTML container |
col.items | Dom7 instance with column items HTML elements |
col.value | Currently selected column value |
col.displayValue | Currently selected column display value |
col.activeIndex | Index number of currently selected/active item |
Methods | |
col.setValue(value, duration) | Set new value for current column. value is a new value, duration - transition duration in ms |
col.replaceValues(values, displayValues) | Replace column values and displayValues with new ones |
Picker Events
Picker will fire the following DOM events on picker element and events on app and picker instance:
DOM Events
Event | Target | Description |
---|---|---|
picker:open | Picker Element<div class=”picker”> | Event will be triggered when Picker starts its opening animation |
picker:opened | Picker Element<div class=”picker”> | Event will be triggered after Picker completes its opening animation |
picker:close | Picker Element<div class=”picker”> | Event will be triggered when Picker starts its closing animation |
picker:closed | Picker Element<div class=”picker”> | Event will be triggered after Picker completes its closing animation |
App and Picker Instance Events
Picker instance emits events on both self instance and app instance. App instance events has same names prefixed with picker
.
Event | Target | Arguments | Description |
---|---|---|---|
change | picker | (picker, value, displayValue) | Event will be triggered when picker value changes |
pickerChange | app | ||
init | picker | (picker) | Event will be triggered when picker initialized |
pickerInit | app | ||
open | picker | (picker) | Event will be triggered when Picker starts its opening animation. As an argument event handler receives picker instance |
pickerOpen | app | ||
opened | picker | (picker) | Event will be triggered after Picker completes its opening animation. As an argument event handler receives picker instance |
pickerOpened | app | ||
close | picker | (picker) | Event will be triggered when Picker starts its closing animation. As an argument event handler receives picker instance |
pickerClose | app | ||
closed | picker | (picker) | Event will be triggered after Picker completes its closing animation. As an argument event handler receives picker instance |
pickerClosed | app | ||
beforeDestroy | picker | (picker) | Event will be triggered right before Picker instance will be destroyed. As an argument event handler receives picker instance |
pickerBeforeDestroy | app |
CSS Variables
Below is the list of related CSS variables (CSS custom properties).
Note that commented variables are not specified by default and their values is what they fallback to in this case.
:root {
--f7-picker-height: 260px;
--f7-picker-inline-height: 200px;
--f7-picker-popover-height: 200px;
--f7-picker-popover-width: 280px;
--f7-picker-landscape-height: 200px;
--f7-picker-item-height: 36px;
--f7-picker-item-selected-text-color: #000;
}
:root .theme-dark,
:root.theme-dark {
--f7-picker-item-selected-text-color: #fff;
}
.ios {
--f7-picker-column-font-size: 20px;
--f7-picker-sheet-bg-color: #cfd5da;
--f7-picker-divider-text-color: #000;
--f7-picker-item-text-color: rgba(0, 0, 0, 0.45);
--f7-picker-item-selected-border-color: rgba(0, 0, 0, 0.22);
}
.ios .theme-dark,
.ios.theme-dark {
--f7-picker-sheet-bg-color: #1c1c1d;
--f7-picker-divider-text-color: #fff;
--f7-picker-item-text-color: rgba(255, 255, 255, 0.55);
--f7-picker-item-selected-border-color: rgba(255, 255, 255, 0.06);
}
.md {
/*
--f7-picker-sheet-bg-color: var(--f7-sheet-bg-color);
*/
--f7-picker-column-font-size: 20px;
--f7-picker-divider-text-color: rgba(0, 0, 0, 0.87);
--f7-picker-item-text-color: rgba(0, 0, 0, 0.54);
--f7-picker-item-selected-border-color: rgba(0, 0, 0, 0.15);
}
.md .theme-dark,
.md.theme-dark {
--f7-picker-item-text-color: rgba(255, 255, 255, 0.54);
--f7-picker-divider-text-color: rgba(255, 255, 255, 0.87);
--f7-picker-item-selected-border-color: rgba(255, 255, 255, 0.15);
}
.aurora {
/*
--f7-picker-sheet-bg-color: var(--f7-sheet-bg-color);
*/
--f7-picker-column-font-size: 16px;
--f7-picker-item-height: 28px;
--f7-picker-item-text-color: #888;
--f7-picker-divider-text-color: #000;
--f7-picker-item-selected-border-color: rgba(0, 0, 0, 0.12);
}
.aurora .theme-dark,
.aurora.theme-dark {
--f7-picker-divider-text-color: #fff;
--f7-picker-item-selected-border-color: rgba(255, 255, 255, 0.06);
}
Examples
Picker With Single Value
<div class="block-title">Picker with single value</div>
<div class="list no-hairlines-md">
<ul>
<li>
<div class="item-content item-input">
<div class="item-inner">
<div class="item-input-wrap">
<input type="text" placeholder="Your iOS device" readonly="readonly" id="demo-picker-device"/>
</div>
</div>
</div>
</li>
</ul>
</div>
var pickerDevice = app.picker.create({
inputEl: '#demo-picker-device',
cols: [
{
textAlign: 'center',
values: ['iPhone 4', 'iPhone 4S', 'iPhone 5', 'iPhone 5S', 'iPhone 6', 'iPhone 6 Plus', 'iPad 2', 'iPad Retina', 'iPad Air', 'iPad mini', 'iPad mini 2', 'iPad mini 3']
}
]
});
Two Values and 3D-Rotate Effect
<div class="block-title">2 values and 3d-rotate effect</div>
<div class="list no-hairlines-md">
<ul>
<li>
<div class="item-content item-input">
<div class="item-inner">
<div class="item-input-wrap">
<input type="text" placeholder="Describe yourself" readonly="readonly" id="demo-picker-describe"/>
</div>
</div>
</div>
</li>
</ul>
</div>
var pickerDescribe = app.picker.create({
inputEl: '#demo-picker-describe',
rotateEffect: true,
cols: [
{
textAlign: 'left',
values: ('Super Amazing Bat Iron Rocket Lex Beautiful Wonderful Raining Happy Funny Cool Hot').split(' ')
},
{
values: ('Man Luthor Woman Boy Girl Person Cutie Babe Raccoon').split(' ')
},
]
});
Dependent Values
<div class="block-title">Dependent values</div>
<div class="list no-hairlines-md">
<ul>
<li>
<div class="item-content item-input">
<div class="item-inner">
<div class="item-input-wrap">
<input type="text" placeholder="Your car" readonly="readonly" id="demo-picker-dependent"/>
</div>
</div>
</div>
</li>
</ul>
</div>
var carVendors = {
Japanese : ['Honda', 'Lexus', 'Mazda', 'Nissan', 'Toyota'],
German : ['Audi', 'BMW', 'Mercedes', 'Volkswagen', 'Volvo'],
American : ['Cadillac', 'Chrysler', 'Dodge', 'Ford']
};
var pickerDependent = app.picker.create({
inputEl: '#demo-picker-dependent',
rotateEffect: true,
formatValue: function (values) {
return values[1];
},
cols: [
{
textAlign: 'left',
values: ['Japanese', 'German', 'American'],
onChange: function (picker, country) {
if(picker.cols[1].replaceValues){
picker.cols[1].replaceValues(carVendors[country]);
}
}
},
{
values: carVendors.Japanese,
width: 160,
},
]
});
Custom toolbar
<div class="block-title">Custom toolbar</div>
<div class="list no-hairlines-md">
<ul>
<li>
<div class="item-content item-input">
<div class="item-inner">
<div class="item-input-wrap">
<input type="text" placeholder="Describe yourself" readonly="readonly" id="demo-picker-custom-toolbar"/>
</div>
</div>
</div>
</li>
</ul>
</div>
var pickerCustomToolbar = app.picker.create({
inputEl: '#demo-picker-custom-toolbar',
rotateEffect: true,
renderToolbar: function () {
return '<div class="toolbar">' +
'<div class="toolbar-inner">' +
'<div class="left">' +
'<a href="#" class="link toolbar-randomize-link">Randomize</a>' +
'</div>' +
'<div class="right">' +
'<a href="#" class="link sheet-close popover-close">That\'s me</a>' +
'</div>' +
'</div>' +
'</div>';
},
cols: [
{
values: ['Mr', 'Ms'],
},
{
textAlign: 'left',
values: ('Super Amazing Bat Iron Rocket Lex Beautiful Wonderful Raining Happy Funny Cool Hot').split(' ')
},
{
values: ('Man Luthor Woman Boy Girl Person Cutie Babe Raccoon').split(' ')
},
],
on: {
open: function (picker) {
picker.$el.find('.toolbar-randomize-link').on('click', function () {
var col0Values = picker.cols[0].values;
var col0Random = col0Values[Math.floor(Math.random() * col0Values.length)];
var col1Values = picker.cols[1].values;
var col1Random = col1Values[Math.floor(Math.random() * col1Values.length)];
var col2Values = picker.cols[2].values;
var col2Random = col2Values[Math.floor(Math.random() * col2Values.length)];
picker.setValue([col0Random, col1Random, col2Random]);
});
},
}
});
Inline Picker / Date-time
<div class="block-title">Inline Picker / Date-time</div>
<div class="list no-margin">
<ul>
<li>
<div class="item-content item-input">
<div class="item-inner">
<div class="item-input-wrap">
<input type="text" placeholder="Date Time" readonly="readonly" id="demo-picker-date"/>
</div>
</div>
</div>
</li>
</ul>
</div>
<div class="block block-strong no-padding no-margin margin-bottom">
<div id="demo-picker-date-container"></div>
</div>
var today = new Date();
var pickerInline = app.picker.create({
containerEl: '#demo-picker-date-container',
inputEl: '#demo-picker-date',
toolbar: false,
rotateEffect: true,
value: [
today.getMonth(),
today.getDate(),
today.getFullYear(),
today.getHours(),
today.getMinutes() < 10 ? '0' + today.getMinutes() : today.getMinutes()
],
formatValue: function (values, displayValues) {
return displayValues[0] + ' ' + values[1] + ', ' + values[2] + ' ' + values[3] + ':' + values[4];
},
cols: [
// Months
{
values: ('0 1 2 3 4 5 6 7 8 9 10 11').split(' '),
displayValues: ('January February March April May June July August September October November December').split(' '),
textAlign: 'left'
},
// Days
{
values: [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31],
},
// Years
{
values: (function () {
var arr = [];
for (var i = 1950; i <= 2030; i++) { arr.push(i); }
return arr;
})(),
},
// Space divider
{
divider: true,
content: ' '
},
// Hours
{
values: (function () {
var arr = [];
for (var i = 0; i <= 23; i++) { arr.push(i); }
return arr;
})(),
},
// Divider
{
divider: true,
content: ':'
},
// Minutes
{
values: (function () {
var arr = [];
for (var i = 0; i <= 59; i++) { arr.push(i < 10 ? '0' + i : i); }
return arr;
})(),
}
],
on: {
change: function (picker, values, displayValues) {
var daysInMonth = new Date(picker.value[2], picker.value[0]*1 + 1, 0).getDate();
if (values[1] > daysInMonth) {
picker.cols[1].setValue(daysInMonth);
}
},
}
});