# xpl-select Select allows users to make a single selection or multiple selections from a list of options. Items can be a simple list, grouped, simple multi-select. User selections typically appear within the Select Box once created unless multiple selections are made, where truncation or another method of showing these selections is required. ***When the list of options contains “Actions”, use a ***[Dropdown component](https://apollo.xplordocs.com/?path=/story/components-dropdown--simple). The `selectIcon` property accepts icon names as strings. See [xpl-icon available icons](../xpl-icon/ICONS.md) for the complete list. --- ## Properties | Property | Attribute | Description | Type | Default | | -------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | | `choices` | -- | An array of choices for the user to choose from. Each choice should be of the form: { label: string; href?: string; value?: string; isGroupHeading?: boolean; isSelected?: boolean; isDisabled?: boolean; options?: DropdownItem[]; groupName?: string; } | `Partial[]` | `[]` | | `classNames` | `class-names` | The class name to apply to the select component. | `string` | `undefined` | | `customDisplayValue` | `custom-display-value` | If true, enables custom display value rendering via slot. | `boolean` | `undefined` | | `description` | `description` | Optional text that appears below the input label. | `string` | `undefined` | | `disabled` | `disabled` | Whether the field is disabled | `boolean` | `undefined` | | `dropdownFlipFallbackPlacements` | -- | Additional placements to try for the options panel when the default `dropdownPlacement` does not fit. Passed to `xpl-dropdown` / Floating UI `flip`. | `Placement[]` | `undefined` | | `dropdownPlacement` | `dropdown-placement` | Initial Floating UI placement for the options panel (e.g. `top-start`, `bottom-start`). Forwarded to the inner `xpl-dropdown` when the menu is open. | `"bottom" \| "bottom-end" \| "bottom-start" \| "left" \| "left-end" \| "left-start" \| "right" \| "right-end" \| "right-start" \| "top" \| "top-end" \| "top-start"` | `'bottom-start'` | | `error` | `error` | If an empty string (attribute present with no value), will display visually as an error. If a string is included, will display visually as an error and include the value as an error message. | `string` | `undefined` | | `label` | `label` | The label that appears above the select dropdown | `string` | `undefined` | | `mode` | `mode` | Whether to allow a single choice or multiple choices. | `"multi" \| "single"` | `'single'` | | `name` | `name` | The name of the hidden input field that contains the selected option's value(s) | `string` | `undefined` | | `placeholder` | `placeholder` | Placeholder text that appears when the field has no value | `string` | `undefined` | | `selectIcon` | `select-icon` | The icon to display in the select trigger button. See [xpl-icon available icons](../xpl-icon/ICONS.md) for valid icon names. | `string` | `'chevron-down'` | | `selectedValues` | `selected-values` | The value(s) currently selected in the select component. | `string \| string[]` | `undefined` | | `truncate` | `truncate` | Only used in multi-choice selects. If `true`, badges representing selections that would overflow the container are replaced with "+x more" (where x is the number not shown). If `false`, the container's height will adjust to show all badges representing selections. | `boolean` | `true` | ## Events | Event | Description | Type | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- | | `changeEvent` | Emits the value of the selected option in the select menu on change | `CustomEvent` | | `dropdownStateChange` | Emits when the dropdown opens or closes | `CustomEvent` | | `selectChange` | Emits the value of the selected option in the select menu on change | `CustomEvent` | | `triggerDropdown` | Emits before the dropdown state changes, allowing listeners to prevent the default behavior. The event detail contains the previous and new dropdown states. | `CustomEvent<{ prevState: boolean; nextState: boolean; }>` | ## Methods ### `reset() => Promise` Resets the select component to its initial state with no selections. This clears all selected values and returns the component to its default state. #### Returns Type: `Promise` ## Dependencies ### Used by - [xpl-pagination](../xpl-pagination) - [xpl-tabs](../xpl-tabs) ### Depends on - [xpl-tag](../xpl-tag) - [xpl-icon](../xpl-icon) - [xpl-dropdown](../xpl-dropdown) ### Graph ```mermaid graph TD; xpl-select --> xpl-tag xpl-select --> xpl-icon xpl-select --> xpl-dropdown xpl-tag --> xpl-icon xpl-dropdown --> xpl-dropdown-group xpl-dropdown --> xpl-dropdown-option xpl-dropdown-group --> xpl-dropdown-group xpl-dropdown-group --> xpl-dropdown-option xpl-dropdown-group --> xpl-dropdown-heading xpl-dropdown-option --> xpl-icon xpl-pagination --> xpl-select xpl-tabs --> xpl-select style xpl-select fill:#f9f,stroke:#333,stroke-width:4px ``` ---------------------------------------------- *Built with [StencilJS](https://stenciljs.com/)*