# auro-dropdown The `auro-dropdown` element provides a way to place content in a bib that can be toggled. ## Properties | Property | Attribute | Type | Default | Description | |---------------------------|---------------------------|--------------------------------------------------|------------------|--------------------------------------------------| | `a11yRole` | | `string` | | The value for the role attribute of the trigger element. | | [appearance](#appearance) | `appearance` | `'default' \| 'inverse'` | "'default'" | Defines whether the component will be on lighter or darker backgrounds. | | [autoPlacement](#autoPlacement) | `autoPlacement` | `boolean` | | If declared, bib's position will be automatically calculated where to appear. | | [chevron](#chevron) | `chevron` | `boolean` | | If declared, the dropdown displays a chevron on the right. | | [disableEventShow](#disableEventShow) | `disableEventShow` | `boolean` | | If declared, the dropdown will only show by calling the API .show() public method. | | [disableKeyboardHandling](#disableKeyboardHandling) | `disableKeyboardHandling` | `boolean` | | If declared, the dropdown will not handle keyboard events and will require the consumer to manage this behavior. | | [disabled](#disabled) | `disabled` | `boolean` | | If declared, the dropdown is not interactive. | | [error](#error) | `error` | `boolean` | | If declared, will apply error UI to the dropdown. | | [errorMessage](#errorMessage) | `errorMessage` | `string` | "undefined" | Contains the help text message for the current validity error. | | [focusShow](#focusShow) | `focusShow` | `boolean` | | If declared, the bib will display when focus is applied to the trigger. | | [fullscreenBreakpoint](#fullscreenBreakpoint) | `fullscreenBreakpoint` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'disabled'` | "'sm'" | Defines the screen size breakpoint at 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. | | [hoverToggle](#hoverToggle) | `hoverToggle` | `boolean` | | If declared, the trigger will toggle the dropdown on mouseover/mouseout. | | [isBibFullscreen](#isBibFullscreen) | `isBibFullscreen` | `boolean` | false | If true, the dropdown bib is taking the fullscreen when it's open. | | [isPopoverVisible](#isPopoverVisible) | `open` | `boolean` | false | If true, the dropdown bib is displayed. | | [layout](#layout) | `layout` | `'classic' \| 'emphasized' \| 'snowflake'` | "'classic'" | Sets the layout of the dropdown. | | [matchWidth](#matchWidth) | `matchWidth` | `boolean` | false | If declared, the popover and trigger will be set to the same width. | | [noFlip](#noFlip) | `noFlip` | `boolean` | | If declared, the bib will NOT flip to an alternate position
when there isn't enough space in the specified `placement`. | | [noHideOnThisFocusLoss](#noHideOnThisFocusLoss) | `noHideOnThisFocusLoss` | `boolean` | false | If declared, the dropdown will not hide when moving focus outside the element. | | [noToggle](#noToggle) | `noToggle` | `boolean` | | If declared, the trigger will only show the dropdown bib. | | [offset](#offset) | `offset` | `number` | "0" | Gap between the trigger element and bib. | | [onDark](#onDark) | `onDark` | `boolean` | | DEPRECATED - use `appearance="inverse"` instead. | | [onSlotChange](#onSlotChange) | `onSlotChange` | | | If declared, and a function is set, that function will execute when the slot content is updated. | | [placement](#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. | | [shape](#shape) | | | "undefined" | | | [shift](#shift) | `shift` | `boolean` | | If declared, the dropdown will shift its position to avoid being cut off by the viewport. | | [simple](#simple) | `simple` | `boolean` | | If declared, applies a border around the trigger slot. | | [size](#size) | | | "undefined" | | ## Methods | Method | Type | Description | |------------------|------------|--------------------------------------------------| | [exposeCssParts](#exposeCssParts) | `(): void` | Exposes CSS parts for styling from parent components. | | [focus](#focus) | `(): void` | When bib is open, focus on the first element inside of bib.
If not, trigger element will get focus. | | [hide](#hide) | `(): void` | Public method to hide the dropdown. | | [show](#show) | `(): void` | Public method to show the dropdown. | ## Events | Event | Type | Description | |-----------------------------|--------------------------------------|--------------------------------------------------| | `auroDropdown-idAdded` | `Object` | Notifies consumers that the unique ID for the dropdown bib has been generated. | | `auroDropdown-toggled` | | Notifies that the visibility of the dropdown bib has changed. | | `auroDropdown-triggerClick` | `CustomEvent` | Notifies that the trigger has been clicked. | ## Slots | Name | Description | |------------|--------------------------------------------| | | Default slot for the dropdown bib content. | | [helpText](#helpText) | Defines the content of the helpText. | | [trigger](#trigger) | Defines the content of the trigger. | ## CSS Shadow Parts | Part | Description | |------------|--------------------------------------------------| | [chevron](#chevron) | The collapsed/expanded state icon container. | | [helpText](#helpText) | The helpText content container. | | [size](#size) | The size of the dropdown bib. (height, width, maxHeight, maxWidth only) | | [trigger](#trigger) | The trigger content container. | ## Basic The following examples demonstrate basic usage of the `auro-dropdown` component with different types of trigger content. ### Text

Lorem ipsum solar

Trigger

See code ```html Lorem ipsum solar

Trigger

```

Lorem ipsum solar

Trigger

### Icon

Lorem ipsum solar

See code ```html Lorem ipsum solar

``` ### Button

Lorem ipsum solar

Dropdown

See code ```html Lorem ipsum solar

Dropdown

``` ## Property & Attribute Examples ### Appearance on Dark Backgrounds Use the `appearance="inverse"` attribute to ensure proper styling when the dropdown is used on dark backgrounds.

Lorem ipsum solar

Trigger

See code ```html Lorem ipsum solar

Trigger

``` ### Chevron Use the `chevron` attribute to add a chevron icon to the dropdown trigger.

Lorem ipsum solar

Trigger

See code ```html Lorem ipsum solar

Trigger

``` ### Disabled Use the `disabled` attribute to disable interaction with the dropdown.

Lorem ipsum solar

Trigger

Help text Name

Lorem ipsum solar

Trigger

Help text Name

See code ```html Lorem ipsum solar

Trigger

Help text Name ``` ```html Lorem ipsum solar

Trigger

Help text Name ``` ### Error Use the `error` attribute to set persistent error state styling on the dropdown.

Lorem ipsum solar

Dismiss Dropdown

Help text Element label (default text will be read by screen reader)

Trigger

Lorem ipsum solar

Dismiss Dropdown

Help text Element label (default text will be read by screen reader)

Trigger

See code ```html

Lorem ipsum solar

Dismiss Dropdown

Help text Element label (default text will be read by screen reader)

Trigger

``` ```html

Lorem ipsum solar

Dismiss Dropdown

Help text Element label (default text will be read by screen reader)

Trigger

``` ### Fullscreen Bib You can make the dropdown open in fullscreen at a specific breakpoint by setting `fullscreenBreakpoint`. The default value of `fullscreenBreakpoint` is `sm`. Breakpoint token can be found [here](https://auro.alaskaair.com/getting-started/developers/design-tokens).

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Dismiss Dropdown

Trigger

See code ```html

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Dismiss Dropdown

Trigger

``` ### Layouts The `auro-dropdown` element supports multiple layouts to fit different design needs. The available layouts are: `classic`, `emphasized`, and `snowflake`. Each layout offers a unique visual style while maintaining the same core functionality. **Important**: The `emphasized` and `snowflake` layouts are designed specifically for dark backgrounds and should be used with the `appearance="inverse"` attribute. #### Classic

Lorem ipsum solar

Dismiss Dropdown

Help text

Trigger

See code ```html

Lorem ipsum solar

Dismiss Dropdown

Help text

Trigger

```

Lorem ipsum solar

Dismiss Dropdown

Help text

Trigger

See code ```html

Lorem ipsum solar

Dismiss Dropdown

Help text

Trigger

``` #### Emphasized

Lorem ipsum solar

Trigger

Help text - Lorem ipsum solar lorem ipsum solar

Lorem ipsum solar

Trigger

Help text - Lorem ipsum solar lorem ipsum solar

Lorem ipsum solar

Trigger

Help text - Lorem ipsum solar lorem ipsum solar

See code ```html Lorem ipsum solar

Trigger

Help text - Lorem ipsum solar lorem ipsum solar

Lorem ipsum solar

Trigger

Help text - Lorem ipsum solar lorem ipsum solar

Lorem ipsum solar

Trigger

Help text - Lorem ipsum solar lorem ipsum solar ``` #### Snowflake

Lorem ipsum solar

Trigger

Help text - Lorem ipsum solar lorem ipsum solar

See code ```html Lorem ipsum solar

Trigger

Help text - Lorem ipsum solar lorem ipsum solar ``` ### Customized Bib Position The bib position can be customized with `placement`, `offset`, `flip`, `autoPlacement`, and `shift` attributes. - `placement` specifies the preferred position where the bib should appear relative to the trigger. - `offset` sets the distance between the trigger and the bib. - When `autoPlacement` is enabled, smart positioning logic is applied to determine the best placement for the bib. If all sides have sufficient space, the bib will appear in the position specified by `placement`. - Unless `noFlip` is enabled, if there isn't enough space for the preferred `placement`, the bib will automatically flip to an alternative position. - `shift` when enabled, adjusts the bib position when it would overflow the viewport boundaries, ensuring it remains visible.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Trigger

Trigger for bottom-end bib with 20px offset and noFlip

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Trigger

Trigger for bottom-end bib with 20px offset and flip

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Trigger

Trigger for right bib with 20px offset and noFlip

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Trigger

Trigger for bottom-start bib with 20px offset, shift and noFlip

See code ```html

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Trigger

Trigger for bottom-end bib with 20px offset and noFlip

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Trigger

Trigger for bottom-end bib with 20px offset and flip

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Trigger

Trigger for right bib with 20px offset and noFlip

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Trigger

Trigger for bottom-start bib with 20px offset, shift and noFlip

``` ### Match Width When the `matchWidth` attribute is applied, the width of the dropdown bib will match the width of the trigger element.

Lorem ipsum solar

Dismiss Dropdown

Help text

Trigger

See code ```html

Lorem ipsum solar

Dismiss Dropdown

Help text

Trigger

``` ### No Toggle In cases where it is desired behavior for `auro-dropdown` to only show, not toggle, the bib content when activating the trigger the `noToggle` attribute must be applied.

Lorem ipsum solar

Trigger

See code ```html Lorem ipsum solar

Trigger

``` ## Method Examples ### Hide The `hide()` method can be called from within the default slot content. This is useful for cases such as `auro-select` when the dropdown should be collapsed after making a selection. The `hide()` method may also be called from anywhere in your code by executing `document.querySelector('#idOfTheDropdownElement').hide()`. This example demonstrations collapsing the dropdown by clicking a button within the dropdown bib content.

Lorem ipsum solar

Hide Dropdown

Trigger

See code ```html

Lorem ipsum solar

Hide Dropdown

Trigger ``` ```js export function hideExample() { const btn = document.querySelector('#hideExampleBtn'); const dropdown = document.querySelector('#hideExample'); btn?.addEventListener('click', () => { dropdown?.hide(); }); } ``` ### Show The `show()` method may also be called from anywhere in your code by executing `document.querySelector('#idOfTheDropdownElement').show()`. This example will execute the `show()` method on a `keydown` event with focus in the input element.

Enter a value to show the dropdown

Lorem ipsum solar

Trigger Label

See code ```html Enter a value to show the dropdown

Lorem ipsum solar

Trigger Label ``` ```js export function showExample() { const triggerInput = document.querySelector('#showExampleTriggerInput'); const dropdownElem = document.querySelector('#showMethodExample'); triggerInput?.addEventListener('keydown', () => { dropdownElem?.show(); }); } ``` ## Slot Examples ### Help Text Content defined in the `helpText` slot will be rendered left aligned below the trigger. This slot requires the `auro-helptext` component be used as slot content for the helptext to render with the same styles as other form elements.

Lorem ipsum solar Helper text

Trigger

See code ```html Lorem ipsum solar Helper text

Trigger

``` ### Trigger Content defined in the `trigger` slot will be rendered in the clickable trigger of the dropdown that is used to display the bib. Focus state visual effects will be disabled on the trigger when it contains a focusable element other than ``. This slot may contain any static content (e.g. plain text) and/or no more than one of the following elements: - `` - `` - `