Popover

Floating content anchored to a trigger; flips and shifts to stay on screen.

Install

If this is the first component in the project, set up once. This writes ermine.json and copies the theme stylesheet. The installation guide covers Vue, Nuxt and Astro.

npx ermineui init
pnpm dlx ermineui init
yarn dlx ermineui init
bunx ermineui init

Then add the component:

npx ermineui add popover
pnpm dlx ermineui add popover
yarn dlx ermineui add popover
bunx ermineui add popover

That copies 5 files into src/components/ui/popover/, 4 helpers into src/lib/ermine/. Files you already have are kept.

Use

import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
<script setup lang="ts">
import { Popover } from '@/components/ui/popover'
</script>

<template>
  <Popover />
</template>

In Nuxt, with the auto-import setting, the tags work in templates without the import. In Astro, use it inside a Vue island. The props are documented in the source below, on each one.

What gets copied

FileWhere it goes
Popover.vuesrc/components/ui/popover/Popover.vue
PopoverContent.vuesrc/components/ui/popover/PopoverContent.vue
PopoverTrigger.vuesrc/components/ui/popover/PopoverTrigger.vue
context.tssrc/components/ui/popover/context.ts
index.tssrc/components/ui/popover/index.ts
context.ts helpersrc/lib/ermine/context.ts
floating.ts helpersrc/lib/ermine/floating.ts
layer.ts helpersrc/lib/ermine/layer.ts
primitive.ts helpersrc/lib/ermine/primitive.ts

The folders are the suggested ones. ermine.json says where yours are.

Source

This is exactly what the command copies. To install by hand, create each file below and the helpers listed above.

Popover.vue 17 lines
<script setup lang="ts">
import { ref, useId } from 'vue'
import { providePopover } from './context'

const open = defineModel<boolean>('open', { default: false })

function setOpen(next: boolean) {
  open.value = next
}

providePopover({ open, setOpen, anchor: ref(null), contentId: useId() })
</script>

<template>
  <slot :open="open" :close="() => setOpen(false)" />
</template>
PopoverContent.vue 64 lines
<script setup lang="ts">
import { ref } from 'vue'
import { useFloating, type Align, type Side } from '../../lib/floating'
import { useLayer } from '../../lib/layer'
import { Portal } from '../../lib/primitive'
import { usePopover } from './context'

defineOptions({ inheritAttrs: false })

const props = withDefaults(
  defineProps<{
    side?: Side
    align?: Align
    /** Gap between trigger and popover, in px. */
    sideOffset?: number
    alignOffset?: number
  }>(),
  { side: 'bottom', align: 'center', sideOffset: 6, alignOffset: 0 },
)

const popover = usePopover()
const content = ref<HTMLElement | null>(null)

useFloating(popover.anchor, content, popover.open, props)
useLayer(content, popover.open, {
  loopFocus: true,
  ignore: () => [popover.anchor.value],
  onDismiss: () => popover.setOpen(false),
})
</script>

<template>
  <Portal>
    <Transition name="er-pop">
      <div
        v-if="popover.open.value"
        :id="popover.contentId"
        ref="content"
        v-bind="$attrs"
        role="dialog"
        tabindex="-1"
        class="er-floating er-popover"
      >
        <slot :close="() => popover.setOpen(false)" />
      </div>
    </Transition>
  </Portal>
</template>

<style>
@layer components {
  .er-popover {
    width: 18rem;
    padding: 1rem;
    border: 1px solid var(--er-border);
    border-radius: var(--er-radius-md);
    background: var(--er-popover);
    color: var(--er-popover-foreground);
    font-size: 0.875rem;
    box-shadow: var(--er-shadow-md);
  }
}
</style>
PopoverTrigger.vue 37 lines
<script setup lang="ts">
import type { Component } from 'vue'
import { Primitive, toElement } from '../../lib/primitive'
import { usePopover } from './context'

withDefaults(
  defineProps<{
    as?: string | Component
    /** Use the single child (e.g. a Button) as the trigger instead of rendering one. */
    asChild?: boolean
  }>(),
  { as: 'button' },
)

const popover = usePopover()

function setAnchor(target: unknown) {
  popover.anchor.value = toElement(target)
}
</script>

<template>
  <Primitive
    :ref="setAnchor"
    :as="as"
    :as-child="asChild"
    :type="as === 'button' && !asChild ? 'button' : undefined"
    aria-haspopup="dialog"
    :aria-expanded="popover.open.value"
    :aria-controls="popover.open.value ? popover.contentId : undefined"
    :data-state="popover.open.value ? 'open' : 'closed'"
    @click="popover.setOpen(!popover.open.value)"
  >
    <slot />
  </Primitive>
</template>
context.ts 12 lines
import type { Ref } from 'vue'
import { createContext } from '../../lib/context'

export interface PopoverContext {
  open: Ref<boolean>
  setOpen: (open: boolean) => void
  anchor: Ref<HTMLElement | null>
  contentId: string
}

export const [providePopover, usePopover] = createContext<PopoverContext>('Popover')
index.ts 5 lines
/** Popover — floating content anchored to a trigger; flips and shifts to stay on screen. */
export { default as Popover } from './Popover.vue'
export { default as PopoverContent } from './PopoverContent.vue'
export { default as PopoverTrigger } from './PopoverTrigger.vue'