@bentoproject/selector v1.2305051745.1
Bento Selector
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.
Usage
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
Install via npm:
npm install @bentoproject/selector
import {defineElement as defineBentoSelector} from '@bentoproject/selector';
defineBentoSelector();
Example: Include via <script>
<head>
<script src="https://cdn.ampproject.org/bento.js"></script>
<!-- These styles prevent Cumulative Layout Shift on the unupgraded custom element -->
<style>
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>
Usage notes
- A
bento-selector
can contain any arbitrary HTML elements or AMP components (e.g.,bento-carousel
, etc.). - A
bento-selector
cannot contain any nestedbento-selector
controls. - Selectable options can be set by adding the
option
attribute to the element and assigning a value to the attribute (e.g.,<li option="value"></li>
). - Disabled options can be set by adding the
disabled
attribute to the element (e.g.,<li option="d" disabled></li>
). - Preselected options can be set by adding the
selected
attribute to the element (e.g.,<li option="b" selected></li>
). - To allow for multiple selections, add the
multiple
attribute to thebento-selector
element. By default, thebento-selector
allows for one selection at a time. - To disable the entire
bento-selector
, add thedisabled
attribute to thebento-selector
element. - When an
bento-selector
contains aname
attribute and thebento-selector
is inside aform
tag, if a submit event occurs on the form, thebento-selector
behaves 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>
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>
.
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.
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
Install via npm:
npm install @bentoproject/selector
import React from 'react';
import {
BentoSelector,
BentoSelectorOption,
} from '@bentoproject/selector/react';
import '@bentoproject/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>
);
}
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: 100, height: 400}}>
<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>
.
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.current.selectBy(1); // Select next option in DOM sequence.
ref.current.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.current.toggle('1'); // Toggle the item with the attribute `option="1"`.
ref.current.toggle('2', true); // Select the item with the attribute `option="2"`.
Events
BentoSelector
API allows you to register and respond to the following events:
onChange
This event is triggered when a selector option is selected or deselected.
The onChange
prop gives you two key options:
option
which returns the value of theoption
prop of theBentoSelectorOption
which was selected or deselected.value
which returns an array of whichBentoSelectorOptions
are currently selected in the order they were selected.
<BentoSelector
as="ul"
multiple
onChange={({option, value}) => console.log(option, value)}
>
<BentoSelectorOption as="li" option="1">
Option 1
</BentoSelectorOption>
<BentoSelectorOption as="li" option="2">
Option 2
</BentoSelectorOption>
</BentoSelector>
12 months ago
1 year ago
1 year ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
2 years ago
1 year ago
2 years ago
2 years ago
1 year ago
1 year ago
1 year ago
1 year ago
2 years ago
2 years ago
1 year ago
1 year ago
2 years ago
1 year ago
1 year ago
2 years ago
1 year ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago