Theme

PlaygroundBeta

npm_versionnpm Paragon package page

ListBox

basic usage

Any Paragon component or export may be added to the code example.

<ListBox>
<ListBoxOption>
Apple
</ListBoxOption>
<ListBoxOption>
Orange
</ListBoxOption>
<ListBoxOption>
Strawberry
</ListBoxOption>
<ListBoxOption>
Banana
</ListBoxOption>
</ListBox>

using tag prop

Any Paragon component or export may be added to the code example.

<React.Fragment>
<div>This is an ordered list!</div>
<ListBox tag="ol">
<ListBoxOption tag="li">
Apple
</ListBoxOption>
<ListBoxOption tag="li">
<div>Orange</div>
</ListBoxOption>
<ListBoxOption tag="li">
Strawberry
</ListBoxOption>
<ListBoxOption tag="li">
Banana
</ListBoxOption>
</ListBox>
</React.Fragment>

using onSelect prop

Any Paragon component or export may be added to the code example.

class ListBoxWrapperForOnSelect extends React.Component {
constructor(props) {
super(props);
this.onSelect = this.onSelect.bind(this);
this.state = {
selectedOption: null,
selectedOptionIndex: null,
};
this.fruits = {
Apple: '๐ŸŽ',
Orange: '๐ŸŠ',
Strawberry: '๐Ÿ“',
Banana: '๐ŸŒ',
};
}
onSelect(option, index) {
this.setState({
selectedOption: option,
selectedOptionIndex: index,
});
}
getSelectedFruitEmoji(fruit) {
return fruit ? this.fruits[fruit] : '';
}
render() {
const children = Object.keys(this.fruits).map((fruit, index) => (
<ListBoxOption
key={fruit}
onSelect={() => this.onSelect(fruit, index)}
style={{ textAlign: 'center' }}
>
{fruit}
</ListBoxOption>
));
return (
<React.Fragment>
<span aria-live="polite">
Selected Fruit:
{this.state.selectedOptionIndex === undefined ? (
<span className="sr-only">none</span>
) : (
<span
arialabelledby={`list-box-option-${
this.state.selectedOptionIndex
}`}
>
{this.getSelectedFruitEmoji(this.state.selectedOption)}
</span>
)}
</span>
<ListBox style={{ width: '200px' }}>
{children}
</ListBox>
</React.Fragment>
);
}
}

using selectedOptionIndex prop

Any Paragon component or export may be added to the code example.

class ListBoxWrapperForSelectedOptionIndex extends React.Component {
constructor(props) {
super(props);
this.onSelect = this.onSelect.bind(this);
this.onButtonClick = this.onButtonClick.bind(this);
this.state = {
reset: true,
};
this.fruits = Object.keys({
Apple: '๐ŸŽ',
Orange: '๐ŸŠ',
Strawberry: '๐Ÿ“',
Banana: '๐ŸŒ',
});
}
onButtonClick() {
this.setState({
reset: true,
});
}
onSelect() {
this.setState({
reset: false,
});
}
render() {
const children = this.fruits.map(fruit => (
<ListBoxOption
key={fruit}
onSelect={this.onSelect}
style={{ textAlign: 'center' }}
>
{fruit}
</ListBoxOption>
));
return (
<React.Fragment>
<Button variant="primary" onClick={this.onButtonClick}>
Click me to reset your selected fruit!
</Button>
<ListBox
selectedOptionIndex={this.state.reset ? null : undefined}
style={{ margin: '10px' }}
>
{children}
</ListBox>
</React.Fragment>
);
}
}

Props API#

ListBox Props API
  • children node Required

    specifies the ListBoxOption component(s) that will be displayed within the ListBox element. You can pass in one or more ListBoxOption components.

  • className string

    specifies Bootstrap class names to apply to the ListBox component. The default is an empty string.

  • selectedOptionIndex nonNegativeInteger

    Although the ListBox component keeps track of which ListBoxOption is selected, selectedOptionIndex provides a mechanism for an override, if necessary. An example would be to clear the selectedOption when moving between views. Note that override is not permanent and that clicking on a ListBoxOption or interacting with the ListBox with the keyboard will change the selected ListBoxOption relative to the original override. The default is undefined.

  • tag string

    used to specify the element type of the rendered ListBox component. The default is div. Example alternatives include ol, ul, span, etc.

    Default'div'
ListBoxOption Props API
  • children node Required
  • className string
  • index number
  • isSelected bool
    Defaultfalse
  • tag string
    Default'div'
  • onSelect func
    Default() => { }