<commit_before>---
title: Basic Usage
order: 2
layout: page
---


[[vaadin-combo-box.example]]
= Basic Usage

You need to provide the set of items which the user can select with the [propertyname]#items# property.
Current selection is indicated by the [propertyname]#value# and [propertyname]#selectedItem# properties.
You can set or change the selection programmatically by setting the [propertyname]#value# property.
Doing so also updates the visible fields.

When setting the items declaratively, notice that the attribute value needs to be a valid JSON string. You need to use single quotes for the attribute value and double quotes inside the value (in the JSON string). Alternatively, you can escape the double quotes inside the value.

[source,html]
----
<vaadin-combo-box 
  label="Element" 
  items='["Bohrium", "Boron", "Bromine", "Cadmium", "Caesium", "Calcium"]' 
  value="Bromine">
</vaadin-combo-box>
----

Setting the items and value programmatically:

[source,javascript]
----
var combobox = document.querySelector('vaadin-combo-box');
combobox.items = ['Bohrium', 'Boron', 'Bromine', 'Cadmium', 'Caesium', 'Calcium'];
combobox.value = 'Bromine';
----

== Events

The [vaadinelement]#vaadin-combo-box# element dispatches events when the value changes.
An event contains the [propertyname]#value# property in the [propertyname]#event.detail# object.


[source,javascript]
----
var combobox = document.querySelector('vaadin-combo-box');
combobox.addEventListener('value-changed', function(event) {
  console.log(event.detail.value);
});

combobox.addEventListener('selected-item-changed', function(event) {
  console.log(event.detail.value);
});
----

When using the element inside another Polymer element, you can use the declarative binding syntax to subscribe for an event:

[source,html]
----
<dom-module id="my-element">
  <template>
    <vaadin-combo-box on-value-change="valueChanged"></vaadin-combo-box>
  </template>
</dom-module>
<script>
  Polymer({
    is: 'my-element',
    valueChanged: function(event) {
      alert(event.detail.value);
    }
  });
</script>
----

== Forms

In addition to other features mentioned earlier, the [vaadinelement]#vaadin-combo-box# implements the [classname]#IronFormElementBehavior#, so it can be used as a field in an [elementname]#iron-form#.

[source,html]
----
<form is="iron-form" method="post">
  <vaadin-combo-box name="name" label="Element"></vaadin-combo-box>
  <button>Submit</button>
</form>
<script>
  var form = document.querySelector('form');
  var combobox = document.querySelector('vaadin-combo-box');

  form.addEventListener('iron-form-submit', function() {
    alert('Form submitted with name: ' + form.serialize().name);
    return false;
  });
</script>
----

== Custom Input Values

Users can be allowed also to input their own custom values. By default, this feature is disabled, so it
needs to be explicitly enabled.

[source,html]
----
<vaadin-combo-box allow-custom-value></vaadin-combo-box>
----

When enabled, custom input values are always accepted and used as the value of the [vaadinelement]#vaadin-combo-box#.
If you need to cancel the automatic assignment, you can provide your own listener for the custom-value-set event<commit_msg>Update vaadin-combo-box-basic.adoc<commit_after>---
title: Basic Usage
order: 2
layout: page
---


[[vaadin-combo-box.example]]
= Basic Usage

You need to provide the set of items which the user can select with the [propertyname]#items# property.
Current selection is indicated by the [propertyname]#value# and [propertyname]#selectedItem# properties.
You can set or change the selection programmatically by setting the [propertyname]#value# property.
Doing so also updates the visible fields.

When setting the items declaratively, notice that the attribute value needs to be a valid JSON string. You need to use single quotes for the attribute value and double quotes inside the value (in the JSON string). Alternatively, you can escape the double quotes inside the value.

[source,html]
----
<vaadin-combo-box 
  label="Element" 
  items='["Bohrium", "Boron", "Bromine", "Cadmium", "Caesium", "Calcium"]' 
  value="Bromine">
</vaadin-combo-box>
----

Setting the items and value programmatically:

[source,javascript]
----
var combobox = document.querySelector('vaadin-combo-box');
combobox.items = ['Bohrium', 'Boron', 'Bromine', 'Cadmium', 'Caesium', 'Calcium'];
combobox.value = 'Bromine';
----

== Events

The [vaadinelement]#vaadin-combo-box# element dispatches events when the value changes.
An event contains the [propertyname]#value# property in the [propertyname]#event.detail# object.


[source,javascript]
----
var combobox = document.querySelector('vaadin-combo-box');
combobox.addEventListener('value-changed', function(event) {
  console.log(event.detail.value);
});

combobox.addEventListener('selected-item-changed', function(event) {
  console.log(event.detail.value);
});
----

When using the element inside another Polymer element, you can use the declarative binding syntax to subscribe for an event:

[source,html]
----
<dom-module id="my-element">
  <template>
    <vaadin-combo-box on-value-change="valueChanged"></vaadin-combo-box>
  </template>
</dom-module>
<script>
  Polymer({
    is: 'my-element',
    valueChanged: function(event) {
      alert(event.detail.value);
    }
  });
</script>
----

== Forms

The [vaadinelement]#<vaadin-combo-box># element implements the link:https://elements.polymer-project.org/elements/iron-form-element-behavior[[classname]#IronFormElementBehavior#], so it can be used as a field in an link:https://elements.polymer-project.org/elements/iron-form[[elementname]#iron-form#].

[source,html]
----
<form is="iron-form" method="post">
  <vaadin-combo-box name="name" label="Element"></vaadin-combo-box>
  <button>Submit</button>
</form>
<script>
  var form = document.querySelector('form');
  var combobox = document.querySelector('vaadin-combo-box');

  form.addEventListener('iron-form-submit', function() {
    alert('Form submitted with name: ' + form.serialize().name);
    return false;
  });
</script>
----

== Custom Input Values

Users can be allowed also to input their own custom values. By default, this feature is disabled, so it
needs to be explicitly enabled.

[source,html]
----
<vaadin-combo-box allow-custom-value></vaadin-combo-box>
----

When enabled, custom input values are always accepted and used as the value of the [vaadinelement]#vaadin-combo-box#.
If you need to cancel the automatic assignment, you can provide your own listener for the custom-value-set event
{'fraction_non_alphanumeric': 0.1370342205323194, 'fraction_numerical': 0.0003041825095057034, 'mean_word_length': 4.601362862010221, 'pattern_counts': {'":': 0, '<': 44, '<?xml version=': 0, '>': 44, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '796776', 'n_tokens_mistral': 2060, 'n_tokens_neox': 1956, 'n_words': 624}