# gds-dropdown **Class**: `GdsDropdown` **Tag**: `` ## Properties > Some properties accept design token names. Use `get_tokens` with the appropriate category to discover valid token names and their resolved values. | Name | Type | Default | Description | |------|------|---------|-------------| | `width` | `string \| undefined` | `-` | Style Expression Property that controls the `width` property. Supports space tokens and all valid CSS `width` values. | | `'min-width'` | `string \| undefined` | `-` | Style Expression Property that controls the `min-width` property. Supports space tokens and all valid CSS `min-width` values. | | `'max-width'` | `string \| undefined` | `-` | Style Expression Property that controls the `max-width` property. Supports space tokens and all valid CSS `max-width` values. | | `'inline-size'` | `string \| undefined` | `-` | Style Expression Property that controls the `inline-size` property. Supports space tokens and all valid CSS `inline-size` values | | `'min-inline-size'` | `string \| undefined` | `-` | Style Expression Property that controls the `min-inline-size` property. Supports space tokens and all valid CSS `min-inline-size` values. | | `'max-inline-size'` | `string \| undefined` | `-` | Style Expression Property that controls the `max-inline-size` property. Supports space tokens and all valid CSS `max-inline-size` values. | | `margin` | `string \| undefined` | `-` | Style Expression Property that controls the `margin` property. Only accepts space tokens. | | `'margin-inline'` | `string \| undefined` | `-` | Style Expression Property that controls the `margin-inline` property. Only accepts space tokens. | | `'margin-block'` | `string \| undefined` | `-` | Style Expression Property that controls the `margin-block` property. Only accepts space tokens. | | `'align-self'` | `string \| undefined` | `-` | Style Expression Property that controls the `align-self` property. Supports all valid CSS `align-self` values. | | `'justify-self'` | `string \| undefined` | `-` | Style Expression Property that controls the `justify-self` property. Supports all valid CSS `justify-self` values. | | `'place-self'` | `string \| undefined` | `-` | Style Expression Property that controls the `place-self` property. Supports all valid CSS `place-self` values. | | `'grid-column'` | `string \| undefined` | `-` | Style Expression Property that controls the `grid-column` property. Supports all valid CSS grid-column values. Documentation: https://developer.mozilla.org/en-US/docs/Web/CSS/grid-column | | `'grid-row'` | `string \| undefined` | `-` | Style Expression Property that controls the `grid-row` property. Supports all valid CSS `grid-row` values. | | `'grid-area'` | `string \| undefined` | `-` | Style Expression Property that controls the `grid-area` property. Supports all valid CSS `grid-area` values. | | `flex` | `string \| undefined` | `-` | Style Expression Property that controls the `flex` property. Supports all valid CSS `flex` values. | | `order` | `string \| undefined` | `-` | Style Expression Property that controls the `order` property. Supports all valid CSS `order` values. | | `supportingText` | `string` | `-` | The supporting text displayed between the label and the field itself. | | `open` | `boolean` | `-` | Sets the open state of the dropdown. | | `searchable` | `boolean` | `-` | Whether the dropdown should be searchable. | | `multiple` | `boolean` | `-` | Whether the dropdown should support multiple selections. When set to true, the dropdown will render a checkbox next to each option. The value of the dropdown will be an array of the selected values. | | `clearable` | `boolean` | `-` | Whether the dropdown should be clearable. | | `combobox` | `boolean` | `-` | Whether the dropdown should be rendered as a combobox. When set to true, the dropdown will render an input field instead of a button. The value of the dropdown will be a string representing the selected value. | | `compareWith` | `(a: unknown, b: unknown) => boolean` | `-` | Delegate function for comparing option values. By default the option values are compared using strict equality. If you want to compare objects by field values, you can provide a custom compare function here. The function should return true if the values are considered equal. Example: ```ts dropdown.compareWith = (a, b) => a.id === b.id ``` | | `searchFilter` | `(q: string, o: GdsOption) => boolean` | `-` | Delegate function for customizing the search filtering. By default, the search filter will just check if the option label contains the search string using [String.includes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/includes). This property allows you to provide a custom filter function to use instead. For example, to filter on value instead of label: ```ts dropdown.searchFilter = (query, option) => option.value.toLowerCase().includes(query.toLowerCase()) ``` | | `syncPopoverWidth` | `boolean` | `-` | Whether the popover should sync its width to the trigger button. When this is set to `true`, the popover will always have the same width as the trigger button. By default, line-breaks will be applied to the option content if it is wider than the popover width. If you use this option, make sure to verify that your options are still readable and apply appropriate custom layout or truncation if neccecary. | | `maxHeight` | `number` | `-` | Maximum height of the dropdown list. | | `size` | `'medium' \| 'small'` | `-` | Size of the dropdown. Supports `medium` and `small`. There is no `large` size for dropdowns. `medium` is the default size. | | `hideLabel` | `boolean` | `-` | Whether to hide the label. | | `plain` | `boolean` | `-` | Hides the header and the footer, while still keeping the accessible label Always set the `label` attribute, and if you need to hide it, add this attribute and keep `label` set. | | `disableMobileStyles` | `boolean` | `-` | Whether to disable the mobile styles. | | `showExtendedSupportingText` | `boolean` | `-` | Whether the supporting text should be displayed or not. | | `validator` | `GdsValidator \| undefined` | `-` | A validator that can be used to validate the form control and set an error message. | | `required` | `boolean` | `-` | The required attribute can be used to communicate to users of assistive technology that the control is required. Validation still needs to be done in a validator or equivalent. | | `errorMessage` | `string` | `-` | This can be used to manually control the error message that will be displayed when the control is invalid. | | `invalid` | `any` | `-` | Validation state of the form control. Setting this to true triggers the invalid state of the control. | | `label` | `string` | `-` | The label of the form control. | | `value` | `any` | `-` | Get or set the value of the form control. | | `name` | `string` | `-` | | | `disabled` | `boolean` | `-` | If the input is Disabled | | `syncFirstRender` | `boolean` | `-` | Force the element to perform a synchronous first render and apply style expression properties in `connectedCallback`. This guarantees that the child DOM always remains projected in DOM, since the element will attach the shadowRoot and run the first render pass in the same event loop cycle, and that declarative layout will be applied once slotted DOM is projected. Note: This will cause the first render pass to be blocking. Use sparingly and only when necessary, such as when the element needs to be measured synchronously after being added to the DOM. | ## Events | Name | Type | Description | |------|------|-------------| | `change` | `Event` | Fired when the value of the dropdown is changed through user interaction (not when value prop is set programatically). | | `input` | `InputEvent` | Fired when the value of the dropdown is changed through user interaction. | | `gds-ui-state` | `CustomEvent` | Fired when the dropdown is opened or closed by the user. Can be cancelled to prevent the dropdown from opening or closing. | | `gds-filter-input` | `CustomEvent` | Fired when the user types in the search field. The event is cancellable, and the consumer is expected to handle filtering and updating the options list if the event is cancelled. | | `gds-input-cleared` | `CustomEvent` | Fired when the user clears the input using the clear button. | ## Slots | Name | Description | |------|-------------| | `(default)` | Options for the dropdown. Accepts `gds-option` and `gds-menu-heading` elements. | | `trigger` | Custom content for the trigger button can be assigned through this slot. | | `extended-supporting-text` | A longer supporting text can be placed here. It will be displayed in a panel when the user clicks the info button. | | `message` | ***(deprecated - use `errorMessage` property instead)*** Error message to show below the input field whem there is a validation error. | | `sub-label` | ***(deprecated - use `supporting-text` property instead)*** Renders between the label and the trigger button. | ## Form Control This component is a form control and inherits form-related properties and methods. ## Related Components This component is designed to work with the following child components: - **`gds-option`** - Defines an option in the dropdown - **`gds-menu-heading`** - Defines a non-selectable heading in the dropdown options list ### Usage Example ```html ... ... ```