usePopoverController

usePopoverController can create and control popovers and tooltips dynamically.

BPopoverOrchestrator

You must initialize the BPopoverOrchestrator component once and only once (multiple instances may display duplicate popovers). This is typically best placed at the App root.

template
<BPopoverOrchestrator />

The only props it access are teleportDisabled and teleportTo to modify the location that it is placed

Additionally, it exposes several methods on the template ref that correspond to those in the usePopoverController composable:

  • popover
  • tooltip
  • popovers

Creating Popovers

Popovers and tooltips can be created using the popover or tooltip methods.

HTML
vue
<template>
  <BButton ref="popoverButton">Hover me</BButton>
</template>

<script setup lang="ts">
const {popover} = usePopoverController()
const popoverButton = useTemplateRef('popoverButton')

const pop = popover({title: 'Hello World!', body: 'This is a popover.', target: popoverButton})
</script>

Reactivity Within popover and tooltip

The methods accepts reactive properties using MaybeRef, allowing dynamic updates to the popover content.

HTML
vue
<template>
  <BButton ref="reactiveExample">Click me</BButton>
</template>

<script setup lang="ts">
const {tooltip} = usePopoverController()

const title = ref('Hello')
onMounted(() => {
  setInterval(() => {
    title.value = title.value === 'Hello' ? 'World' : 'Hello'
  }, 2500)
})
tooltip({
  title: title,
})
</script>

Advanced Creation

For more control, you can use the component property to render a custom component or the slots property to define slot content dynamically.

HTML
vue
<template>
  <BButton ref="advancedExample">Click me</BButton>
</template>

<script setup lang="ts">
const {popover} = usePopoverController()

pop({
  slots: {
    default: (scope) =>
      h('div', null, {default: () => `Custom content - Visible: ${scope.visible}`}),
  },
})
</script>

Return Value

The popover and tooltip methods return a promise that resolves to a BvTriggerableEvent object when the popover is hidden. The promise includes methods to control the popover:

  • show: () => void - Shows the popover.
  • hide: (trigger?: string) => void - Hides the popover, optionally passing a trigger.
  • toggle: () => void - Toggles the visibility of the popover.
  • set: (props: Partial<PopoverOrchestratorParam>) => void - Updates the popover's properties.
  • destroy: () => Promise<void> - Destroys the popover and cleans up resources.

Lifecycle

By default, the popover is destroyed when the current scope is exited. You can manually destroy it using the destroy method.

js
const popover = popover({title: 'Hello World!'})
popover.show()
// do something
popover.destroy()

Alternatively, use await using in TypeScript to automatically destroy the popover when the scope is exited.

js
await using popover = popover({title: 'Hello World!'})