Popover

Display supplementary content or information when users interact with specific elements.

	<script lang="ts">
  import { Popover, Separator, Toggle } from "bits-ui";
  import ImageSquare from "phosphor-svelte/lib/ImageSquare";
  import LinkSimpleHorizontalBreak from "phosphor-svelte/lib/LinkSimpleHorizontalBreak";
 
  let width = $state(1024);
  let height = $state(768);
</script>
 
<Popover.Root>
  <Popover.Trigger
    class="inline-flex h-10
	select-none items-center justify-center whitespace-nowrap rounded-input bg-dark px-[21px] text-[15px] font-medium text-background shadow-mini transition-all hover:cursor-pointer hover:bg-dark/95 active:scale-98"
  >
    Resize
  </Popover.Trigger>
  <Popover.Portal>
    <Popover.Content
      class="z-30 w-full max-w-[328px] rounded-[12px] border border-dark-10 bg-background p-4 shadow-popover data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2"
      sideOffset={8}
    >
      <div class="flex items-center">
        <div
          class="mr-3 flex size-12 items-center justify-center rounded-full bg-muted"
        >
          <ImageSquare class="size-6" />
        </div>
        <div class="flex flex-col">
          <h4 class="text-[17px] font-semibold leading-5 tracking-[-0.01em]">
            Resize image
          </h4>
          <p class="text-sm font-medium text-muted-foreground">
            Resize your photos easily
          </p>
        </div>
      </div>
      <Separator.Root class="-mx-4 mb-6 mt-[17px] block h-px bg-dark-10" />
      <div class="flex items-center pb-2">
        <div class="mr-2 flex items-center">
          <div class="relative mr-2">
            <span class="sr-only">Width</span>
            <span
              aria-hidden="true"
              class="absolute left-5 top-4 text-xxs text-muted-foreground"
              >W</span
            >
            <input
              type="number"
              class="h-input w-[119px] rounded-10px border border-border-input bg-background pl-10 pr-2 text-sm text-foreground"
              bind:value={width}
            />
          </div>
          <div class="relative">
            <span class="sr-only">Height</span>
            <span
              aria-hidden="true"
              class="absolute left-5 top-4 text-xxs text-muted-foreground"
              >H</span
            >
            <input
              type="number"
              class="h-input w-[119px] rounded-10px border border-border-input bg-background pl-10 pr-2 text-sm text-foreground"
              bind:value={height}
            />
          </div>
        </div>
        <Toggle.Root
          aria-label="toggle constrain portions"
          class="inline-flex size-10 items-center justify-center rounded-[9px] bg-background transition-all hover:bg-muted active:scale-98 data-[state=on]:bg-muted"
        >
          <LinkSimpleHorizontalBreak class="size-6" />
        </Toggle.Root>
      </div>
    </Popover.Content>
  </Popover.Portal>
</Popover.Root>

Structure

	<script lang="ts">
	import { Popover } from "bits-ui";
</script>
 
<Popover.Root>
	<Popover.Trigger />
	<Popover.Content>
		<Popover.Close />
		<Popover.Arrow />
	</Popover.Content>
</Popover.Root>

Managing Open State

Bits UI offers several approaches to manage and synchronize the Popover's open state, catering to different levels of control and integration needs.

1. Two-Way Binding

For seamless state synchronization, use Svelte's bind:open directive. This method automatically keeps your local state in sync with the dialog's internal state.

	<script lang="ts">
	import { Popover } from "bits-ui";
	let isOpen = $state(false);
</script>
 
<button onclick={() => (isOpen = true)}>Open Popover</button>
 
<Popover.Root bind:open={isOpen}>
	<!-- ... -->
</Popover.Root>

Key Benefits

  • Simplifies state management
  • Automatically updates isOpen when the popover closes/opens (e.g., via escape key)
  • Allows external control (e.g., opening via a separate button)

2. Change Handler

For more granular control or to perform additional logic on state changes, use the onOpenChange prop. This approach is useful when you need to execute custom logic alongside state updates.

	<script lang="ts">
	import { Popover } from "bits-ui";
	let isOpen = $state(false);
</script>
 
<Popover.Root
	open={isOpen}
	onOpenChange={(o) => {
		isOpen = o;
		// additional logic here.
	}}
>
	<!-- ... -->
</Popover.Root>

Use Cases

  • Implementing custom behaviors on open/close
  • Integrating with external state management solutions
  • Triggering side effects (e.g., logging, data fetching)

3. Fully Controlled

For complete control over the dialog's open state, use the controlledOpen prop. This approach requires you to manually manage the open state, giving you full control over when and how the dialog responds to open/close events.

To implement controlled state:

  1. Set the controlledOpen prop to true on the Popover.Root component.
  2. Provide an open prop to Popover.Root, which should be a variable holding the current state.
  3. Implement an onOpenChange handler to update the local state when the internal state changes.
	<script lang="ts">
	import { Popover } from "bits-ui";
 
	let myOpen = $state(false);
</script>
 
<Popover.Root controlledOpen open={myOpen} onOpenChange={(o) => (myOpen = o)}>
	<!-- ... -->
</Popover.Root>

When to Use

  • Implementing complex open/close logic
  • Coordinating multiple UI elements
  • Debugging state-related issues

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.

	<Popover.Content trapFocus={false}>
	<!-- ... -->
</Popover.Content>

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.

	<script lang="ts">
	import { Popover } from "bits-ui";
	let nameInput = $state<HTMLInputElement>();
</script>
 
<Popover.Root>
	<Popover.Trigger>Open Popover</Popover.Trigger>
	<Popover.Content
		onOpenAutoFocus={(e) => {
			e.preventDefault();
			nameInput?.focus();
		}}
	>
		<input type="text" bind:this={nameInput} />
	</Popover.Content>
</Popover.Root>

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.

	<script lang="ts">
	import { Popover } from "bits-ui";
	let nameInput = $state<HTMLInputElement>();
</script>
 
<input type="text" bind:this={nameInput} />
<Popover.Root>
	<Popover.Trigger>Open Popover</Popover.Trigger>
	<Popover.Content
		onCloseAutoFocus={(e) => {
			e.preventDefault();
			nameInput?.focus();
		}}
	>
		<!-- ... -->
	</Popover.Content>
</Popover.Root>

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.

	<Popover.Content preventScroll={true}>
	<!-- ... -->
</Popover.Content>

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.

	<Popover.Content escapeKeydownBehavior="ignore">
	<!-- ... -->
</Popover.Content>

onEscapeKeydown

You can also override the default behavior by cancelling the event passed to the onEscapeKeydown callback on the Popover.Content component.

	<Popover.Content onEscapeKeydown={(e) => e.preventDefault()}>
	<!-- ... -->
</Popover.Content>

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.

	<Popover.Content interactOutsideBehavior="ignore">
	<!-- ... -->
</Popover.Content>

onInteractOutside

You can also override the default behavior by cancelling the event passed to the onInteractOutside callback on the Popover.Content component.

	<Popover.Content onInteractOutside={(e) => e.preventDefault()}>
	<!-- ... -->
</Popover.Content>

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

A callback that fires when the open state changes.

Default: undefined
controlledOpen
boolean

Whether or not the open state is controlled or not. If true, the component will not update the open state internally, instead it will call onOpenChange when it would have otherwise, and it is up to you to update the open prop that is passed to the component.

Default: false
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

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined
Data Attribute Value Description
data-state
enum

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

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

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

A boundary element or array of elements to check for collisions against.

Default: undefined
collisionPadding
union

The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.

Default: 0
sticky
enum

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

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

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

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

Callback fired when an outside interaction event completes, which is either a pointerup, mouseup, or touchend event, depending on the user's input device. You can call event.preventDefault() to prevent the default behavior of handling the outside interaction.

Default: undefined
onFocusOutside
function

Callback fired when focus leaves the dismissable layer. You can call event.preventDefault() to prevent the default behavior on focus leaving the layer.

Default: undefined
interactOutsideBehavior
enum

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

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

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 handler called when auto-focusing the content as it is opened. Can be prevented.

Default: undefined
onCloseAutoFocus
function

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

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

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined
Data Attribute Value Description
data-state
enum

Whether the popover is open or closed.

data-popover-content
''

Present on the content 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

Callback fired when an outside interaction event completes, which is either a pointerup, mouseup, or touchend event, depending on the user's input device. You can call event.preventDefault() to prevent the default behavior of handling the outside interaction.

Default: undefined
onFocusOutside
function

Callback fired when focus leaves the dismissable layer. You can call event.preventDefault() to prevent the default behavior on focus leaving the layer.

Default: undefined
interactOutsideBehavior
enum

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

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

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 handler called when auto-focusing the content as it is opened. Can be prevented.

Default: undefined
onCloseAutoFocus
function

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

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

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined
Data Attribute Value Description
data-state
enum

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

Use render delegation to render your own element. See delegation 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

Use render delegation to render your own element. See delegation 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.