Dropdown
Use when
Use dropdowns when users require access to multiple, related actions or when users require access to multiple, unrelated actions and you do not have room for multiple buttons.
Use context-menu dropdowns when actions affect individual items in a list.
For details on when to include a delete action in a context-menu dropdown, see the manage data guidelines.
Use icon-only dropdowns when you do not have room for text labels. For example, use icon-only dropdowns in list toolbars when screen widths are narrow.
Don't use when
Don't use dropdowns as form inputs. Use HTML <select>
Button types
| Default |  |
| Icon and text |  |
| Context menu |  |
| Icon only |  |
Button styles
Dropdown buttons can use the default or primary styles inherited from SKY UX buttons. For details about when to use the primary style, see the primary action guidelines.
Behavior
The popover component defines the behavior of dropdown menus.
States
Dropdown buttons inherit the styling for states such as hover and disabled from SKY UX buttons.
Dropdown menu action text
For actions that clearly apply to the object associated with the context menu, use the following format for the action wording:
<Verb>
For dropdown buttons with one type of action, use the following format:
Button text: <Verb>
Menu item: <Direct object>
For dropdown buttons with more than one type of action, use the following format:
Button icon: sky-i-ellipsis
Button text: More
Menu item: <Verb> <direct object>
In addition, follow these guidelines for button text:
- Use sentence-style capitalization.
- Use singular direct objects for actions that apply to one item and plural direct objects for actions that apply to multiple items.
- Don't append extra words such as “details.” For example, use “Edit constituent” rather than “Edit constituent details.”
Placement
Place context-menu dropdowns to the left of all row-specific content but to the right of all list controls, such as expand-collapse actions in tree views and checkboxes in grids or repeaters.
Default dropdowns are positioned with the same alignment and margins as SKY UX buttons.
Menu items
Organize menu items to place the most important or frequently used options at the top of the list and the least important or least frequently used items at the bottom.
Components
Guidelines
- NPM package
@skyux/popoversView in NPM | View in GitHub None found.- Install with NPM
npm install --save-exact @skyux/popoversNone found.
import { SkyDropdownModule } from '@skyux/popovers';
Selector: sky-dropdown
Creates a dropdown menu that displays menu items that users may select.
Inputs
buttonStyle: string
The background color for the dropdown button. Available values are default,
primary, and link. These values set the background color and hover behavior from the
secondary and primary button classes respectively.
Default: "default"
buttonType: SkyDropdownButtonType
The type of button to render as the dropdown's trigger element. To display a button
with a caret, specify 'select' and render the button text or icon in a
sky-dropdown-button element. To display a round button with an ellipsis, specify
'context-menu'.
Default: "select"
disabled: boolean | undefined
Whether to disable the dropdown button.
Default: false
horizontalAlignment: SkyDropdownHorizontalAlignment
The horizontal alignment of the dropdown menu in relation to the dropdown button.
Default: "left"
label: string | undefined
The ARIA label for the dropdown. This sets the dropdown's aria-label attribute to provide a text equivalent for screen readers
to support accessibility. If multiple dropdowns with no label or the same label appear on the same page,
they must have unique ARIA labels that provide context, such as "Context menu for Robert Hernandez" or "Edit Robert Hernandez."
For more information about the aria-label attribute, see the WAI-ARIA definition.
title: string | undefined
The title to display in a tooltip when users hover the mouse over the dropdown button.
trigger: SkyDropdownTriggerType
How users interact with the dropdown button to expose the dropdown menu.
We recommend the default click value because the hover value can pose
accessibility issues
for users on touch devices such as phones and tablets.
Default: "click"
Selector: sky-dropdown-button
Specifies the button for the dropdown menu.
Selector: sky-dropdown-menu
Creates a menu that contains dropdown menu items.
Inputs
ariaLabelledBy: string | undefined
The HTML element ID of the element that labels
the dropdown menu. This sets the dropdown menu's aria-labelledby attribute to provide a text equivalent for
to support accessibility.
For more information about the aria-labelledby attribute, see the WAI-ARIA definition.
ariaRole: string
The ARIA role for the dropdown menu
to support accessibility
by indicating how the dropdown menu functions and what it controls. The dropdown button
inherits this value to set its aria-haspopup property. For information
about how an ARIA role indicates what an item represents on a web page, see the
WAI-ARIA roles model.
Default: "menu"
Selector: sky-dropdown-item
Specifies the items to display on the dropdown menu.
Inputs
ariaRole: string
The ARIA role for the dropdown menu item to support accessibility by indicating how the item functions and what it controls. For information about how an ARIA role indicates what an item represents on a web page, see the WAI-ARIA roles model.
Default: "menuitem"
type SkyDropdownButtonType = "select" | "context-menu" | "tab"
The horizontal alignment for the dropdown.
type SkyDropdownHorizontalAlignment = "left" | "center" | "right"
How users interact with the dropdown button to expose the dropdown menu.
type SkyDropdownTriggerType = "click" | "hover"SKY UX test harnesses are built upon Angular CDK component harnesses. For more information see the Angular CDK component harness documentation.
import { SkyDropdownHarness } from '@skyux/popovers/testing';
Harness for interacting with a dropdown component in tests.
Methods
clickDropdownButton(): Promise<void>
Clicks the dropdown button.
Returns
Promise<void>
getAriaLabel(): Promise<null | string>
Gets the aria-label value.
Returns
Promise<null | string>
getButtonStyle(): Promise<string>
Gets the dropdown button style.
Returns
Promise<string>
getButtonType(): Promise<string>
Gets the dropdown button type.
Returns
Promise<string>
getDropdownMenu(): Promise<SkyDropdownMenuHarness>
getTitle(): Promise<null | string>
Gets the hover tooltip text.
Returns
Promise<null | string>
isDisabled(): Promise<boolean>
Gets whether the dropdown is disabled.
Returns
Promise<boolean>
isOpen(): Promise<boolean>
Gets whether the dropdown menu is open.
Returns
Promise<boolean>
SkyDropdownHarness.with(filters: SkyDropdownHarnessFilters): HarnessPredicate<SkyDropdownHarness>
Gets a HarnessPredicate that can be used to search for a
SkyDropdownHarness that meets certain criteria.
Parameters
filters: SkyDropdownHarnessFilters
Returns
HarnessPredicate<SkyDropdownHarness>
A set of criteria that can be used to filter a list of SkyDropdownHarness instances.
interface SkyDropdownHarnessFilters {
dataSkyId?: string | RegExp;
}Properties
dataSkyId?: string | RegExp
Only find instances whose data-sky-id attribute matches the given value.
import { SkyDropdownItemHarness } from '@skyux/popovers/testing';
Harness for interacting with a dropdown item component in tests.
Methods
click(): Promise<void>
Clicks the dropdown item.
Returns
Promise<void>
getAriaRole(): Promise<null | string>
Gets the dropdown item role.
Returns
Promise<null | string>
getText(): Promise<null | string>
Gets the menu item text.
Returns
Promise<null | string>
SkyDropdownItemHarness.with(filters: SkyDropdownItemHarnessFilters): HarnessPredicate<SkyDropdownItemHarness>
Gets a HarnessPredicate that can be used to search for a
SkyDropdownItemHarness that meets certain criteria.
Parameters
filters: SkyDropdownItemHarnessFilters
Returns
HarnessPredicate<SkyDropdownItemHarness>
A set of criteria that can be used to filter a list of SkyDropdownItemHarness instances.
interface SkyDropdownItemHarnessFilters {
ariaRole?: string;
dataSkyId?: string | RegExp;
text?: string;
}Properties
ariaRole?: string
Only find instances whose role matches the given value.
dataSkyId?: string | RegExp
Only find instances whose data-sky-id attribute matches the given value.
text?: string
Only find instances whose text content matches the given value.
import { SkyDropdownMenuHarness } from '@skyux/popovers/testing';
Harness for interacting with a dropdown menu component in tests.
Methods
clickOut(): Promise<void>
Clicks out of the dropdown menu.
Returns
Promise<void>
getAriaLabelledBy(): Promise<null | string>
Gets the aria-labelledby value.
Returns
Promise<null | string>
getAriaRole(): Promise<null | string>
Gets the dropdown menu role.
Returns
Promise<null | string>
getItem(filters: SkyDropdownItemHarnessFilters): Promise<SkyDropdownItemHarness>
Gets the first item that matches the given filters
Parameters
filters: SkyDropdownItemHarnessFilters
filter for which menu item to return
Returns
Promise<SkyDropdownItemHarness>
getItems(filters?: SkyDropdownItemHarnessFilters): Promise<SkyDropdownItemHarness[]>
Gets an array of dropdown menu item harnesses.
Parameters
filters?: SkyDropdownItemHarnessFilters
Optional filter for which menu items to return
Returns
Promise<SkyDropdownItemHarness[]>
queryHarness(query: HarnessQuery<T>): Promise<T>
Returns a child harness or throws an error if not found.
Parameters
query: HarnessQuery<T>
Returns
Promise<T>
queryHarnesses(harness: HarnessQuery<T>): Promise<T[]>
Returns child harnesses.
Parameters
harness: HarnessQuery<T>
Returns
Promise<T[]>
queryHarnessOrNull(query: HarnessQuery<T>): Promise<null | T>
Returns a child harness or null if not found.
Parameters
query: HarnessQuery<T>
Returns
Promise<null | T>
querySelector(selector: string): Promise<TestElement>
Returns a child test element or throws an error if not found.
Parameters
selector: string
Returns
Promise<TestElement>
querySelectorAll(selector: string): Promise<TestElement[]>
Returns child test elements.
Parameters
selector: string
Returns
Promise<TestElement[]>
querySelectorOrNull(selector: string): Promise<null | TestElement>
Returns a child test element or null if not found.
Parameters
selector: string
Returns
Promise<null | TestElement>
SkyDropdownMenuHarness.with(filters: SkyDropdownMenuHarnessFilters): HarnessPredicate<SkyDropdownMenuHarness>
Gets a HarnessPredicate that can be used to search for a
SkyDropdownMenuHarness that meets certain criteria.
Parameters
filters: SkyDropdownMenuHarnessFilters
Returns
HarnessPredicate<SkyDropdownMenuHarness>
A set of criteria that can be used to filter a list of SkyDropdownMenuHarness instances.
interface SkyDropdownMenuHarnessFilters {
dataSkyId?: string | RegExp;
}Properties
dataSkyId?: string | RegExp
Only find instances whose data-sky-id attribute matches the given value.
Loading...