Popup
import { Popup } from '@bbc/front-end-kit/vue'
A generic popup component that teleports the popup to a context outside the current component.
Getting started
<template>
<button @click="showPopup = true">Open popup</button>
<Popup v-model:visible="showPopup">
<h1>Custom popup</h1>
<p>A pop-up is a small window that appears while browsing a website. Marketers mainly use pop-ups for advertising and generating leads. With SendPulse, you can create smart pop-ups that are displayed according to certain scenarios</p>
</Popup>
</template>
<script setup>
import { ref } from 'vue';
import { Popup } from '@bbc/front-end-kit/vue';
const showPopup = ref(false);
</script>
Tips
The popup will be teleported to the .app__popups element by default. This means it is wrapped in a Teleport component, while the inherited attributes are passed on to the popup element
Escape to close
The popup automatically closes when the Escape key is pressed while it is visible, via @vueuse/core's useMagicKeys.
Guidelines
- It is best practice to extend or wrap the component, provide it with default values, and ensure consistency across the project.
Off-canvas behavior
The default built-in animation for the popup is a simple fade in. But it also incorporates more Off-Canvas like animations that can simply be triggered by adding the right css class to the DOM element it manages. Using css it will also make sure it sticks to the desired side of the screen like off-canvas elements are required to do. Possible classes to trigger this behavior.
--oc-top: Triggers the animation to slide in from the top of the screen--oc-right: Triggers the animation to slide in from the right of the screen--oc-bottom: Triggers the animation to slide in from the bottom of the screen--oc-left: Triggers the animation to slide in from the left of the screen
<Popup class="--oc-right">
...
</Popup>
API
Properties
animations
A way to override the hide/show animations of the popup. The animation functions will be passed to Vue's Transition component.
{
show ($el, done) {
gsap.to($el, {
opacity: 1,
duration: 0.5,
onComplete: done
})
},
hide ($el, done) {
gsap.to($el, {
opacity: 0,
duration: 0.5,
onComplete: done
})
}
}
Values: Object (with show and/or hide property)
Default: null (defaults to internal animations using gsap)
appear
Control whether the enter transition plays on first render.
Values: Boolean
Default: false
canClose
Toggles the close button. Set to false for popups that should not be closable via the button (e.g. modals with explicit action buttons).
Values: Boolean
Default: true
CloseButton
Vue component to replace the close button of the popup.
Values: Vue Component
Default: IconCross
closeButtonProps
Props to pass to the given CloseButton component.
Values: Object
Default: {}
instant
Open the popup instantly, skipping animations.
Values: Boolean
Default: false
teleportTarget
A selector of the element in the page the popup has to teleport to. This value will be passed on to the teleport's :to property.
Values: String
Default: '.app__popups'
closeIcon (deprecated)
Deprecated in favour of CloseButton. Still functional but will be removed in a future release.
Values: Vue Component
Default: IconCross
Models
visible
Reactive flag to toggle the popup and keep track of its current visibility state.
Type: Boolean
Default: false
Events
show
Emitted when the popup becomes visible. Not emitted when silent mode is active.
hide
Emitted when the popup is hidden. Not emitted when silent mode is active.
Slots
default
The contents inside the popup__content wrapper.
Attribute forwarding
Extra attributes passed to <Popup> (e.g. class, data-*) are forwarded to the inner .popup div via v-bind="$attrs", not the teleport wrapper. This is how off-canvas classes like --oc-right are applied.
Exposed properties
$el
Root DOM element of the popup component (the wrapper div outside the Teleport).
Values: HTMLElement
visible
Reactive ref for the popup's current visibility state. Can be read or set directly.
Values: Ref<Boolean>
toggle
Toggle the popup programmatically.
Values: Function
onCrossClick
Programmatically trigger the close button click (sets visible to false).
Values: Function
silent
When called with true, suppresses show/hide events for subsequent visibility changes. Call with false to re-enable.
Values: Function(value: Boolean)