Listbox

Listboxes are menus that display options and allow the user to select one. Listboxes are the menu which displays when clicking a <rapid-select></rapid-select>.

Use cases:

• Constructing menus as part of form items

While any DOM content is permissible as a child of the listbox, only <rapid-option> elements, option elements, and slotted items with role="option" attribute will be treated as options and receive keyboard support.

tip

The primary use of this component is to be used as part of other custom form components you wish to construct. If you simply want to use a form item which allows the user to select one value we recommend you use a <rapid-radio-group></rapid-radio-group> or <rapid-segmented-control></rapid-segmented-control> instead.

Example

AppleBananaStrawberry

Selected:

Genesis

Declaration

<rapid-listbox>
  <rapid-option></rapid-option>
  <rapid-option></rapid-option>
  <rapid-option></rapid-option>
</rapid-listbox>

Usage

@customElement({
  name: 'my-element',
  template: html`
    <rapid-listbox @click=${(x, ctx) => x.setSelected(ctx.event)}>
      <rapid-option value="apple">Apple</rapid-option>
      <rapid-option value="banana">Banana</rapid-option>
      <rapid-option value="strawberry">Strawberry</rapid-option>
    </rapid-listbox>
    Listbox value: ${x => x.listboxValue}
  `,
})
export class MyElement extends GenesisElement {
  @observable listboxValue: string;
  setSelected(event: Event & { target: { value: string } }) {
    this.listboxValue = event.target.value;
  }
}

warning

Unlike most other Genesis components you cannot use the sync directive here. This is because the listbox doesn't fire events, that is intended to be controlled by the parent form element.

React

Declaration

<rapid-listbox>
  <rapid-option></rapid-option>
  <rapid-option></rapid-option>
  <rapid-option></rapid-option>
</rapid-listbox>

Usage

export function MyComponent() {
const [selected, setSelected] = useState('');

return (
  <div>
    <rapid-listbox onClick={(e) => setSelected(e.target.value)}>
      <rapid-option value="apple">Apple</rapid-option>
      <rapid-option value="banana">Banana</rapid-option>
      <rapid-option value="strawberry">Strawberry</rapid-option>
    </rapid-listbox>
    <p>Selected: {selected}</p>
  </div>)
}

Angular

Declaration

<rapid-listbox>
  <rapid-option></rapid-option>
  <rapid-option></rapid-option>
  <rapid-option></rapid-option>
</rapid-listbox>

Usage

import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { FormsModule } from '@angular/forms';
@Component({
  selector: 'my-component',
  template: `
    <rapid-listbox (click)="setSelected($event)">
      <rapid-option value="apple">Apple</rapid-option>
      <rapid-option value="banana">Banana</rapid-option>
      <rapid-option value="strawberry">Strawberry</rapid-option>
    </rapid-listbox>
    <p>Selected: {{ selected }}</p>
  `,
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  imports: [FormsModule],
})
export class MyComponent {
  selected: string = '';
  setSelected(event: any) {
    this.selected = event.target.value;
  }
}

API

Attributes

Attribute	Type	Description	Example
disabled	boolean	When disabled the user won't be able to interact with the component.	<rapid-listbox disabled>

Properties

These properties are intended to be selected in the TypeScript code with a reference to the component, not declaratively via the html.

Property	Type	Description
selectedIndex	number	The index of the selected option. Starts at -1 indicating no item selected.
selectedOptions	ListboxOption[]	A collection of the selected options.

Slots

Slot	Description
Default	The default slot which should be filled with <rapid-option>.

Option attributes

In order to use the component, you need to create a list of options for the user to select from. You create this list using <rapid-option>. You can define the following attributes for an <rapid-option>:

Name	Type	Description
disabled	boolean	Disables an option so that the user cannot interact with it, but the option is still visible
selected	boolean	Selects the option, so it turns to the selected mode
value	string	The value of the attribute

You can also use the repeat directive to create options dynamically in the code:

import { html, repeat } from '@genesislcap/web-core';
const sampleSelectOptions = [
  { label: 'Large', value: 'l' },
  { label: 'Small', value: 's' },
];
html`
  <rapid-listbox>
    ${repeat(
      (x) => x.sampleSelectOptions,
      html`
        <rapid-option value="${(x) => x.value}">${(x) => x.label}</rapid-option>
      `
    )}
  </rapid-listbox>
`;

Methods

Method	Modifier	Type	Description
selectFirstOption	public	() => void	Moves focus to the first selectable option.
setSelectedOption	protected	() => void	Sets an option as selected (according to the select status of the child option components) and gives it focus.

Parts

This component doesn't have any parts.

Events fired

This component doesn't fire any events. When used as part of a larger form component it's recommended you'd fire change events from that component when the user interacts with the underlying listbox.

Events listened to

This component doesn't listen to any events.