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

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

Published on webcomponents.org

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']
  1. 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
  1. 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'
  1. 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 ''
  1. 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.

Install

Link to this version
ImportedReleased 14 August 2017Apache License 2.0
Framework Support
Polymer 2.0+
Browser Compatibility
Install with
Release notes - Version 1.0.2

Dependencies

Polymer/polymer#^2.0.0