Bento Selector
Usage
The Bento Selector is a control that presents a list of options and lets the user choose one or many options; the contents of the options aren't just limited to text. It can be used as a web component<bento-selector>, or as a Preact/React functional component <BentoSelector>.
Web Component
You must include each Bento component's required CSS library before adding custom styles in order to guarantee proper loading. Or use the lightweight pre-uprgrade styles available inline. See Layout and Style
Example: Import via npm
[example preview="top-frame" playground="false"]
Install via npm:
npm install @ampproject/bento-selectorimport '@ampproject/bento-selector';[/example]
Example: Include via <script>
[example preview="top-frame" playground="false"]
<head>
<script src="https://cdn.ampproject.org/custom-elements-polyfill.js"></script>
<!-- These styles prevent Cumulative Layout Shift on the unupgraded custom element -->
<style data-bento-boilerplate>
bento-selector {
display: block;
}
</style>
<script async src="https://cdn.ampproject.org/v0/bento-selector-1.0.js"></script>
</head>
<bento-selector class="sample-selector">
<ul>
<li option="1">Option 1</li>
<li option="2">Option 2</li>
<li option="3">Option 3</li>
<li option="4">Option 4</li>
</ul>
</bento-selector>[/example]
Usage notes
- A
bento-selectorcan contain any arbitrary HTML elements or AMP components (e.g.,bento-carousel, etc.). - A
bento-selectorcannot contain any nestedbento-selectorcontrols. - Selectable options can be set by adding the
optionattribute to the element and assigning a value to the attribute (e.g.,<li option="value"></li>). - Disabled options can be set by adding the
disabledattribute to the element (e.g.,<li option="d" disabled></li>). - Preselected options can be set by adding the
selectedattribute to the element (e.g.,<li option="b" selected></li>). - To allow for multiple selections, add the
multipleattribute to thebento-selectorelement. By default, thebento-selectorallows for one selection at a time. - To disable the entire
bento-selector, add thedisabledattribute to thebento-selectorelement. - When an
bento-selectorcontains anameattribute and thebento-selectoris inside aformtag, if a submit event occurs on the form, thebento-selectorbehaves like a radio-button/checkbox group and submits the selected values (the ones assigned to the option) against the name of thebento-selector.
Layout and Style
Each Bento component has a small CSS library you must include to guarantee proper loading without content shifts. Because of order-based specificity, you must manually ensure that stylesheets are included before any custom styles.
You may also make the light-weight pre-upgrade styles available inline:
<style data-bento-boilerplate>
bento-selector{
display: block;
}
</style>
Attributes on <bento-selector>
disabled, form, multiple, name
The attributes above behave the same way as they do on a standard HTML <select> element.
keyboard-select-mode
The keyboard-select-mode attribute dictates the keyboard navigation behavior for options inside <bento-selector>.
- `none` (default): The tab key changes focus between items in the ``. The user must press enter or space to change the selection. Arrow keys are disabled.
- `focus`: Tab key gives focus to ``. The user navigates between items with the arrow keys. Must press space or enter to change the selection.
- `select`: Tab key gives focus to ``. The selection changes as the user navigates options with arrow keys.
Attributes on option elements
option (required)
Indicates that the option is selectable. If a value is specified, the contents of the value is submitted with the form.
disabled, selected
The attributes above behave the same way as they do on a standard HTML <option> element.
Actions
The bento-selector API allows you to perform the following actions:
selectBy(delta: number) Closes the selector.
api.selectBy(1); // Select next option in DOM sequence.
api.selectBy(-2); // Select the option that is two previous in DOM sequence.toggle(optionValue: string, opt_select: boolean|undefined)
Toggles the option with the given optionValue to be selected or deselected based on opt_select. If opt_select is not present, then the option will be selected if currently not selected, and deselected if currently selected.
api.toggle("a"); // Toggle the item with the attribute `option="a"`.
api.toggle("1", true); // Select the item with the attribute `option="1"`.Events
The bento-selector API allows you to register and respond to the following events:
select
This event is triggered when the user selects an option.
Multi-selectors and single-selectors fire this when selecting or unselecting options.
Tapping disabled options does not trigger the select event.
- `event.data.targetOption` contains the `option` attribute value of the selected element.
- `event.data.selectedOptions` contains an array of the `option` attribute values of all selected elements.
selector.addEventListener("select", (e) => console.log(e.data.targetOption))Preact/React Component
The examples below demonstrate use of the <BentoSelector> as a functional component usable with the Preact or React libraries.
Example: Import via npm
[example preview="top-frame" playground="false"]
Install via npm:
npm install @ampproject/bento-selectorimport React from 'react';
import { BentoSelector, BentoSelectorOption} from '@ampproject/bento-selector/react';
import '@ampproject/bento-selector/styles.css';
function App() {
return (
<BentoSelector>
<BentoSelectorOption option="1">Option 1</BentoSelectorOption>
<BentoSelectorOption option="2">Option 2</BentoSelectorOption>
<BentoSelectorOption option="3">Option 3</BentoSelectorOption>
<BentoSelectorOption option="4">Option 4</BentoSelectorOption>
</BentoSelector>
);
}[/example]
Layout and Style
Container type
The BentoSelector component can be styled with standard CSS.
The width and height of the BentoSelector may both be set in order to adjust the default size of the component.
To ensure the component renders how you want it to, be sure to apply a size to the component. These can be applied inline:
<BentoSelector style={{width: "100px", height:"400px"}}>
<BentoSelectorOption option="1">Option 1</BentoSelectorOption>
</BentoSelector>Or via className:
<BentoSelector className='custom-styles'>
<BentoSelectorOption option="1">Option 1</BentoSelectorOption>
</BentoSelector>.custom-styles {
width: "100px";
height: "400px";
}
Props for <BentoSelector>
disabled, form, multiple, name
The attributes above behave the same way as they do on a standard HTML <select> element.
keyboardSelectMode
The keyboardSelectMode attribute dictates the keyboard navigation behavior for options inside <BentoSelector>.
- `none` (default): The tab key changes focus between items in the ``. The user must press enter or space to change the selection. Arrow keys are disabled.
- `focus`: Tab key gives focus to ``. The user navigates between items with the arrow keys. Must press space or enter to change the selection.
- `select`: Tab key gives focus to ``. The selection changes as the user navigates options with arrow keys.
Props for <BentoSelectorOption>
option
Indicates that the option is selectable. If a value is specified, the contents of the value is submitted with the form.
disabled, selected
The attributes above behave the same way as they do on a standard HTML <option> element.
Interactivity and API usage
Bento components are highly interactive through their API. The BentoSelector component API is accessible by passing a ref:
import React, {createRef} from 'react';
const ref = createRef();
function App() {
return (
<BentoSelector ref={ref}>
<BentoSelectorOption option="1">Option 1</BentoSelectorOption>
<BentoSelectorOption option="2">Option 2</BentoSelectorOption>
<BentoSelectorOption option="3">Option 3</BentoSelectorOption>
<BentoSelectorOption option="4">Option 4</BentoSelectorOption>
</BentoSelector>
);
}Actions
The BentoSelector API allows you to perform the following actions:
selectBy(delta: number) Closes the selector.
ref.selectBy(1); // Select next option in DOM sequence.
ref.selectBy(-2); // Select the option that is two previous in DOM sequence.toggle(optionValue: string, opt_select: boolean|undefined)
Toggles the option with the given optionValue to be selected or deselected based on opt_select. If opt_select is not present, then the option will be selected if currently not selected, and deselected if currently selected.
ref.toggle("1"); // Toggle the item with the attribute `option="1"`.
ref.toggle("2", true); // Select the item with the attribute `option="2"`.Events
select
This event is triggered when the user selects an option.
Multi-selectors and single-selectors fire this when selecting or unselecting options.
Tapping disabled options does not trigger the select event.