@ampproject/amp-selector
Advanced tools
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>.
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 preview="top-frame" playground="false"]
Install via npm:
npm install @ampproject/bento-selector
import '@ampproject/bento-selector';
[/example]
<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]
bento-selector can contain any arbitrary HTML elements or AMP components (e.g., bento-carousel, etc.).bento-selector cannot contain any nested bento-selector controls.option attribute to the element and assigning a value to the attribute (e.g., <li option="value"></li>).disabled attribute to the element (e.g., <li option="d" disabled></li>).selected attribute to the element (e.g., <li option="b" selected></li>).multiple attribute to the bento-selector element. By default, the bento-selector allows for one selection at a time.bento-selector, add the disabled attribute to the bento-selector element.bento-selector contains a name attribute and the bento-selector is inside a form tag, if a submit event occurs on the form, the bento-selectorbehaves like a radio-button/checkbox group and submits the selected values (the ones assigned to the option) against the name of the bento-selector.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>
<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>.
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.
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"`.
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.
selector.addEventListener("select", (e) => console.log(e.data.targetOption))
The examples below demonstrate use of the <BentoSelector> as a functional component usable with the Preact or React libraries.
[example preview="top-frame" playground="false"]
Install via npm:
npm install @ampproject/bento-selector
import 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]
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";
}
<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>.
<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.
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>
);
}
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"`.
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.
FAQs
AMP HTML amp-selector Component
The npm package @ampproject/amp-selector receives a total of 2 weekly downloads. As such, @ampproject/amp-selector popularity was classified as not popular.
We found that @ampproject/amp-selector demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 16 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Ransomware payment rates hit an all-time low in 2024 as law enforcement crackdowns, stronger defenses, and shifting policies make attacks riskier and less profitable.
Security News
require(esm) backported to Node.js 20, easing the transition to ESM-only packages and reducing complexity for developers as Node 18 nears end-of-life.
Security News
PyPI now supports iOS and Android wheels, making it easier for Python developers to distribute mobile packages.