# Select ## Usage The custom select component is a web component built from scratch to enhance the native `` tag as options reference. ```html
``` ## Capturing values There are several ways to capture values from the `` component. The simplest approach is to add a `name` attribute to the component. When you do this, a hidden input field with the specified name will be automatically generated, allowing you to easily capture the selected value on your server. ```html
``` Note If you don't specify a `value` attribute for an `` tag, which will be automatically converted into a dropdown header, providing a seamless developer experience. ```html
``` ## Selecting multiple values To enable the selection of multiple values, simply add the `multiple` attribute to the `` element. This will allow users to choose multiple options from the dropdown list. ```html
``` Note When utilizing the `multiple` attribute, note that it will automatically append `[]` to the name of your input. This is particularly useful when your server expects multiple values, even if the user selects only one option. This ensures that your server-side logic can properly handle the input, regardless of the number of values selected. ## Prepopulating values There are two ways to prepopulate values from the `` component. The simplest approach is to add a `selected` attribute to one or more of your ` ``` ## Searchable To add a search box, simply add the `searchable` attribute. This will add an input field within the dropdown menu, enabling users to search for specific options. This feature is particularly useful when dealing with extensive lists, such as selecting a country from a long list of options. ```html
``` Search features: - Case-insensitive filtering - Real-time results as you type - Searches through option keywords (automatically generated from text) - Emits `z-select:search` event on search term change - Supports keyboard navigation through filtered results ### Custom keywords Sometimes, there are items that have related keywords that may be slightly off or awkward when included as anchor tags. For these use cases, we can leverage the `data-keywords` attribute. For example, if we have a "Form" link but also want it to appear when users search for terms like "checkbox," "input," "toggle switch," etc., we can simply add a comma-separated list of terms like this: `data-keywords="apple, mango, lemon"`. ```html
``` ## Disable input To prevent user input, add the `disabled` attribute to the `` element. This will disable the custom select, making it impossible for users to enter or modify its value. ```html
``` ## Icon This component allows you to customize icons through the template system: ```html
``` ### Options icon To add icon to options, just add `data-icon` attribute with the name of the icon to your ` ``` ### Using global i18n Place this in your document `` or before any select components: ```html ``` ### Available i18n options | Key | Default | Description | | -------------------- | ------------------------ | ---------------------------------------------------------------------------- | | `search-placeholder` | Search | Placeholder text for search input field | | `selection-count` | {'{n}'} options selected | Text shown when multiple options are selected (supports {'{n}'} placeholder) | | `insert` | Insert | Button text for inserting custom options | | `list-label` | Options | ARIA label for the listbox | | `button-label` | Select an option | ARIA label and default text for the select button | ## Custom classes The Select component supports custom CSS classes through the `cls` attribute. This allows you to style specific elements within the select without modifying the component's internal structure. ### Using simple string format Apply a class to the default element (button): ```html ``` ### Using JSON object format Target specific elements within the select: ```html ``` ### Using configuration script ```html ``` ### Available cls targets | Target | Description | | --------------- | --------------------------------------------------------------- | | `host-inner` | The main wrapper container for the entire component | | `button` | The clickable button that opens the dropdown | | `button-text` | The text span inside the button showing selected option(s) | | `icon` | The icon element inside the button (when icon attribute is set) | | `dropdown` | The dropdown container holding the list and search | | `list` | The listbox (ul) containing all options | | `item` | Individual list item (li) wrapper | | `item-active` | The active list item (li) | | `item-disabled` | Class for disabled list item (li) | | `item-header` | Group header for grouped options | | `item-link` | The clickable button/link inside each item | | `item-wrapper` | Wrapper for item content (icon + text) | | `item-icon` | Icon element for options with data-icon | | `item-text` | Text label for the option | | `item-check` | Checkmark indicator for selected options | | `item-subtitle` | Description/subtitle text for options with data-description | | `search` | Search input wrapper (when searchable is enabled) | | `search-input` | The actual search input field | | `search-icon` | Icon displayed in search input | | `divider` | Class for the divider element | ## Custom inline styles The Select component supports custom inline styles through the `stl` attribute. This allows you to apply specific CSS styles to individual elements within the select. ### Using simple string format Apply styles to the default element (button): ```html ``` ### Using JSON object format Target specific elements with custom styles: ```html ``` ### Using configuration script ```html ``` ### Available stl targets The `stl` attribute supports the same targets as the `cls` attribute. See the [Available cls targets](#available-cls-targets) table above for a complete list of targetable elements. ## Error state To indicate an error state in the form, simply add the `.z-form-danger` class to the `cls` attribute. This will apply a "danger" state to the component, providing visual feedback to the user. ```html

This field is required.

``` ## Preventing layout shift When loading Web Components, a brief delay may cause a flash of unstyled content. To mitigate this issue, consider setting a predefined height on the parent element to prevent layout shift and ensure a smooth user experience. ```html
``` ## Attributes The following attributes are available for this component: | Name | Type | Default | Description | | ------------------------ | ------- | ----------------------------------------------------- | -------------------------------------------------------------------------------- | | `searchable` | Boolean | false | Enables search functionality to filter options | | `insertable` | Boolean | false | Allows inserting custom options (auto-enables searchable) | | `send-headers` | String | | JSON object of HTTP headers for server validation requests | | `send-url` | String | | Server endpoint URL for validating inserted options | | `send-method` | String | POST | HTTP method for server requests | | `multiple` | Boolean | false | Enables multi-select mode | | `icon` | String | | Custom icon/text displayed in the button | | `name` | String | | Name attribute for hidden input(s), enabling form submission | | `disabled` | Boolean | false | Disables the entire component, preventing user interaction | | `required` | Boolean | false | Marks the select as required for form validation | | `placeholder` | String | | Custom placeholder text when no option is selected | | `value` | String | | Pre-selected value(s). Use comma-separated for multiple selections | | `cls` | String | | Custom CSS classes. Can be simple string or JSON object for targeting elements | | `stl` | String | | Custom inline styles. Can be simple string or JSON object for targeting elements | | `i18n` | String | | Internationalization strings as JSON object or via configuration script | | `force-prevent-rerender` | Boolean | false | Prevents component rerendering (useful for HTMX or SPA scenarios) | ## Events The Select component triggers the following events: | Name | Description | | ------------------ | --------------------------------------------------------------------------------------------------------- | | `z-select:input` | Fired when the selected value(s) change. Event detail contains `{value: string \| string[]}`. | | `z-select:search` | Fired when the search term changes (when searchable is enabled). Event detail contains `{value: string}`. |