FloatingBubble - Vant 4

FloatingBubble

🫧 Create magical floating bubbles that dance around your screen! Perfect for quick actions, shortcuts, and interactive elements that follow users everywhere.

🌟 Intro

Meet the FloatingBubble - your new favorite interactive element! 🎯 These delightful clickable bubbles hover gracefully around the edge of your page, providing instant access to important actions. ✨ With smooth dragging, magnetic snapping, and customizable positioning, they create an engaging user experience that's both functional and fun! 🚀

💡 Note: Please upgrade vant to >= v4.6.0 before using this component.

📦 Install

Get your floating bubbles ready to soar! 🎈 Register the component globally with app.use(), or explore Component Registration for more flexible installation options.

import { createApp } from'vue'; import { FloatingBubble } from'vant'; const app = createApp(); app.use(FloatingBubble);

🎨 Usage

✨ Basic Usage

Launch your first floating bubble! 🚀 By default, it appears in the bottom right corner with smooth vertical dragging along the y-axis. Customize the bubble's appearance with the icon prop for the perfect visual touch.

import { showToast } from'vant'; exportdefault { setup() { constonClick = () => { showToast('Click Bubble'); }; return { onClick }; }, };

🧲 Free Magnetic

Experience the magic of magnetic attraction! ✨ Enable free dragging in both x and y directions, and watch your bubble intelligently snap to the nearest edge of the x-axis - it's like having a smart assistant for your UI!

import { showToast } from'vant'; exportdefault { setup() { constonOffsetChange = (offset) => { showToast(`x: ${offset.x.toFixed(0)}, y: ${offset.y.toFixed(0)}`); }; return { onOffsetChange }; }, };

🎯 Use v-model

Take full control of your bubble's position! 🎮 Use v-model:offset to programmatically control where your bubble appears and moves - perfect for creating guided tours or dynamic positioning.

import { ref } from'vue'; exportdefault { setup() { const offset = ref({ x: 200, y: 400 }); return { offset }; }, };

🔧 API

Complete control over your floating bubble's behavior and appearance! 🎛️ Configure every aspect from positioning to interactions with these comprehensive options.

📋 Props

Attribute	Description	Type	Default
v-model:offset	Control bubble position	OffsetType	Default right-bottom coordinate
axis	Drag direction, xy stands for free drag, lock stands for disable drag	*'x'	'y'
magnetic	Direction of automatic magnetic absorption	*'x'	'y'*
icon	Bubble icon	string	-
gap	Minimum gap between the bubble and the window, unit px	*number	{ x: number, y: number }*
teleport	Specifies a target element where BackTop will be mounted	*string	Element*

🎪 Events

Listen to user interactions and bubble movements! 🎯 Stay connected to every click and position change for dynamic responses.

Event	Description	Arguments
click	Triggered when a component is clicked	MouseEvent
offset-change	Triggered when the position changes due to user dragging	{x: string, y: string}

🎨 Slots

Unlimited customization possibilities! ✨ Replace the default bubble content with your own creative designs and interactive elements.

Name	Description
default	Customize the bubble display content

📝 Types

Full TypeScript support for type-safe development! 🛡️ Import comprehensive type definitions to ensure your FloatingBubble implementation is robust and error-free.

exporttype { FloatingBubbleProps, FloatingBubbleAxis, FloatingBubbleMagnetic, FloatingBubbleOffset, } from'vant';

🎨 Theming

🎯 CSS Variables

Customize every visual aspect of your floating bubble! 🎨 Use these CSS variables to create the perfect look that matches your brand and design system. Refer to ConfigProvider component for global theming options.

Name	Default Value	Description
--van-floating-bubble-size	48px	-
--van-floating-bubble-initial-gap	24px	-
--van-floating-bubble-icon-size	28px	-
--van-floating-bubble-background	var(--van-primary-color)	-
--van-floating-bubble-color	var(--van-background-2)	-
--van-floating-bubble-z-index	999	-
--van-floating-bubble-border-radius	--van-floating-bubble-border-radius	-

📚 Related Docs

• BackTop - Scroll to top functionality
• Button - Interactive button components
• Icon - Icon library and usage
• Popup - Modal and overlay components
• ActionSheet - Bottom action menus
• Overlay - Background overlay effects
• Toast - Quick feedback messages
• ConfigProvider - Global configuration and theming
• Advanced Usage - Tips and best practices