AMP
EN
Deutsch Français العربية Español Italiano Indonesia 日本語 한국어 Português Русский Türkçe 中文 Polski Tiếng việt
  • websites

amp-selector

Open in playground

Introduction

amp-selector lets the user choose from a list of options. The contents of the options isn't limited to just text.

Setup

Import the amp-selector component.

<script async custom-element="amp-selector" src="https://cdn.ampproject.org/v0/amp-selector-0.1.js"></script>

This sample also demonstrates how to combine amp-selector with forms ...

<script async custom-element="amp-form" src="https://cdn.ampproject.org/v0/amp-form-0.1.js"></script>

... and amp-bind.

<script async custom-element="amp-bind" src="https://cdn.ampproject.org/v0/amp-bind-0.1.js"></script>

Single select

amp-selector defaults to single selection. The option is required for all selectable elements, for example, the divider in the following sample cannot be selected.

 
<amp-selector class="sample-selector" layout="container">
  <amp-img src="/static/samples/img/landscape_sea_300x199.jpg" alt="Image 1" width="90" height="60" option="1"></amp-img>
  <amp-img src="/static/samples/img/landscape_desert_300x200.jpg" alt="Image 2" width="90" height="60" option="2"></amp-img>
  <div class="divider inline-block mx1"></div>
  <amp-img src="/static/samples/img/landscape_ship_300x200.jpg" alt="Image 3" width="90" height="60" option="3"></amp-img>
  <amp-img src="/static/samples/img/landscape_village_300x200.jpg" alt="Image 4" width="90" height="60" option="4"></amp-img>
</amp-selector>

Multi select

Add the attribute multiple to enable multi selection.

<amp-selector layout="container" class="sample-selector" multiple>
  <amp-img src="/static/samples/img/landscape_sea_300x199.jpg" alt="Image 1" width="90" height="60" option="1"></amp-img>
  <amp-img src="/static/samples/img/landscape_desert_300x200.jpg" alt="Image 2" width="90" height="60" option="2"></amp-img>
  <amp-img src="/static/samples/img/landscape_ship_300x200.jpg" alt="Image 3" width="90" height="60" option="3"></amp-img>
  <amp-img src="/static/samples/img/landscape_village_300x200.jpg" alt="Image 4" width="90" height="60" option="4"></amp-img>
</amp-selector>

Disable and pre-select attributes

The following attributes are supported for select elements:

  • disabled: disable an element.
  • selected: pre-select an element.
<amp-selector layout="container" class="sample-selector" multiple>
  <amp-img src="/static/samples/img/landscape_sea_300x199.jpg" alt="Image 1" width="90" height="60" option="1"></amp-img>
  <amp-img src="/static/samples/img/landscape_desert_300x200.jpg" alt="Image 2" width="90" height="60" option="2" selected></amp-img>
  <amp-img src="/static/samples/img/landscape_ship_300x200.jpg" alt="Image 3" width="90" height="60" option="3"></amp-img>
  <amp-img src="/static/samples/img/landscape_village_300x200.jpg" alt="Image 4" width="90" height="60" option="4" disabled></amp-img>
</amp-selector>

Disabled amp-selector

Add the attribute disabled to disable the whole selector.

<amp-selector layout="container" class="sample-selector" disabled>
  <amp-img src="/static/samples/img/landscape_sea_300x199.jpg" alt="Image 1" width="90" height="60"></amp-img>
  <amp-img src="/static/samples/img/landscape_desert_300x200.jpg" alt="Image 2" width="90" height="60"></amp-img>
  <amp-img src="/static/samples/img/landscape_ship_300x200.jpg" alt="Image 3" width="90" height="60"></amp-img>
  <amp-img src="/static/samples/img/landscape_village_300x200.jpg" alt="Image 4" width="90" height="60"></amp-img>
</amp-selector>

Keyboard select modes

Add the attribute keyboard-select-mode to opt into a pre-defined user interaction pattern for amp-selector. By default the value is 'NONE' and displays the following behavior.

<amp-selector layout="container" keyboard-select-mode="none" class="sample-selector" disabled>
  <amp-img src="/static/samples/img/landscape_sea_300x199.jpg" alt="Image 1" width="90" height="60"></amp-img>
  <amp-img src="/static/samples/img/landscape_desert_300x200.jpg" alt="Image 2" width="90" height="60"></amp-img>
  <amp-img src="/static/samples/img/landscape_ship_300x200.jpg" alt="Image 3" width="90" height="60"></amp-img>
  <amp-img src="/static/samples/img/landscape_village_300x200.jpg" alt="Image 4" width="90" height="60"></amp-img>
</amp-selector>

Keyboard select mode: Focus

Add the attribute keyboard-select-mode="focus" so the Tab key gives focus to amp-selector. The user navigates between items with the arrow keys. Must press space or enter to change the selection.

<amp-selector layout="container" keyboard-select-mode="focus" class="sample-selector">
  <amp-img src="/static/samples/img/landscape_sea_300x199.jpg" alt="Image 1" width="90" height="60"></amp-img>
  <amp-img src="/static/samples/img/landscape_desert_300x200.jpg" alt="Image 2" width="90" height="60"></amp-img>
  <amp-img src="/static/samples/img/landscape_ship_300x200.jpg" alt="Image 3" width="90" height="60"></amp-img>
  <amp-img src="/static/samples/img/landscape_village_300x200.jpg" alt="Image 4" width="90" height="60"></amp-img>
</amp-selector>

Keyboard select mode: Select

Add the attribute keyboard-select-mode="focus" so the Tab key gives focus to amp-selector. The selection changes as the user navigates options with arrow keys.

<amp-selector layout="container" keyboard-select-mode="select" class="sample-selector">
  <amp-img src="/static/samples/img/landscape_sea_300x199.jpg" alt="Image 1" width="90" height="60"></amp-img>
  <amp-img src="/static/samples/img/landscape_desert_300x200.jpg" alt="Image 2" width="90" height="60"></amp-img>
  <amp-img src="/static/samples/img/landscape_ship_300x200.jpg" alt="Image 3" width="90" height="60"></amp-img>
  <amp-img src="/static/samples/img/landscape_village_300x200.jpg" alt="Image 4" width="90" height="60"></amp-img>
</amp-selector>

Actions

The clear action may be used to clear all selections of an amp-selector.

<amp-selector id="actionsSample" layout="container" class="sample-selector" multiple>
  <amp-img src="/static/samples/img/landscape_sea_300x199.jpg" alt="Image 1" width="90" height="60" option="1"></amp-img>
  <amp-img src="/static/samples/img/landscape_desert_300x200.jpg" alt="Image 2" width="90" height="60" option="2"></amp-img>
  <amp-img src="/static/samples/img/landscape_ship_300x200.jpg" alt="Image 3" width="90" height="60" option="3" selected></amp-img>
  <amp-img src="/static/samples/img/landscape_village_300x200.jpg" alt="Image 4" width="90" height="60" option="4"></amp-img>
  <amp-img src="/static/samples/img/landscape_trees_300x225.jpg" width="90" height="60" option="5" selected></amp-img>
  <amp-img src="/static/samples/img/landscape_green_300x200.jpg" width="90" height="60" option="6"></amp-img>
</amp-selector>
<button on="tap:actionsSample.clear">clear</button>
<button on="tap:actionsSample.selectUp">selectUp</button>
<button on="tap:actionsSample.selectUp(delta=2)">selectUp(delta=2)</button>
<button on="tap:actionsSample.selectDown">selectDown</button>
<button on="tap:actionsSample.selectDown(delta=2)">selectDown(delta=2)</button>
<button on="tap:actionsSample.toggle(index=1)">toggle(index=1)</button>
<button on="tap:actionsSample.toggle(index=1, value=true)">toggle(index=1, value=true)</button>

Events

Listen to the select or selectedOptions events to trigger other actions or update amp-state.

Option A
Option B
Option C
Option D
Last selected option:a
All selected option(s): a
<amp-selector multiple layout="container" class="radio-selector" on="select: AMP.setState({
      selectedOption: event.targetOption,
      allSelectedOptions: event.selectedOptions
    })">
  <div option="a" selected>Option A</div>
  <div option="b">Option B</div>
  <div option="c">Option C</div>
  <div option="d">Option D</div>
</amp-selector>
<div>Last selected option:<code [text]="selectedOption">a</code></div>
<div>All selected option(s): <code [text]="allSelectedOptions.join(', ')">a</code></div>

Forms

Inside a form, amp-selector behaves like a radio-button/checkbox group and submits the selected value(s) against the name of the amp-selector. Here we've styled an amp-selector to function like a radio list. Using amp-selector for this has the advantage that bindings using amp-bind are easier to implement.

Option A
Option B
Option C
 
<form action="#" method="get" target="_top">
  <amp-selector class="radio-selector" layout="container" name="my-selector">
    <div option="a">Option A</div>
    <div option="b">Option B</div>
    <div option="c">Option C</div>
  </amp-selector>
  <button>Submit</button>
</form>
Need further explanation?

If the explanations on this page don't cover all of your questions feel free to reach out to other AMP users to discuss your exact use case.

Go to Stack Overflow
An unexplained feature?

The AMP project strongly encourages your participation and contributions! We hope you'll become an ongoing participant in our open source community but we also welcome one-off contributions for the issues you're particularly passionate about.

Edit sample on GitHub