Popover

🌏 Translated with the assistance of DeepSeek and ChatGPT

The Popover is used to display hidden content in a popup.

Currently, the Popover and Tooltip components are almost identical except for their styles. Both are retained for UI design and future code maintainability.

From a UI perspective, Tooltip is used for read-only short text hints, while Popover is designed to hold richer content (titles, buttons, forms, etc.) and allows users to perform lightweight actions.

Basic Usage

The Popover provides 9 display positions.

Use the content property to set the displayed information. The placement property determines the popup position. The property value format is: [direction]-[alignment], including 'top', 'right', 'bottom', 'left', 'top-start', 'top-end', 'right-start', 'right-end', 'bottom-start', 'bottom-end', 'left-start', 'left-end'. There are four directions and three alignment options. The default placement is top.

<template>
	<div class="box">
		<div class="left">
			<px-popover
				v-for="item in ['left-start', 'left', 'left-end']"
				:key="item"
				:placement="item"
				:content="getContent(item)"
			>
				<px-button>{{ getLabel(item) }}</px-button>
			</px-popover>
		</div>
		<div class="center">
			<div class="top">
				<px-popover
					v-for="item in ['top-start', 'top', 'top-end']"
					:key="item"
					:placement="item"
					:content="getContent(item)"
				>
					<px-button>{{ getLabel(item) }}</px-button>
				</px-popover>
			</div>
			<div class="bottom">
				<px-popover
					v-for="item in ['bottom-start', 'bottom', 'bottom-end']"
					:key="item"
					:placement="item"
					:content="getContent(item)"
				>
					<px-button>{{ getLabel(item) }}</px-button>
				</px-popover>
			</div>
		</div>
		<div class="right">
			<px-popover
				v-for="item in ['right-start', 'right', 'right-end']"
				:key="item"
				:placement="item"
				:content="getContent(item)"
			>
				<px-button>{{ getLabel(item) }}</px-button>
			</px-popover>
		</div>
	</div>
</template>

<script setup lang="ts">
const getLabel = (placement: string) => {
	return placement.replace(/-/g, ' ').replace(/\b\w/g, (l) => l.toUpperCase())
}

const getContent = (placement: string) => {
	let contentArr: string[] = []
	if (placement.includes('-')) {
		const [pos, sub] = placement.split('-')
		contentArr = [capitalize(pos), capitalize(sub), 'Popover']
	} else {
		contentArr = [capitalize(placement), 'Popover']
	}

	return placement.startsWith('top') || placement.startsWith('bottom')
		? contentArr.join(' ')
		: contentArr.join('\n')
}

const capitalize = (str: string) => str.charAt(0).toUpperCase() + str.slice(1)
</script>

<style lang="css" scoped>
.box {
	display: flex;
	width: 600px;
	height: 350px;
	margin-left: 100px;
	margin-top: 64px;
	margin-bottom: 64px;
}
.left,
.right {
	flex-shrink: 0;
	display: flex;
	flex-direction: column;
	justify-content: space-around;
}
.left {
	align-items: flex-start;
}
.right {
	align-items: flex-end;
}
.center {
	flex: 1;
	display: flex;
	flex-direction: column;
}
.top,
.bottom {
	display: flex;
	justify-content: space-around;
}
.top {
	flex: 1;
}
</style>

Trigger Method

The trigger property sets the trigger method.

<template>
	<px-space>
		<px-popover content="Hover" trigger="hover">
			<px-button>Hover</px-button>
		</px-popover>
		<px-popover content="Click" trigger="click">
			<px-button>Click</px-button>
		</px-popover>
	</px-space>
</template>

Controlled Mode

Pass in visible to enable controlled mode. If not passed or set to undefined, it is uncontrolled. In this case, you can use the defaultVisible property as the default value.

<template>
	<px-space>
		<px-popover content="Controlled" v-model:visible="visible">
			<px-button>Controlled {{ visible }}</px-button>
		</px-popover>
		<px-popover content="Uncontrolled">
			<px-button>Uncontrolled</px-button>
		</px-popover>
	</px-space>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const visible = ref(false)
</script>

Disabled State

Pass in disabled to set the disabled state. In this state, mouse events will no longer open or close the popup.

<template>
	<px-popover disabled content="Test">
		<px-button>Cannot Show Popover</px-button>
	</px-popover>
</template>

Hide Arrow

Pass in arrow to control whether the arrow is displayed. The default is true.

<template>
	<px-space>
		<px-popover content="Not Arrow" :arrow="false">
			<px-button>Not Arrow</px-button>
		</px-popover>
		<px-popover content="Has Arrow">
			<px-button>Has Arrow</px-button>
		</px-popover>
	</px-space>
</template>

Offset Distance

Use the offset property to set the distance between the popup and the trigger element.

<template>
	<px-space>
		<px-popover content="Offset Default">
			<px-button>Offset Default</px-button>
		</px-popover>
		<px-popover content="Offset 0px" :offset="0">
			<px-button>Offset 0px</px-button>
		</px-popover>
	</px-space>
</template>

API

PopoverProps

Attribute	Type	Optional	Default	Description	Version
content	string	True		The content of the popover.	0.0.2
visible	boolean | null	True		Whether the popover is visible (controlled).	0.0.2
defaultVisible	boolean | null	True		Whether the popover is visible by default (uncontrolled).	0.0.2
placement	'top' | 'right' | 'bottom' | 'left' | 'top-start' | 'top-end' | 'right-start' | 'right-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end'	True	'top'	The position of the popover relative to the trigger element.	0.0.2
trigger	'hover' | 'click'	True	'hover'	The trigger method.	0.0.2
offset	number	True	8	Offset distance in pixels.	0.0.2
variant	'dark' | 'light'	True	'light'	Popover style variant.	0.0.2
arrow	boolean	True	true	Whether to show the arrow.	0.0.2
disabled	boolean	True	false	Whether the popover is disabled.	0.0.2
disabled	number	True		Whether the popover is disabled.	0.0.2
root	HTMLElement | string	True	'body'	The element where the popover is mounted.	0.0.2
widthEqual	boolean	True	false		0.0.2
contentStyle	CSSProperties	True		Style of content area.	0.0.2

PopoverEvents

Event	Parameter	Description	Version
update:visible	value: boolean	v-model update for the visible property.	0.0.2
close	e: MouseEvent	Callback when the popover closes.	0.0.2
open	e: MouseEvent	Callback when the popover opens.	0.0.2

PopoverSlots

Slot	Parameter	Description	Version
default		The trigger element.	0.0.0-beta
content		The popover content.	0.0.0-beta