Dropdowns¶
Dropdowns are toggleable, contextual overlays for displaying actions related to the content.
Usage¶
They consist of a dropdown toggle and an overlay containing the actions. The overlay is shown after clicking the dropdown toggle. Dropdown are available with text only or with text and icon.
When to use¶
- When there is a need for actions, which are related to each other (e.g. Export: PDF, Excel, Word, ...).
- When users need to make a choice among a list of mutually exclusive options.
Best practices¶
- Minimal button width is
100px. - Menu container should be at least the same width as the button.
Design¶
Elements¶
- Placeholder text, 2. Arrow, 3. Container, 4. menu container, 5. Icon (optional)
Variants¶
Interaction states are identical to the normal buttons.
Code¶
Dropdown menu
If the overlay should show a contextual menu, please use the menu component. It already implements specific keyboard interactions and aria roles that are needed for a dropdown menu.
This chapter describes how to create an interactive contextual overlay using the CDK Overlay module and the CDK Focus trap without special keyboard handling and aria-roles.
The example uses the markup of Bootstrap dropdown. It is also possible to use the CDK directives without using markup related to the dropdown-menu.
The overlay is toggled by the open property which needs to be updated properly. We added a transparent backdrop to the overlay so that we can listen for (backdropClick) which should close the overlay. The listener for (detach) is necessary for updating the open property after escape was pressed. In a real world scenario, one has to be careful here, because (detach) is always called when the overlay is closed.
For having a proper keyboard interaction, we are using the CDK Focus trap. It ensures that the focus will remain within the overlay while it is open. Enabling [cdkTrapFocusAutoCapture]="true" ensures, that the focus will be moved into the overlay on creation and returned to the trigger when the overlay is closed.
CdkConnectedOverlay API Documentation¶
Directive to facilitate declarative creation of an Overlay using a FlexibleConnectedPositionStrategy.
Input Properties¶
| Name | Type | Description |
|---|---|---|
| cdkConnectedOverlayBackdropClass ¶ | (string | string[]) | The custom class to be set on the backdrop element. |
| cdkConnectedOverlayDisableClose ¶ | boolean | Whether the overlay can be closed by user interaction. |
| cdkConnectedOverlayDisposeOnNavigation ¶ | boolean | Whether the overlay should be disposed of when the user goes backwards/forwards in history. |
| cdkConnectedOverlayFlexibleDimensions ¶ | boolean | Whether the overlay's width and height can be constrained to fit within the viewport. |
| cdkConnectedOverlayGrowAfterOpen ¶ | boolean | Whether the overlay can grow after the initial open when flexible positioning is turned on. |
| cdkConnectedOverlayHasBackdrop ¶ | boolean | Whether or not the overlay should attach a backdrop. |
| cdkConnectedOverlayHeight ¶ | (string | number) | The height of the overlay panel. |
| cdkConnectedOverlayLockPosition ¶ | boolean | Whether or not the overlay should be locked when scrolling. |
| cdkConnectedOverlayMinHeight ¶ | (string | number) | The min height of the overlay panel. |
| cdkConnectedOverlayMinWidth ¶ | (string | number) | The min width of the overlay panel. |
| cdkConnectedOverlayOffsetX ¶ | number | The offset in pixels for the overlay connection point on the x-axis |
| cdkConnectedOverlayOffsetY ¶ | number | The offset in pixels for the overlay connection point on the y-axis |
| cdkConnectedOverlayOpen ¶ | boolean | Whether the overlay is open. |
| cdkConnectedOverlayOrigin ¶ | (FlexibleConnectedPositionStrategyOrigin | CdkOverlayOrigin) | Origin for the connected overlay. |
| cdkConnectedOverlayPanelClass ¶ | (string | string[]) | The custom class to add to the overlay pane element. |
| cdkConnectedOverlayPositions ¶ | ConnectedPosition[] | Registered connected position pairs. |
| cdkConnectedOverlayPositionStrategy ¶ | FlexibleConnectedPositionStrategy | This input overrides the positions input if specified. It lets users pass in arbitrary positioning strategies. |
| cdkConnectedOverlayPush ¶ | boolean | Whether the overlay can be pushed on-screen if none of the provided positions fit. |
| cdkConnectedOverlayScrollStrategy ¶ | ScrollStrategy | Strategy to be used when handling scroll events while the overlay is open. |
| cdkConnectedOverlayTransformOriginOn ¶ | string | CSS selector which to set the transform origin. |
| cdkConnectedOverlayViewportMargin ¶ | number | Margin between the overlay and the viewport edges. |
| cdkConnectedOverlayWidth ¶ | (string | number) | The width of the overlay panel. |
Output Properties¶
| Name | Type | Description |
|---|---|---|
| (readonly) attach ¶ | EventEmitter<void> | Event emitted when the overlay has been attached. |
| (readonly) backdropClick ¶ | EventEmitter<MouseEvent> | Event emitted when the backdrop is clicked. |
| (readonly) detach ¶ | EventEmitter<void> | Event emitted when the overlay has been detached. |
| (readonly) overlayKeydown ¶ | EventEmitter<KeyboardEvent> | Emits when there are keyboard events that are targeted at the overlay. |
| (readonly) overlayOutsideClick ¶ | EventEmitter<MouseEvent> | Emits when there are mouse outside click events that are targeted at the overlay. |
| (readonly) positionChange ¶ | EventEmitter<ConnectedOverlayPositionChange> | Event emitted when the position has changed. |
Attributes and Methods¶
| Name | Type | Description |
|---|---|---|
| attachOverlay() ¶ | () => void | Attaches the overlay. |
| detachOverlay() ¶ | () => void | Detaches the overlay. |
| (readonly) dir ¶ | Direction | The element's layout direction. |
| (readonly) overlayRef ¶ | OverlayRef | The associated overlay reference. |
CdkOverlayOrigin API Documentation¶
Directive applied to an element to make it usable as an origin for an Overlay using a ConnectedPositionStrategy.
Attributes and Methods¶
| Name | Type | Description |
|---|---|---|
| elementRef ¶ | ElementRef<any> |
CdkTrapFocus API Documentation¶
Directive for trapping focus within a region.
Input Properties¶
| Name | Type | Description |
|---|---|---|
| cdkTrapFocus ¶ | boolean | Whether the focus trap is active. |
| cdkTrapFocusAutoCapture ¶ | boolean | Whether the directive should automatically move focus into the trapped region upon initialization and return focus to the previous activeElement upon destruction. |
Attributes and Methods¶
| Name | Type | Description |
|---|---|---|
| focusTrap ¶ | FocusTrap | Underlying FocusTrap instance. |
Types Documentation¶
No types to document for items on this page.
Except where otherwise noted, content on this site is licensed under MIT License.