# dds-popover



<!-- Auto Generated Below -->


## Overview

A popover is a floating panel anchored to a trigger that reveals contextual information or secondary actions on demand. It opens in the browser's top layer and closes on `Esc` or a click outside.

## Usage

### Popover

#### Basic

Slot the element that opens the popover into `trigger`, and put the panel's content in the default slot. Give the popover an `aria-label`: the panel is a dialog, and a dialog needs a name.

```html
<dds-popover aria-label="Campaign details">
  <button slot="trigger" type="button">Open</button>
  <p>Select a campaign from the sidebar to view performance metrics.</p>
</dds-popover>
```

#### Placement

`placement` sets the preferred side and alignment of the panel relative to the trigger. The panel flips to the opposite side when it would leave the viewport.

```html
<dds-popover placement="top-start" aria-label="Help">
  <button slot="trigger" type="button">Help</button>
  <p>Appears above the trigger, aligned to its start edge.</p>
</dds-popover>
```

#### Open state

The `open` attribute is present while the panel is open and is removed once `Esc`, a click outside or the trigger closes it. Add it to render the panel open, and set or remove it from code to open or close the panel.

```html
<dds-popover open aria-label="Welcome">
  <button slot="trigger" type="button">Welcome</button>
  <p>Open on first render.</p>
</dds-popover>
```

#### Reacting to open and close

`ddsPopoverWillOpen` fires before the panel opens and can be cancelled with `preventDefault()`, which keeps it closed. `ddsPopoverDidOpen` and `ddsPopoverDidClose` fire after the change, whether a user or a change to `open` caused it. There is no cancellable event for closing.

```js
const popover = document.querySelector("dds-popover");

popover.addEventListener("ddsPopoverWillOpen", (event) => {
  if (!userCanOpen()) event.preventDefault();
});
popover.addEventListener("ddsPopoverDidClose", () => saveDraft());
```

#### Accessibility

The panel is the accessible element and has the `dialog` role. Name it with `aria-label` on `dds-popover`, which is forwarded to the panel. `aria-labelledby` and the other attributes that reference an element by id cannot cross the shadow boundary and are not forwarded.

The popover does not set `aria-expanded` on the trigger. If the trigger needs to expose its state, set `aria-expanded` yourself from `open` and the open and close events.

Keyboard behaviour follows the browser's popover handling, which is close to the [Dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) but non-modal. `Esc` and a click outside close the panel, and focus returns to the trigger. Focus does not move into the panel when it opens and is not trapped inside it, unlike a modal dialog.



## Properties

| Property    | Attribute   | Description                                                                                                                        | Type                                                                                                                                                                 | Default    |
| ----------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `open`      | `open`      | Whether the panel is open. The attribute follows the user opening and closing the panel, and setting it opens or closes the panel. | `boolean`                                                                                                                                                            | `false`    |
| `placement` | `placement` | The preferred side and alignment of the panel relative to the trigger. The panel flips to stay in view.                            | `"bottom" \| "bottom-end" \| "bottom-start" \| "left" \| "left-end" \| "left-start" \| "right" \| "right-end" \| "right-start" \| "top" \| "top-end" \| "top-start"` | `"bottom"` |


## Events

| Event                | Description                                                                               | Type                |
| -------------------- | ----------------------------------------------------------------------------------------- | ------------------- |
| `ddsPopoverDidClose` | Fires after the panel closes, whether a user or a change to `open` closed it.             | `CustomEvent<void>` |
| `ddsPopoverDidOpen`  | Fires after the panel opens, whether a user or a change to `open` opened it.              | `CustomEvent<void>` |
| `ddsPopoverWillOpen` | Fires before the panel opens. Cancel it with `preventDefault()` to keep the panel closed. | `CustomEvent<void>` |


## Slots

| Slot        | Description                                                            |
| ----------- | ---------------------------------------------------------------------- |
|             | The default slot                                                       |
| `"default"` | The content of the panel.                                              |
| `"trigger"` | The element that opens and closes the popover, such as a `dds-button`. |


## Shadow Parts

| Part     | Description         |
| -------- | ------------------- |
| `"root"` | The floating panel. |


----------------------------------------------

*Built with [StencilJS](https://stenciljs.com/)*