npm package: @paprika/list-box
Description: The ListBox component allows users to select one or more options from a list contained within the component
Author: @paprika
Latest version: 7.0.4

<!-- start: Autogenerated - do not modify -->

# @paprika/list-box

## Description

The ListBox component allows users to select one or more options from a list contained within the component

## Installation

```
yarn add @paprika/list-box
```

or with npm:

```
npm install @paprika/list-box
```

## Props

### ListBox

| Prop           | Type                                                                                                        | required | default                            | Description                                                                    |
| -------------- | ----------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------- | ------------------------------------------------------------------------------ |
| children       | arrayOf                                                                                                     | false    | null                               | Child of type <ListBox.Option />, <ListBox.Divider />, etc                     |
| hasError       | bool                                                                                                        | false    | false                              | If ListBox is in an error state                                                |
| hasTag         | bool                                                                                                        | false    | false                              | If there is a tag                                                              |
| hasImplicitAll | bool                                                                                                        | false    | false                              | Has implicit "All items selected" value when no item is selected               |
| height         | [string,number]                                                                                             | false    | 200                                | The maximum height for the options container. Using a number implies px units. |
| isDisabled     | bool                                                                                                        | false    | false                              | Disables the ListBox if true                                                   |
| isInline       | bool                                                                                                        | false    | false                              | This options will display the list-box without the Popover                     |
| isMulti        | bool                                                                                                        | false    | false                              | Let the user to select multiple options at same time                           |
| isOpen         | bool                                                                                                        | false    | false                              | Indicates if the popover is visible                                            |
| isReadOnly     | bool                                                                                                        | false    | false                              | The ListBox will not allow value to be changed                                 |
| onChange       | func                                                                                                        | false    | () => {}                           | Callback returning the current selection on the ListBox                        |
| placeholder    | string                                                                                                      | false    | null                               | Default label for trigger when the ListBox has no option selected              |
| size           | [ ListBoxContainer.types.size.SMALL, ListBoxContainer.types.size.MEDIUM, ListBoxContainer.types.size.LARGE] | false    | ListBoxContainer.types.size.MEDIUM | Size of the trigger and options (font size, height, padding, etc).             |
| contentOffsetX | number                                                                                                      | false    | 0                                  | Lets the user control the X-axis offset for the ListBox content                |
| contentOffsetY | number                                                                                                      | false    | 0                                  | Lets the user control the Y-axis offset for the ListBox content                |

### ListBox.A11y

| Prop     | Type   | required | default | Description                                                                              |
| -------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------- |
| id       | string | false    | null    | DOM id attribute for focussable control (trigger element or ul element if isInline=true) |
| refLabel | custom | false    | null    | Ref for a DOM element containing the label for this component                            |

### ListBox.Box

| Prop     | Type | required | default | Description              |
| -------- | ---- | -------- | ------- | ------------------------ |
| children | node | false    | null    | Body content of the box. |

### ListBox.Divider

| Prop       | Type | required | default | Description                                   |
| ---------- | ---- | -------- | ------- | --------------------------------------------- |
| isDisabled | bool | false    | true    | isDisable is use internally as a default prop |

the prop is read by the option/helpers/optionState.js which is assigned in the store
it helps to ignore the divider while using the keyboard.
see: options/helpers/options.js|
|children|node|false|null| |

### ListBox.Filter

| Prop             | Type   | required | default | Description                                                                                         |
| ---------------- | ------ | -------- | ------- | --------------------------------------------------------------------------------------------------- |
| a11yText         | string | false    | null    | Descriptive a11y text for assistive technologies. By default, text from children node will be used. |
| filter           | func   | false    | null    | Filters the list                                                                                    |
| hasSearchIcon    | bool   | false    | true    | If true displays a search icon                                                                      |
| noResultsMessage | string | false    | null    | Message displayed if no results are found                                                           |
| onChangeFilter   | func   | false    | null    | Callback to be executed when the value is changed                                                   |
| onKeyDown        | func   | false    | null    | Callback to be executed when a key is pressed                                                       |
| placeholder      | string | false    | null    | Displays a placeholder                                                                              |
| renderFilter     | func   | false    | null    | Render function for filter                                                                          |
| value            | string | false    | null    | Sets a value for filter                                                                             |

### ListBox.Footer

| Prop              | Type                                                                          | required | default                   | Description                                                                         |
| ----------------- | ----------------------------------------------------------------------------- | -------- | ------------------------- | ----------------------------------------------------------------------------------- |
| isAcceptVisible   | bool                                                                          | false    | true                      | If true it makes the accept button visible                                          |
| isCancelVisible   | bool                                                                          | false    | true                      | If true it makes the cancel button visible                                          |
| isClearVisible    | bool                                                                          | false    | true                      | If true it makes the clear button visible                                           |
| isDisabled        | bool                                                                          | false    | false                     | If true it makes the footer disabled                                                |
| kindAccept        | [ Button.types.kind.PRIMARY, Button.types.kind.MINOR]                         | false    | Button.types.kind.PRIMARY | Sets what kind the accept button will be                                            |
| kindCancel        | [ Button.types.kind.PRIMARY, Button.types.kind.MINOR]                         | false    | Button.types.kind.MINOR   | Sets what kind the cancel button will be                                            |
| kindClear         | [ Button.types.kind.PRIMARY, Button.types.kind.MINOR]                         | false    | Button.types.kind.MINOR   | Sets what kind the cancel button will be                                            |
| labelAccept       | string                                                                        | false    | null                      | Sets the label for the accept button                                                |
| labelCancel       | string                                                                        | false    | null                      | Sets the label for the cancel button                                                |
| labelClear        | string                                                                        | false    | null                      | Sets the label for the clear button                                                 |
| onClickAccept     | func                                                                          | false    | null                      | Callback to be executed when the accept button is clicked or activated by keyboard. |
| onClickCancel     | func                                                                          | false    | null                      | Callback to be executed when the cancel button is clicked or activated by keyboard. |
| onClickClear      | func                                                                          | false    | null                      | Callback to be executed when the clear button is clicked or activated by keyboard.  |
| renderExtraButton | func                                                                          | false    | () => {}                  | Render an extra button beside the clear button                                      |
| size              | [ Button.types.size.SMALL, Button.types.size.MEDIUM, Button.types.size.LARGE] | false    | Button.types.size.MEDIUM  | Determines the size of the footer                                                   |

### ListBox.Option

| Prop                   | Type        | required | default    | Description                                                                            |
| ---------------------- | ----------- | -------- | ---------- | -------------------------------------------------------------------------------------- |
| children               | [node,func] | true     | -          | String, number or JSX content                                                          |
| isSelected             | bool        | false    | null       |                                                                                        |
| defaultIsSelected      | bool        | false    | null       | Describe if the option started as selected or not                                      |
| hasNoIcon              | bool        | false    | false      | When no PlusIcon or CheckBox are needed                                                |
| isDisabled             | bool        | false    | false      | Describe if the option is enable or not                                                |
| isHidden               | bool        | false    | false      | Describe if the option is hidden or not                                                |
| label                  | string      | false    | null       | When the children are not a String, label should need to be add so the filter can work |
| onClick                | func        | false    | null       | Callback for the clicking event                                                        |
| value                  | any         | false    | null       | Value of your option this can be any data structure                                    |
| internalHandleOnClick  | func        | false    | () => null | Internal prop, which shouldn't be documented                                           |
| id                     | string      | false    | ""         | Internal prop, which shouldn't be documented                                           |
| preventDefaultOnSelect | bool        | false    | false      | Internal prop, which shouldn't be documented                                           |

### ListBox.Popover

| Prop     | Type   | required | default | Description                           |
| -------- | ------ | -------- | ------- | ------------------------------------- |
| children | node   | false    | -       | Body content of the PopOver.          |
| zIndex   | number | false    | 100     | Sets the z-index value of the PopOver |

### ListBox.RawItem

| Prop                   | Type | required | default | Description |
| ---------------------- | ---- | -------- | ------- | ----------- |
| preventDefaultOnSelect | bool | false    | true    |             |

### ListBox.Trigger

| Prop                | Type        | required | default | Description                                                                         |
| ------------------- | ----------- | -------- | ------- | ----------------------------------------------------------------------------------- |
| clearIcon           | node        | false    | null    | Custom clear icon                                                                   |
| children            | [node,func] | false    | <></>   | Body content of the trigger.                                                        |
| hasClearButton      | bool        | false    | true    | If true it adds a clear button                                                      |
| hasImplicitAll      | bool        | false    | false   | Has implicit "All items selected" value when no item is selected                    |
| label               | string      | false    | null    | Override the label with a custom one.                                               |
| onClickClear        | func        | false    | null    | Callback to be executed when the clear button is clicked or activated by keyboard.  |
| onClickFooterAccept | func        | false    | null    | Callback to be executed when the accept button is clicked or activated by keyboard. |
| placeholder         | string      | false    | null    | Sets a placeholder for the trigger                                                  |
| isHidden            | bool        | false    | false   | If true the trigger will be hidden                                                  |

<!-- end: Autogenerated - do not modify -->
<!-- content -->

For a basic ListBox

```js
import ListBox from "@paprika/list-box";

function Component() {
  return (
    <ListBox onChange={changeHandler}>
      <ListBox.Option>Option 1</ListBox.Option>
      <ListBox.Option>Option 2</ListBox.Option>
    </ListBox>
  );
}
```

With Filter

```js
import ListBox from "@paprika/list-box";

function Component() {
  return (
    <ListBox onChange={changeHandler}>
      <ListBox.Filter />
      <ListBox.Option>Option 1</ListBox.Option>
      <ListBox.Option>Option 2</ListBox.Option>
    </ListBox>
  );
}
```

<!-- eoContent -->

## Links

- [Storybook Showcase](https://paprika.highbond.com/?path=/story/forms-listbox--showcase)
- [GitHub source code](https://github.com/acl-services/paprika/tree/master/packages/ListBox/src)
- [Create GitHub issue](https://github.com/acl-services/paprika/issues/new?label=[]&title=@paprika/list-box%20[help]:%20your%20short%20description&body=%0A%23%20Help%20wanted%0A%0A%23%23%20Please%20write%20your%20question.%0A*A%20clear%20and%20concise%20description%20of%20what%20the%20question%20is*%0A%0A%23%23%20Additional%20context%0A*Add%20any%20other%20context%20or%20screenshots%20about%20your%20question%20here.*%0A)
- [CHANGELOG](https://github.com/acl-services/paprika/tree/master/packages/ListBox/CHANGELOG.md)