Dropdown

Updated:

Used to provide a menu of contextual actions.

Events are emitted from Q2 Dropdown Item, not Q2 Dropdown.

Using Hoist

When using the hoist option on <q2-dropdown>, it is essential to note that your <q2-dropdown-item> 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.

One Two Three
<q2-dropdown 
  type="primary"
  label="Hoisted Demo" 
  icon="options"
  hoist
>
  <q2-dropdown-item
    value="item-1"
    onclick="console.log('item-1 selected')"
  >
    One
  </q2-dropdown-item>
  <q2-dropdown-item 
    value="item-2"
    onclick="console.log('item-2 selected')"
  >
    Two
  </q2-dropdown-item>
  <q2-dropdown-item 
    value="item-3"
    onclick="console.log('item-3 selected')"
  >
    Three
  </q2-dropdown-item>
</q2-dropdown>

Control Slot

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

Example

First Second Third Fourth
<q2-dropdown type="custom" label="My dropdown" popover-alignment="left">
  <q2-avatar slot="control" icon="person">
  </q2-avatar>
  <q2-dropdown-item value="first" removable="false">First</q2-dropdown-item>
  <q2-dropdown-item value="second" removable="false">Second</q2-dropdown-item>
  <q2-dropdown-item separator="true">
  </q2-dropdown-item>
  <q2-dropdown-item value="third" removable="false">Third</q2-dropdown-item>
  <q2-dropdown-item value="fourth" removable="false">Fourth</q2-dropdown-item>
</q2-dropdown>

Slots

The q2-dropdown element has one slot that can be used to insert custom content into the component.

Learn more about slots

An optional slot to provide custom content as the clickable interface. The Dropdown must have type="custom" to use the control slot.

Properties

The q2-dropdown element has one or more properties that support text localization. Those properties are indicated by the localizable badge in the description.

Learn more about properties.

block

If true, component expands to fill the width of its parent element.

context

Tells 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.

contextValue
context-value

Passes 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.

disabled

Indicates the menu cannot be focused or interacted with.

hideLabel
hide-label

Hide's the field's <label> element from view.

Only use when a visible label is impractical.

hoist

Instructs the component to use the action sheet workflow for displaying its options.

For more information, see Action Sheets.

icon

The icon that will render within the toggle button. You may use any of the q2-icon types.

label

The text that appears within the button.

This property should not be used if the type is icon.

Localizable
name

Identifies this menu as an outlet. Used in conjunction with context and, optionally, contextValue.

Only applicable when using <q2-dropdown> for outlets.

open

Determine whether the popover is open or closed.

optionListLabel
option-list-label

Determines the label that is applied to the option list for accessibility purposes.

popoverAlignment
popover-alignment

Aligns the popover dropdown to the left or right side of the input field.

popoverDirection
popover-direction

Force 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.

popoverMaxHeight
popover-max-height

Force 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.

popoverMode
popover-mode

Determines 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.

resolvedType
resolved-type

Use 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.

type

The type of button used as the menu toggle.

Type must be "custom" to use the custom button slot.

Methods

The q2-dropdown element exposes methods that can be used to perform various actions on the component.

Learn more about methods.

closePopover

Test only

Emulates clicking the dropdown <button> to hide the popover if it is showing.

Type signature

closePopover() => Promise<void>

openPopover

Test only

Emulates clicking the dropdown <button> to show the popover if it is hidden.

Type signature

openPopover() => Promise<void>

selectItem

Test only

Emulates opening the dropdown and selecting a Dropdown Item.

If the dropdown is closed, this will open it before selecting the item.

If the value does not match any item's value, this method does nothing.

Type signature

selectItem(value: string) => Promise<void>

selectRemoveItem

Test only

Emulates opening the dropdown and selecting a Dropdown Item's remove button.

If the dropdown is closed, this will open it before selecting the remove item button.

Requirements for this method to work properly:

  • Provided value matches the item's value property
  • Item has the removable property enabled

Type signature

selectRemoveItem(value: string) => Promise<void>

Release Notes

Initial Release

Accessibility Report

Tecton components are designed and tested to be WCAG compliant when used appropriately, and do not get released without proper validation. Developers should prefer not to set ARIA attributes when using components from the Tecton Design System.

The following CSS variables are available to override the default theme styles of the q2-dropdowncomponent.

Dependencies

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!

  • q2-dropdown-item
  • q2-btn
  • q2-icon
  • There is 1 frequently asked question related to this page.