# auro-combobox The `auro-combobox` element provides users with a way to select an option from a list of filtered or suggested options based on user input. ## Properties | Property | Attribute | Modifiers | Type | Default | Description | |---------------------------------------|---------------------------------------|-----------|--------------------------------------------------|------------------|--------------------------------------------------| | `appearance` | `appearance` | | `'default' \| 'inverse'` | "'default'" | Defines whether the component will be on lighter or darker backgrounds. | | `autoPlacement` | `autoplacement` | | `boolean` | | If declared, bib's position will be automatically calculated where to appear. | | `autocomplete` | `autocomplete` | | `string` | | An enumerated attribute that defines what the user agent can suggest for autofill. At this time, only `autocomplete="off"` is supported. | | `behavior` | `behavior` | | `'filter' \| 'suggestion'` | "'suggestion'" | Sets the behavior of the combobox, "filter" or "suggestion".
"filter" requires the user to select an option from the menu.
"suggestion" allows the user to enter a value not present in the menu options. | | `checkmark` | `checkmark` | | `boolean` | | When attribute is present auro-menu will apply check marks to selected options. | | `disabled` | `disabled` | | `boolean` | | If set, disables the combobox. | | `dvInputOnly` | `dvinputonly` | | `boolean` | | If defined, the display value slot content will only mask the HTML5 input element. The inputs label will not be masked. | | `error` | `error` | | `string` | | When defined, sets persistent validity to `customError` and sets the validation message to the attribute value. | | `format` | `format` | | `string` | | Specifies the input mask format. | | `fullscreenBreakpoint` | `fullscreenbreakpoint` | | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'disabled'` | "'sm'" | Defines the screen size breakpointat which the dropdown switches to fullscreen mode on mobile. `disabled` indicates a dropdown should _never_ enter fullscreen.

When expanded, the dropdown will automatically display in fullscreen mode
if the screen size is equal to or smaller than the selected breakpoint. | | `inputValue` | | readonly | `string \| undefined` | | Returns the current value of the input element within the combobox. | | `inputmode` | `inputmode` | | `string` | | Exposes inputmode attribute for input. | | `largeFullscreenHeadline` | `largefullscreenheadline` | | `boolean` | | If declared, make bib.fullscreen.headline in HeadingDisplay.
Otherwise, Heading 600 | | `layout` | `layout` | | `'classic' \| 'emphasized' \| 'snowflake'` | "'classic'" | Sets the layout of the combobox. | | `noFilter` | `nofilter` | | `boolean` | | If set, combobox will not filter menuoptions based on input. | | `noFlip` | `noflip` | | `boolean` | | If declared, the bib will NOT flip to an alternate position
when there isn't enough space in the specified `placement`. | | `noValidate` | `novalidate` | | `boolean` | | If set, disables auto-validation on blur. | | `offset` | `offset` | | `number` | "0" | Gap between the trigger element and bib. | | `onDark` | `ondark` | | `boolean` | | DEPRECATED - use `appearance="inverse"` instead. | | `optionSelected` | | | `HTMLElement` | | Specifies the current selected option. | | `persistInput` | `persistinput` | | `boolean` | | If declared, selecting a menu option will not change the input value. By doing so,
the current menu filter will be preserved and the user can continue from their last
filter state. It is recommended to use this in combination with the `displayValue` slot. | | `placeholder` | `placeholder` | | `string` | | Define custom placeholder text, only supported by date input formats. | | `placement` | `placement` | | `'top' \| 'right' \| 'bottom' \| 'left' \| 'bottom-start' \| 'top-start' \| 'top-end' \| 'right-start' \| 'right-end' \| 'bottom-end' \| 'left-start' \| 'left-end'` | "'bottom-start'" | Position where the bib should appear relative to the trigger. | | `required` | `required` | | `boolean` | | Populates the `required` attribute on the input. Used for client-side validation. | | `setCustomValidity` | `setcustomvalidity` | | `string` | | Sets a custom help text message to display for all validityStates. | | `setCustomValidityCustomError` | `setcustomvaliditycustomerror` | | `string` | | Custom help text message to display when validity = `customError`. | | `setCustomValidityValueMissing` | `setcustomvalidityvaluemissing` | | `string` | | Custom help text message to display when validity = `valueMissing`. | | `setCustomValidityValueMissingFilter` | `setcustomvalidityvaluemissingfilter` | | `string` | | Custom help text message to display when validity = `valueMissing` due to the user not choosing a menu option when behavior = "filter". | | `shape` | `shape` | | `'box' \| 'classic' \| 'pill' \| 'pill-left' \| 'pill-right' \| 'rounded' \| 'snowflake'` | "'classic'" | Sets the shape of the combobox. | | `shift` | `shift` | | `boolean` | | If declared, the dropdown will shift its position to avoid being cut off by the viewport. | | `size` | `size` | | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | "'xl'" | Sets the size of the combobox. | | `triggerIcon` | `triggericon` | | `boolean` | | If set, the `icon` attribute will be applied to the trigger `auro-input` element.
Icon rendering is currently limited to `type="credit-card"`. Setting `triggerIcon`
without a supported `type` propagates the attribute but does not render a visible icon. | | `type` | `type` | | `'text' \| 'password' \| 'email' \| 'credit-card' \| 'tel' \| 'number' \| 'date'` | | Applies the defined value as the type attribute on `auro-input`. | | `typedValue` | `typedvalue` | | `string` | | Specifies the value of the input element within the combobox. | | `validity` | `validity` | | `string` | | Specifies the `validityState` this element is in. | | `value` | `value` | | `string` | | Value selected for the dropdown menu. When set programmatically or as a preset attribute, the value must match a selectable option. If it matches an option marked `disabled` or `static`, the selection is rejected: `value` and `optionSelected` are cleared to `undefined`. `hidden` options (including those filtered out by type-ahead) remain selectable by value. | ## Methods | Method | Type | Description | |----------------------|----------------------------------------|--------------------------------------------------| | `clear` | `(): void` | Clears the current value of the combobox. | | `focus` | `(): void` | Focuses the combobox trigger input. | | `hideBib` | `(): void` | Hides the dropdown bib if its open. | | `isValid` | `(): boolean` | Checks if the element is valid. | | `reset` | `(): void` | Resets component to initial state. | | `setMenuValue` | `(value: string): void` | Sets the menu value if menu is available.

**value**: The value to set on the menu. | | `showBib` | `(): void` | Shows the dropdown bib if there are options to show. | | `updateActiveOption` | `(index: number): void` | Updates the active option in the menu.

**index**: Index of the option to make active. | | `validate` | `(force?: boolean \| undefined): void` | Validates value.

**force**: Whether to force validation. | ## Events | Event | Type | Description | |-----------------------------|--------------------------------------------------|--------------------------------------------------| | `auroCombobox-valueSet` | `CustomEvent` | Notifies that the component has a new value set. **DEPRECATED** - Use the `input` event instead. | | `auroFormElement-validated` | | Notifies that the component value(s) have been validated. | | `input` | `CustomEvent<{ optionSelected: any; value: any; }>` | Notifies that the component has a new value set. | | `inputValue` | `CustomEvent<{ value: string \| undefined; }>` | Notifies that the components internal HTML5 input value has changed. | ## Slots | Name | Description | |---------------------------|--------------------------------------------------| | | Default slot for the menu content. | | `ariaLabel.bib.close` | Sets aria-label on close button in fullscreen bib | | `ariaLabel.input.clear` | Sets aria-label on clear button | | `bib.fullscreen.headline` | Defines the headline to display above menu-options | | `displayValue` | Allows custom HTML content to display the selected value when the combobox is not focused. Only works with `snowflake` and `emphasized` layouts. | | `helpText` | Defines the content of the helpText. | | `label` | Defines the content of the label. | | `optionalLabel` | Allows overriding the optional display text "(optional)", which appears next to the label. | ## CSS Shadow Parts | Part | Description | |------------|--------------------------------------------------| | `helpText` | The help text and error message content container. |