# xpl-choicelist

A Choice List allows users to make single or multiple selections from a list of choices.  This component is meant to consume the radio and checkbox components, either styled or unstyled, then allow for customizing an option list very quickly.
<!-- Auto Generated Below -->


## Properties

| Property      | Attribute     | Description                                                                                                                                                                                                                                                 | Type       | Default     |
| ------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ----------- |
| `choices`     | --            | An array of choices to be displayed in the list. Each choice should be an object with keys: - `checked` [boolean] - whether to pre-check or not - `children` [Choice[]] - an array of child choices (recursive) - `description` [string] - `label` [string] | `Choice[]` | `undefined` |
| `description` | `description` | Descriptive text to be displayed above the choice-list.                                                                                                                                                                                                     | `string`   | `undefined` |
| `heading`     | `heading`     | The title text to be displayed above the choice-list.                                                                                                                                                                                                       | `string`   | `undefined` |
| `multi`       | `multi`       | Whether the user can select more than one choice (true) or only a single choice (false). Corresponds to checkboxes vs. radio buttons.                                                                                                                       | `boolean`  | `undefined` |
| `name`        | `name`        | The `name` to be associated with form data.                                                                                                                                                                                                                 | `string`   | `uuid()`    |
| `styled`      | `styled`      | If `true`, will include borders around the list and between individual choices.                                                                                                                                                                             | `boolean`  | `undefined` |


## Events

| Event                   | Description                                                                                                                                                                                                                                                                                                               | Type                                                      |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `choicelistChange`      | An event that is emitted when the selected value changes. The event detail will be an array of booleans, where each boolean corresponds to the checked state of the choices.                                                                                                                                              | `CustomEvent<boolean[]>`                                  |
| `choicelistValueChange` | An event that is emitted when the selected value changes. The event detail will be an array if the multi prop is true, otherwise it will be a single value. The value will be string if value is provided for choices, otherwise it will be a boolean.  NOTE: This will only be emitted if choices have a value property. | `CustomEvent<(string \| boolean)[] \| boolean \| string>` |


## Dependencies

### Depends on

- [xpl-checkbox](../xpl-checkbox)
- [xpl-radio](../xpl-radio)

### Graph
```mermaid
graph TD;
  xpl-choicelist --> xpl-checkbox
  xpl-choicelist --> xpl-radio
  style xpl-choicelist fill:#f9f,stroke:#333,stroke-width:4px
```

----------------------------------------------

*Built with [StencilJS](https://stenciljs.com/)*