Popover · juxt.ui

Installation #

With the Nuxt module, every component is auto-imported — there is nothing to add. In a plain Vue project, import what you use:

import { JPopover } from '@juxtui/ui'

Usage #

<JPopover v-model:open="open">
  <template #trigger>
    <JButton variant="outline">Notifications</JButton>
  </template>
  <p class="text-sm text-fg-secondary">You’re all caught up.</p>
</JPopover>

Unlike JDialog, the popover is not modal: the rest of the page stays interactive, and there is no focus trap or scroll lock. Reach for JDialog or JSheet when the content needs the user’s full attention.

The trigger slot takes your own element — attributes and listeners are merged onto it, no wrapper element is added.

Variants & examples #

Placement#

placement sets the preferred side and alignment, flipping automatically when there isn’t room.

<script setup lang="ts">
const sides = ['top', 'right', 'bottom', 'left'] as const
</script>

<template>
  <div class="flex flex-wrap gap-3">
    <JPopover v-for="side in sides" :key="side" :placement="side">
      <template #trigger>
        <JButton variant="outline">{{ side }}</JButton>
      </template>
      <p class="w-40 text-sm text-fg-secondary">
        Placed on the {{ side }}, flipping automatically when there isn’t room.
      </p>
    </JPopover>
  </div>
</template>

The default slot exposes close, so a form can dismiss itself on submit.

<script setup lang="ts">
const open = ref(false)
const status = ref('active')

const statuses = [
  { value: 'active', label: 'Active' },
  { value: 'paused', label: 'Paused' },
  { value: 'archived', label: 'Archived' },
]

function apply(close: () => void) {
  close()
  toast.success(`Filtered by ${status.value}`)
}
</script>

<template>
  <JPopover v-model:open="open" placement="bottom-start">
    <template #trigger>
      <JButton variant="outline">Filter</JButton>
    </template>
    <template #default="{ close }">
      <div class="flex w-52 flex-col gap-3">
        <JSelect v-model="status" label="Status" :options="statuses" />
        <div class="flex justify-end gap-2">
          <JButton variant="ghost" size="sm" @click="close">Cancel</JButton>
          <JButton size="sm" @click="apply(close)">Apply</JButton>
        </div>
      </div>
    </template>
  </JPopover>
</template>

API #

Props

Prop	Type	Default	Description
open	`boolean`	`false`	Bound with `v-model:open`.
placement	`Placement`	`'bottom'`	Preferred side and alignment. Flips when there isn’t room.
offset	`number`	`8`	Distance from the trigger in px.
ariaLabel	`string`	—	Accessible name of the popover content.
closeOnOutside	`boolean`	`true`	Close when focus or a click leaves the popover.
disabled	`boolean`	`false`	Prevent opening.

Events

Event	Payload	Description
update:open	`boolean`	Emitted when the popover opens or closes.

Slots

Slot	Props	Description
trigger	`{ open }`	The element that opens the popover.
default	`{ close }`	Popover content.

Methods

Method	Signature	Description
close()	`() => void`	Close the popover and return focus to the trigger.

Accessibility #

role="dialog" without aria-modal; the trigger gets aria-haspopup="dialog", aria-expanded and aria-controls.
On open, focus moves to an element marked autofocus, else the first focusable element, else the popover itself.
A pointer press outside both the trigger and the popover closes it — without returning focus — while close-on-outside is on.
Losing focus to something outside the popover (via Tab) closes it the same way.

Keyboard #

Key	Action
`Esc`	Closes the popover and returns focus to the trigger.
`Tab`	Moves focus to the next focusable element. Because the popover isn’t modal, focus can leave it — doing so closes it while `close-on-outside` is on.