# gds-popover

**Class**: `GdsPopover`

**Tag**: `<gds-popover>`


## Properties

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `open` | `boolean` | `-` | Whether the popover is open. |
| `popupRole` | `'menu' \| 'listbox' \| 'tree' \| 'grid' \| 'dialog'` | `-` | This is used to indicate the semantic role of the popover. This will set the `aria-haspopup` attribute on the trigger element. Read here for more information: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup |
| `triggerRef` | `Promise<HTMLElement> \| undefined` | `-` | Optional way to assign a trigger element for the popover. When using Lit, this can take a value from a `@queryAsync` decorator in order to set the trigger element programatically. |
| `anchorRef` | `Promise<HTMLElement> \| undefined` | `-` | Optional way to assign an anchor element for the popover. When using Lit, this can take a value from a `@queryAsync` decorator in order to set the anchor element programatically. |
| `label` | `string \| undefined` | `-` | Optional trigger element for the popover. |
| `placement` | `Placement` | `-` | The placement of the popover relative to the trigger. Accepts any of the placements supported by Floating UI. |
| `disableMobileStyles` | `boolean` | `-` | Whether to use a modal dialog in mobile viewport. |
| `disableScrollClose` | `boolean` | `-` | Whether to disable closing the popover when the page is scrolled. |
| `autofocus` | `boolean` | `-` | Whether the popover should autofocus the first slotted child when opened. |
| `calcMinWidth` | `any` | `-` | A callback that returns the minimum width of the popover. By default, the popover minWidth will be as wide as the trigger element. |
| `calcMaxWidth` | `any` | `-` | A callback that returns the maximum width of the popover. By default, the popover maxWidth will be set to `auto` and will grow as needed. |
| `calcMinHeight` | `any` | `-` | A callback that returns the minimum height of the popover. By default, the popover minHeight will be set to `auto` |
| `calcMaxHeight` | `any` | `-` | A callback that returns the maximum height of the popover. By default, the popover maxHeight will be set to a hard coded pixel value (check source code). |
| `nonmodal` | `boolean` | `-` | Whether the popover is nonmodal. When true, the popover will not trap focus and other elements on the page will still be interactable while the popover is open. |
| `backdrop` | `string \| undefined` | `-` | When this is set to `true`, the `:backdrop` pseudo-element will be visible if the popover is in modal mode. When not in modal mode (using the `nonmodal` attribute), this can instead be set to a selector matching a `<gds-backdrop>` element, in wich case the popover will take control of that backdrop.  Example: ```html <gds-popover backdrop=".my-backdrop">   <gds-button slot="trigger">Open</gds-button>   <p>Popover content</p> </gds-popover> <gds-backdrop class="my-backdrop"></gds-backdrop> ``` |
| `floatingUIMiddleware` | `Middleware[]` | `-` | An array of middleware for the Floating UI positioning algorithm. Here you can pass in an array of middleware to customize positioning to your needs. This array is passed directly to Floting UI, so you can just follow the documentation here: https://floating-ui.com/docs/middleware  This property does not have a corresponding attribute, so it can only be set in JavaScript.  Defaults to `[offset(8), flip()]` |
| `syncFirstRender` | `boolean` | `-` | Force the element to perform a synchronous first render and apply style expression properties in `connectedCallback`.  This guarantees that the child DOM always remains projected in DOM, since the element will attach the shadowRoot and run the first render pass in the same event loop cycle, and that declarative layout will be applied once slotted DOM is projected.  Note: This will cause the first render pass to be blocking. Use sparingly and only when necessary, such as when the element needs to be measured synchronously after being added to the DOM. |


## Events

| Name | Type | Description |
|------|------|-------------|
| `gds-ui-state` | `CustomEvent<any>` | Fired when the popover is opened or closed. Can be cancelled to prevent the popover from opening or closing. The `detail` object contains the `open` boolean to indicate the result of the state change, and the `reason` string which can be one of `show`, `close`, or `cancel`. |


## Slots

| Name | Description |
|------|-------------|
| `(default)` | Content of the popover |
| `trigger` | Trigger element for the popover. If this slot is occupied, the popover will listen to keydown and click events on the trigger and automtaiclly open when clicked or when the trigger is focused and `ArrowDown` is pressed. |