Directory

← Back

se-datalist

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

Author

Rating

Popularity

<100

[ 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.

Compatibility

(Loading compatibility data...)

Was this helpful? Need more help?
Leave a comment or a question below. You can also join the chat on Discord or ask questions on StackOverflow.

Version

Dependencies

Polymer/polymer#^2.0.0

Released
2017-08-14
Maturity
IMPORTED
License
Apache License 2.0

Compatibility

Framework
Polymer 2.0+
Browser
Browser Independent

se-datalist - Vaadin Add-on Directory

Wrapper around datalist and select tags, to provide datalist whenever it possible and fallback to select otherwise. se-datalist - Vaadin Add-on Directory
**[ This description is mirrored from README.md at [github.com/andrewmiroshnichenko/se-datalist](https://github.com//andrewmiroshnichenko/se-datalist/blob/v1.0.2/README.md) on 2019-05-10 ]** [![Published on webcomponents.org](https://img.shields.io/badge/webcomponents.org-published-blue.svg)](https://www.webcomponents.org/element/andrewmiroshnichenko/se-datalist) # 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](https://www.npmjs.com/package/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. ```html ``` ```javascript 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 `` tag will lead to disabling of component, even if it's value will be `false`. ```html ``` ```javascript 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. ```html ``` ```javascript 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. ```html ``` ```javascript 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. ```html ``` ## 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`. ```html ``` ```javascript 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`. ```html ``` ```javascript 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. ```html ``` ```javascript 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`.
Online