diff --git a/docs/components/buttons-menus/dropdowns.md b/docs/components/buttons-menus/dropdowns.md
index 151a3b10d7..01eaa765e8 100644
--- a/docs/components/buttons-menus/dropdowns.md
+++ b/docs/components/buttons-menus/dropdowns.md
@@ -42,23 +42,150 @@ Interaction states are identical to the [normal buttons](buttons.md).
If the overlay should show a contextual menu, please use the [menu component](menu.md).
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](https://material.angular.io/cdk/overlay/overview) and the [CDK Focus trap](https://material.angular.io/cdk/a11y/overview#focustrap)
-without special keyboard handling and aria-roles.
+Use a [button](buttons.md) with the `dropdown-toggle` class as the trigger and place the content in a
+`dropdown-menu`. Add a `dropdown-caret` icon to indicate that the button opens an overlay.
-The example uses the markup of [Bootstrap dropdown](https://getbootstrap.com/docs/5.1/components/dropdowns/).
-It is also possible to use the CDK directives without using markup related to the `dropdown-menu`.
+The theme provides the dropdown styles. Use the [CDK Overlay module](https://material.angular.io/cdk/overlay/overview)
+to create, position, and dismiss the overlay. The CDK directives can also be used with content that does not use
+the `dropdown-menu` class.
-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.
+### Basic markup
+
+Use a button for actions and an anchor for navigation. Set `aria-expanded` to the current open state and add
+`show` to the trigger while the overlay is open so that the caret rotates.
+
+```html
+
+
+
+
+
+
+
+
+
+
+```
+
+The `open` state controls the overlay. Use a transparent backdrop to close it when the user clicks outside.
+Also update the state on `(detach)`, which is emitted when the overlay closes, including after pressing Escape.
+The `position-static` and `d-block` utility classes allow the CDK to position the rendered menu.
For having a proper keyboard interaction, we are using the [CDK Focus trap](https://material.angular.io/cdk/a11y/overview#focustrap).
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.
+### Directions
+
+Wrap the trigger and menu in one of the direction classes to place a statically positioned menu relative to its
+trigger. The caret direction changes automatically.
+
+| Class | Menu placement |
+| ----------- | ------------------ |
+| `dropdown` | Below the trigger |
+| `dropup` | Above the trigger |
+| `dropstart` | Before the trigger |
+| `dropend` | After the trigger |
+
+```html
+
+
+
+
+
+
+```
+
+When using the CDK Overlay, configure the connected overlay positions instead. The direction classes are useful
+for menus that remain in the document flow or when the position is managed by the application.
+
+### Alignment
+
+Use an alignment class on the `dropdown-menu` to align it with its trigger. `align-start` is the default placement.
+
+| Class | Alignment |
+| -------------- | ------------------------------------------ |
+| `align-start` | Align the menu with the trigger start edge |
+| `align-center` | Center the menu on the trigger start edge |
+| `align-end` | Align the menu with the trigger end edge |
+
+```html
+
+
+
+
+
+
+```
+
+### Menu content
+
+Use `dropdown-item` for interactive actions. It supports the `active` and `disabled` states. Use
+`dropdown-item-text` for non-interactive content and `dropdown-header` to label a group of items.
+Use `dropdown-divider` to separate related groups.
+
+```html
+
+
Export
+
+
+
+
+
Exports include the current filters.
+
+```
+
+For items with icons, place the icon before an `item-title`. A trailing `menu-end-icon` can communicate an
+additional state or a follow-up action.
+
+```html
+
+```
+
+### Long menus
+
+`dropdown-menu` scrolls when its height exceeds the viewport. Add `dropdown-menu-scroller` to apply the
+recommended bounded height for menus with many items.
+
+```html
+
+
+
+```
+
+### Related components
+
+Use [button groups](button-group.md) to create split-button patterns. Use the [menu component](menu.md) when the
+content, see [content actions](content-actions.md).
+
diff --git a/src/app/examples/dropdown/dropdown-with-overlay.html b/src/app/examples/dropdown/dropdown-with-overlay.html
index 8e1380a487..5eedceb2d6 100644
--- a/src/app/examples/dropdown/dropdown-with-overlay.html
+++ b/src/app/examples/dropdown/dropdown-with-overlay.html
@@ -3,36 +3,36 @@
type="button"
class="btn btn-primary dropdown-toggle"
cdkOverlayOrigin
- [class.show]="open"
- [attr.aria-expanded]="open"
- (click)="open = true"
+ [class.show]="open()"
+ [attr.aria-expanded]="open()"
+ (click)="open.set(true)"
>
Overlay trigger / origin
-
+
-
-
-
+
+
+
diff --git a/src/app/examples/dropdown/dropdown-with-overlay.ts b/src/app/examples/dropdown/dropdown-with-overlay.ts
index 91e50cb238..0a0f2e7de9 100644
--- a/src/app/examples/dropdown/dropdown-with-overlay.ts
+++ b/src/app/examples/dropdown/dropdown-with-overlay.ts
@@ -4,17 +4,19 @@
*/
import { A11yModule } from '@angular/cdk/a11y';
import { CdkConnectedOverlay, CdkOverlayOrigin } from '@angular/cdk/overlay';
-import { Component, inject } from '@angular/core';
+import { Component, inject, signal } from '@angular/core';
+import { elementDown2 } from '@siemens/element-icons';
+import { addIcons, SiIconComponent } from '@siemens/element-ng/icon';
import { LOG_EVENT } from '@siemens/live-preview';
@Component({
selector: 'app-sample',
- imports: [CdkOverlayOrigin, CdkConnectedOverlay, A11yModule],
+ imports: [A11yModule, CdkOverlayOrigin, CdkConnectedOverlay, SiIconComponent],
templateUrl: './dropdown-with-overlay.html',
host: { class: 'p-5' }
})
export class SampleComponent {
- logEvent = inject(LOG_EVENT);
-
- open = false;
+ protected readonly logEvent = inject(LOG_EVENT);
+ protected readonly icons = addIcons({ elementDown2 });
+ protected readonly open = signal(false);
}