se-datalist

Wrapper around datalist and select tags, to provide datalist whenever it possible and fallback to select otherwise.

View larger

Close

[ This description is mirrored from README.md at github.com/andrewmiroshnichenko/se-datalist on 2019-05-10 ]

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

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

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

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

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

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:

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.

Links

• Online Demo
• Documentation
• View on GitHub
• GitHub Homepage
• Issue tracker

Compatibility