The q2-dropdown element has one or more properties that support text localization. Those properties are indicated by the localizable badge in the description.
blockIf true, component expands to fill the width of its parent element.
contextTells the outlet what the type of object being passed in as contextValue. This will allow for the hierarchy resolution logic to work to determine if an option should or should not be shown.
Only applicable when using <q2-dropdown> for outlets.
contextValuecontext-valuePasses important information to the outlet (e.g., pass an account id that your platform can use to look up what module to show for that account type).
Only applicable when using <q2-dropdown> for outlets.
disabledIndicates the menu cannot be focused or interacted with.
fullWidthfull-widthIf true, it takes up 100% width.
hideLabelhide-labelHides the dropdown's label text from view.
Hides the label visually. label text is still required for screenreader compliance.
hoistInstructs the component to use the action sheet workflow for displaying its options.
For more information, see Action Sheets.
iconThe icon that will render within the toggle button. You may use any of the q2-icon types.
labelThe text that appears within the button.
Required for screen reader compliance even when hideLabel is true.
nameIdentifies this menu as an outlet. Used in conjunction with context and, optionally, contextValue.
Only applicable when using <q2-dropdown> for outlets.
openDetermine whether the popover is open or closed.
optionListLabeloption-list-labelDetermines the label that is applied to the option list for accessibility purposes.
popoverAlignmentpopover-alignmentAligns the popover dropdown to the left or right side of the input field.
popoverDirectionpopover-directionForce the direction of the popover dropdown when it opens. If no value is passed, the component will auto-detect the direction based on available space.
popoverMaxHeightpopover-max-heightForce the maximum height of the popover. This value will be interpreted as pixels. If no value is passed, or the value exceeds available space, the component will auto-detect the maximum height based on available space.
popoverModepopover-modeDetermines the display mode of the popover.
Providing a value of legacy instructs the popover to use absolute positioning instead of fixed positioning.
This is a temporary solution to work around styling issues related to using fixed positioning for the popover when nested inside of elements with transform properties. This will be removed once the popover API is available for use.
resolvedTyperesolved-typeUse with context to tell the outlet where it appears. It will be matched with the appropriately configured module for that context.
Only applicable when using <q2-dropdown> for outlets.
typeThe type of button used as the menu toggle.
Type must be "custom" to use the custom button slot.
The q2-dropdown element exposes methods that can be used to perform various actions on the component.
Gets the outerHTML for top/bottom slotted elements.
_getSlotsHtml() => Promise<{ slot: string; html: string; }[]>Emulates clicking the dropdown <button> to hide the popover if it is showing.
closePopover() => Promise<void>Emulates clicking the dropdown <button> to show the popover if it is hidden.
openPopover() => Promise<void>Emulates opening the dropdown and selecting a Dropdown Item or Option.
If the dropdown is closed, this will open it before selecting the item.
If the value does not match any item's value, or the dropdown is disabled, this method does nothing.
selectItem(value: string) => Promise<void>Emulates opening the dropdown and selecting a Dropdown Item's remove button.
This method only applies to the deprecated q2-dropdown-item element, since
q2-option (its replacement) does not support the removable attribute.
If the dropdown is closed, this will open it before selecting the remove item button.
If the dropdown is disabled, this method does nothing.
Requirements for this method to work properly:
value matches the item's value propertyremovable property enabledselectRemoveItem(value: string) => Promise<void>The q2-dropdown element has multiple slots that can be used to insert custom content into the component.
An optional slot to provide custom content as the clickable interface. The Dropdown must have type="custom" to use the control slot.
An optional slot to display custom content persistently at the bottom of the q2-dropdown.
An optional slot to display custom content persistently at the top of the q2-dropdown.
When using the hoist option on <q2-dropdown>, it is essential to note that your <q2-option> elements must have a value associated with them. Once you make a selection in the action sheet, the value is what Tecton uses to find the original option and click it, thereby triggering your event listener.
<q2-dropdown
type="primary"
label="Hoisted Demo"
icon="options"
hoist
>
<q2-option
value="item-1"
onclick="console.log('item-1 selected')"
>
One
</q2-option>
<q2-option
value="item-2"
onclick="console.log('item-2 selected')"
>
Two
</q2-option>
<q2-option
value="item-3"
onclick="console.log('item-3 selected')"
>
Three
</q2-option>
</q2-dropdown>
This behavior belongs to the shared Action Sheet. Dropdown forwards its top and bottom slot HTML to that component; other hoist integrations must also forward slot HTML to support the marker.
By default, only the options scroll in an action sheet. To let a large profile header scroll away on a short screen, add data-action-sheet-scroll to the root element of either the popover-top or popover-bottom slot:
<q2-dropdown hoist label="Profile">
<div slot="popover-top" data-action-sheet-scroll>
<div>Alex Example</div>
<div>alex@example.com</div>
</div>
<q2-option value="profile">View profile</q2-option>
<q2-option value="logout">Log off</q2-option>
</q2-dropdown>
On top slots, the first marker starts the scroll area: that slot and all following top slots scroll with the options. Earlier top slots remain fixed. Bottom slots through the last marker scroll with the options; later bottom slots stay fixed. The action-sheet title, close button, and Done button (for multiple selection) remain fixed. Desktop popover behavior is unchanged.
Only attribute presence matters; any value, including "false", enables the marker. Remove the attribute to remove a boundary. After a top marker, later top slots still scroll regardless of their marker. Marking a nested child has no effect. Fixed top slots appear above the scroll area, and scrolling top slots appear inside it before the options. Scrolling bottom slots follow the options inside the scroll area; fixed bottom slots appear outside it after the Done button. Order is preserved within each group.
The Dropdown component exposes a slot - control - for the developer to provide their own element as the clickable interface for the Dropdown.
The Dropdown must have type="custom" to use the control slot
<q2-dropdown type="custom" label="My dropdown" popover-alignment="left">
<q2-avatar slot="control" icon="person">
</q2-avatar>
<q2-option value="first">First</q2-option>
<q2-option value="second">Second</q2-option>
<q2-option separator="true">
</q2-option>
<q2-option value="third">Third</q2-option>
<q2-option value="fourth">Fourth</q2-option>
</q2-dropdown>
The following CSS variables are available to override the default theme styles of the q2-dropdown component.
Many Tecton components consume other components to maintain visual and functional consistency. If you are looking for a CSS variable you think should exist but are not seeing it, it may be defined in one of the dependent components below. Either way, if you think it's something we should expose more conveniently, let us know!
This component uses other components in the Tecton library, including:
q2-dropdown-itemclick-elsewhereq2-btnq2-iconq2-popoverq2-option-listThe changelog provides a detailed history of new features, improvements, and bug fixes going back to Tecton 1.30.0. If the button is disabled, it indicates there have been no detectable changes since then.