# Popover Documentation Display supplementary content or information when users interact with specific elements. This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue. ```svelte Resize ``` ## Structure ```svelte ``` ## Managing Open State This section covers how to manage the `open` state of the component. ### Two-Way Binding Use `bind:open` for simple, automatic state synchronization: ```svelte ``` ### Fully Controlled Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes. ```svelte ``` ## Managing Focus ### Focus Trap By default, when a Popover is opened, focus will be trapped within that Popover. You can disable this behavior by setting the `trapFocus` prop to `false` on the `Popover.Content` component. ```svelte ``` ### Open Focus By default, when a Popover is opened, focus will be set to the first focusable element with the `Popover.Content`. This ensures that users navigating my keyboard end up somewhere within the Popover that they can interact with. You can override this behavior using the `onOpenAutoFocus` prop on the `Popover.Content` component. It's *highly* recommended that you use this prop to focus *something* within the Popover's content. You'll first need to cancel the default behavior of focusing the first focusable element by cancelling the event passed to the `onOpenAutoFocus` callback. You can then focus whatever you wish. ```svelte Open Popover { e.preventDefault(); nameInput?.focus(); }} > ``` ### Close Focus By default, when a Popover is closed, focus will be set to the trigger element of the Popover. You can override this behavior using the `onCloseAutoFocus` prop on the `Popover.Content` component. You'll need to cancel the default behavior of focusing the trigger element by cancelling the event passed to the `onCloseAutoFocus` callback, and then focus whatever you wish. ```svelte Open Popover { e.preventDefault(); nameInput?.focus(); }} > ``` ## Scroll Lock By default, when a Popover is opened, users can still scroll the body and interact with content outside of the Popover. If you wish to lock the body scroll and prevent users from interacting with content outside of the Popover, you can set the `preventScroll` prop to `true` on the `Popover.Content` component. ```svelte ``` ## Escape Keydown By default, when a Popover is open, pressing the `Escape` key will close the dialog. Bits UI provides a couple ways to override this behavior. ### escapeKeydownBehavior You can set the `escapeKeydownBehavior` prop to `'ignore'` on the `Popover.Content` component to prevent the dialog from closing when the `Escape` key is pressed. ```svelte ``` ### onEscapeKeydown You can also override the default behavior by cancelling the event passed to the `onEscapeKeydown` callback on the `Popover.Content` component. ```svelte e.preventDefault()}> ``` ## Interact Outside By default, when a Popover is open, pointer down events outside the content will close the popover. Bits UI provides a couple ways to override this behavior. ### interactOutsideBehavior You can set the `interactOutsideBehavior` prop to `'ignore'` on the `Popover.Content` component to prevent the dialog from closing when the user interacts outside the content. ```svelte ``` ### onInteractOutside You can also override the default behavior by cancelling the event passed to the `onInteractOutside` callback on the `Popover.Content` component. ```svelte e.preventDefault()}> ``` ## Custom Anchor By default, the `Popover.Content` is anchored to the `Popover.Trigger` component, which determines where the content is positioned. If you wish to instead anchor the content to a different element, you can pass either a selector `string` or an `HTMLElement` to the `customAnchor` prop of the `Popover.Content` component. ```svelte

``` ## Svelte Transitions You can use the `forceMount` prop along with the `child` snippet to forcefully mount the `Popover.Content` component to use Svelte Transitions or another animation library that requires more control. ```svelte {#snippet child({ wrapperProps, props, open })} {#if open}

{/if} {/snippet} ``` Of course, this isn't the prettiest syntax, so it's recommended to create your own reusable content component that handles this logic if you intend to use this approach. For more information on using transitions with Bits UI components, see the [Transitions](/docs/transitions) documentation. ```svelte Resize ``` ## API Reference ### Popover.Root The root component used to manage the state of the state of the popover. | Property | Type | Description | | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `open` $bindable | `boolean` | The open state of the link popover component.`Default: false` | | `onOpenChange` | `function`- (open: boolean) => void | A callback that fires when the open state changes.`Default: undefined` | | `children` | `Snippet` | The children content to render.`Default: undefined` | ### Popover.Trigger A component which toggles the opening and closing of the popover on press. | Property | Type | Description | | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ref` $bindable | `HTMLButtonElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: undefined` | | `children` | `Snippet` | The children content to render.`Default: undefined` | | `child` | `Snippet`- type SnippetProps = { props: Record\; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: undefined` | | Data Attribute | Value | Description | | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `data-state` | `enum`- 'open' \| 'closed' | Whether the popover is open or closed. | | `data-popover-trigger` | `''` | Present on the trigger element. | ### Popover.Content The contents of the popover which are displayed when the popover is open. | Property | Type | Description | | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `side` | `enum`- 'top' \| 'bottom' \| 'left' \| 'right' | The preferred side of the anchor to render the floating element against when open. Will be reversed when collisions occur.`Default: bottom` | | `sideOffset` | `number` | The distance in pixels from the anchor to the floating element.`Default: 0` | | `align` | `enum`- 'start' \| 'center' \| 'end' | The preferred alignment of the anchor to render the floating element against when open. This may change when collisions occur.`Default: start` | | `alignOffset` | `number` | The distance in pixels from the anchor to the floating element.`Default: 0` | | `arrowPadding` | `number` | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0` | | `avoidCollisions` | `boolean` | When `true`, overrides the `side` and `align` options to prevent collisions with the boundary edges.`Default: true` | | `collisionBoundary` | `union`- Element \| null | A boundary element or array of elements to check for collisions against.`Default: undefined` | | `collisionPadding` | `union`- number \| Partial\<Record\<Side, number\>\> | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0` | | `sticky` | `enum`- 'partial' \| 'always' | The sticky behavior on the align axis. `'partial'` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst `'always'` will keep the content in the boundary regardless.`Default: partial` | | `hideWhenDetached` | `boolean` | When `true`, hides the content when it is detached from the DOM. This is useful for when you want to hide the content when the user scrolls away.`Default: true` | | `updatePositionStrategy` | `enum`- 'optimized' \| 'always' | The strategy to use when updating the position of the content. When `'optimized'` the content will only be repositioned when the trigger is in the viewport. When `'always'` the content will be repositioned whenever the position changes.`Default: optimized` | | `strategy` | `enum`- 'fixed' \| 'absolute' | The positioning strategy to use for the floating element. When `'fixed'` the element will be positioned relative to the viewport. When `'absolute'` the element will be positioned relative to the nearest positioned ancestor.`Default: fixed` | | `preventScroll` | `boolean` | When `true`, prevents the body from scrolling when the content is open. This is useful when you want to use the content as a modal.`Default: false` | | `customAnchor` | `union`- string \| HTMLElement \| Measurable \| null | Use an element other than the trigger to anchor the content to. If provided, the content will be anchored to the provided element instead of the trigger.`Default: null` | | `onInteractOutside` | `function`- (event: PointerEvent) => void | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default: undefined` | | `onFocusOutside` | `function`- (event: FocusEvent) => void | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default: undefined` | | `interactOutsideBehavior` | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` | | `onEscapeKeydown` | `function`- (event: KeyboardEvent) => void | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default: undefined` | | `escapeKeydownBehavior` | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` | | `onOpenAutoFocus` | `function`- (event: Event) => void | Event handler called when auto-focusing the content as it is opened. Can be prevented.`Default: undefined` | | `onCloseAutoFocus` | `function`- (event: Event) => void | Event handler called when auto-focusing the content as it is closed. Can be prevented.`Default: undefined` | | `trapFocus` | `boolean` | Whether or not to trap the focus within the content when open.`Default: true` | | `preventOverflowTextSelection` | `boolean` | When `true`, prevents the text selection from overflowing the bounds of the element.`Default: true` | | `forceMount` | `boolean` | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false` | | `dir` | `enum`- 'ltr' \| 'rtl' | The reading direction of the app.`Default: 'ltr'` | | `ref` $bindable | `HTMLDivElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: undefined` | | `children` | `Snippet` | The children content to render.`Default: undefined` | | `child` | `Snippet`- type SnippetProps = { props: Record\; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: undefined` | | Data Attribute | Value | Description | | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `data-state` | `enum`- 'open' \| 'closed' | Whether the popover is open or closed. | | `data-popover-content` | `''` | Present on the content element. | | CSS Variable | Description | | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--bits-popover-content-transform-origin` | The transform origin of the popover content element. | | `--bits-popover-content-available-width` | The available width of the popover content element. | | `--bits-popover-content-available-height` | The available height of the popover content element. | | `--bits-popover-anchor-width` | The width of the popover trigger element. | | `--bits-popover-anchor-height` | The height of the popover trigger element. | ### Popover.ContentStatic The contents of the popover which are displayed when the popover is open. (Static/No Floating UI) | Property | Type | Description | | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `onInteractOutside` | `function`- (event: PointerEvent) => void | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default: undefined` | | `onFocusOutside` | `function`- (event: FocusEvent) => void | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default: undefined` | | `interactOutsideBehavior` | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an interaction occurs outside of the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` | | `onEscapeKeydown` | `function`- (event: KeyboardEvent) => void | Callback fired when an escape keydown event occurs in the floating content. You can call `event.preventDefault()` to prevent the default behavior of handling the escape keydown event.`Default: undefined` | | `escapeKeydownBehavior` | `enum`- 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | The behavior to use when an escape keydown event occurs in the floating content. `'close'` will close the content immediately. `'ignore'` will prevent the content from closing. `'defer-otherwise-close'` will defer to the parent element if it exists, otherwise it will close the content. `'defer-otherwise-ignore'` will defer to the parent element if it exists, otherwise it will ignore the interaction.`Default: close` | | `onOpenAutoFocus` | `function`- (event: Event) => void | Event handler called when auto-focusing the content as it is opened. Can be prevented.`Default: undefined` | | `onCloseAutoFocus` | `function`- (event: Event) => void | Event handler called when auto-focusing the content as it is closed. Can be prevented.`Default: undefined` | | `trapFocus` | `boolean` | Whether or not to trap the focus within the content when open.`Default: true` | | `preventOverflowTextSelection` | `boolean` | When `true`, prevents the text selection from overflowing the bounds of the element.`Default: true` | | `preventScroll` | `boolean` | When `true`, prevents the body from scrolling when the content is open. This is useful when you want to use the content as a modal.`Default: false` | | `forceMount` | `boolean` | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.`Default: false` | | `dir` | `enum`- 'ltr' \| 'rtl' | The reading direction of the app.`Default: 'ltr'` | | `ref` $bindable | `HTMLDivElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: undefined` | | `children` | `Snippet` | The children content to render.`Default: undefined` | | `child` | `Snippet`- type SnippetProps = { props: Record\; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: undefined` | | Data Attribute | Value | Description | | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `data-state` | `enum`- 'open' \| 'closed' | Whether the popover is open or closed. | | `data-popover-content` | `''` | Present on the content element. | ### Popover.Close A button which closes the popover when pressed and is typically placed in the content. | Property | Type | Description | | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ref` $bindable | `HTMLButtonElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: undefined` | | `children` | `Snippet` | The children content to render.`Default: undefined` | | `child` | `Snippet`- type SnippetProps = { props: Record\; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: undefined` | | Data Attribute | Value | Description | | ------------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `data-popover-close` | `''` | Present on the close button. | ### Popover.Arrow An optional arrow element which points to the trigger when the popover is open. | Property | Type | Description | | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `width` | `number` | The width of the arrow in pixels.`Default: 8` | | `height` | `number` | The height of the arrow in pixels.`Default: 8` | | `ref` $bindable | `HTMLDivElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: undefined` | | `children` | `Snippet` | The children content to render.`Default: undefined` | | `child` | `Snippet`- type SnippetProps = { props: Record\; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: undefined` | | Data Attribute | Value | Description | | ----------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `data-arrow` | `''` | Present on the arrow element. | | `data-popover-arrow` | `''` | Present on the arrow element. |

Resize image

Resize image