se-datalist

Polymer wrapper around native select and datalist tags with browser-dependent appearance. If browser don't support datalist tag it will fall back to select which is supported fairly well. Note that all bugs, that are belong to native datalist tag will appear on this custom element as well, since it just refer to general tag support.

Install

$ bower install se-datalist

Make sure you have the Polymer CLI installed. Then run polymer serve to serve your element locally.

Viewing component

$ polymer serve

Running tests

$ polymer test

API

Properties

1. List

Property name	list
Property type	Array
Default value	[]
Can be set from html	No
Corresponding attribute

List of the component options. Empty by default, read-only. All manipulations with the list should be accomplished by corresponding component methods(addOptions, removeOptions and removeAllOptions). So, by default, component is initializing without options, and then will populated using JS.

      <se-datalist></se-datalist>

      var customEl = document.querySelector('se-datalist');
      customEl.list = ['1', '2', 'coconut'];
      customEl.list;  // returns empty Array, because list property is read-only 
      customEl.addOptions(['a', 'b']);
      customEl.list;  // returns Array ['a', 'b']
      customEl.removeOptions(['a']);
      customEl.list;  // returns Array ['b']

2. Disabled

Property name	disabled
Property type	Boolean
Default value	false
Can be set from html	Yes
Corresponding attribute	disabled

If true - disables possibility of user interaction with component. But component’s value still will be changeable from code. Warning: presence of this property as attribute of <se-datalist> tag will lead to disabling of component, even if it's value will be false.

      <se-datalist disabled="false"></se-datalist>

      var customEl = document.querySelector('se-datalist');
      customEl.disabled; // returns Boolean true
      customEl.disabled = false;
      customEl.disabled; // returns Boolean false

3. Placeholder

Property name	placeholder
Property type	String
Default value	-
Can be set from html	Yes
Corresponding attribute	placeholder

String that is shown as component’s placeholder when component’s value is empty. Length of this property is limited to 20 characters, bigger placeholder will explicitely cut to this length. When component’s value changes from empty to non-empty placeholder should move to “upper left corner” of the component.

      <se-datalist></se-datalist>

      var customEl = document.querySelector('se-datalist');
      customEl.placeholder; // returns String ''
      customEl.placeholder = 'Select an option';
      customEl.placeholder; // returns String 'Select an option'

4. Selected option

Property name	selectedOption
Property type	String
Default value	''
Can be set from html	No
Corresponding attribute

Current option that is selected as component’s value. Can't be set from HTML because we can't set list from there. On attempt to set non-existing (in list property) selected option this property will be set to empty Sring if list property is empty or if no option is selected yet. If some selected option was already selected - it will remain as selectedOption property value. If current selectedOption will removed from list - selectedOption will become empty.

      <se-datalist></se-datalist>

      var customEl = document.querySelector('se-datalist');
      customEl.addOptions(['One', 'Two', 'Three']); // Setup component’s list of options
      customEl.selectedOption = 'Two';
      customEl.selectedOption; // returns String 'Two'
      customEl.removeOptions(['Two']);
      customEl.selectedOption; // returns String ''
      customEl.selectedOption = 'Four';
      customEl.selectedOption; // returns String ''
      customEl.removeOptions(['One', 'Three']);
      customEl.selectedOption; // returns String ''

5. Is select

Property name	isSelect
Property type	Boolean
Default value	false
Can be set from html	Yes
Corresponding attribute	is-select

With this property set to true component will initialize as select even if datalist is available in current browser. In order to achieve this behavior you should set it upon initialization as attribute of se-datalist tag.

      <se-datalist is-select></se-datalist>

Methods

addOptions(optionsList: Array) => void or false

This method accepts array of options, and populates the component’s list property. If option from optionsList isn't already present in list - component will add it to the end of list, and if it's duplicate of existing option - method will return false.

      <se-datalist></se-datalist>

      var customEl = document.querySelector('se-datalist');
      customEl.addOptions(['One', 'Two', 'Three']);
      customEl.list; // returns Array ['One', 'Two', 'Three']
      customEl.addOptions(['Four']);
      customEl.list; // returns Array ['One', 'Two', 'Three', 'Four']
      customEl.addOptions(['Four', 'Five']);  // returns Boolean 'false' on adding option 'Four'
      customEl.list; // returns Array ['One', 'Two', 'Three', 'Four', 'Five']

removeOptions(optionsList: Array) => void or false

This method accepts array of options, and removes them from the component’s list property. If option from optionsList isn't already present in list - method will return false, and if it's existing option - component will remove it from list.

      <se-datalist></se-datalist>

      var customEl = document.querySelector('se-datalist');
      customEl.addOptions(['One', 'Two', 'Three']);
      customEl.list; // returns Array ['One', 'Two', 'Three']
      customEl.removeOptions(['Two']);
      customEl.list; // returns Array ['One', 'Three']
      customEl.removeOptions(['Four']); // returns Boolean 'false' on adding option 'Four'
      customEl.list; // returns Array ['One', 'Three']
      customEl.addOptions(['One', 'Three']);
      customEl.list; // returns empty Array

removeAllOptions() => void

Completely removes all options from the component’s list property.

      <se-datalist></se-datalist>

      var customEl = document.querySelector('se-datalist');
      customEl.addOptions(['One', 'Two', 'Three']);
      customEl.list; // returns Array ['One', 'Two', 'Three']
      customEl.removeAllOptions();
      customEl.list; // returns Array []

Styling

The following custom properties are available for styling:

Custom property	Description	Default
--sedatalist-text-color	Color of datalist's displayed value	Browser-default(black)
--sedatalist-bottom-line	Style of component’s bottom line. Other borders are disabled	1px solid rgba(0, 0, 0, .12)
--sedatalist-placeholder-color	Color of placeholder text	#999999
--sedatalist-font-size	Charachters font size. Component dimesions will scale accordingly	16px
--sedatalist-font-family	Font family of component typography	Roboto, sans-serif

Events

valueChanged(event) Event is fired when new option from list is chosen. New value is accessible as event.detail.newValue, old value - as event.detail.oldValue.

listChanged(event) Event is fired when list is changed(options are either added or removed). New list is accessible as event.detail.newList, old value - as event.detail.oldList.