@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 |

For a basic ListBox

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

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>
  );
}

Links

• Storybook Showcase
• GitHub source code
• Create GitHub issue
• CHANGELOG