FloatingPanel - Vant 4

FloatingPanel

Create smooth, interactive bottom panels that enhance your mobile experience! 🚀

📱 Intro

A sleek panel that elegantly floats at the bottom of your page! 🎯 Users can intuitively drag it up and down to reveal content, making it perfect for providing additional functionality, detailed information, or interactive features without cluttering your main interface. ✨

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

📦 Install

Get started with FloatingPanel in seconds! 🚀 Register the component globally via app.use, or refer to Component Registration for more registration options.

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

🎯 Usage

Transform your mobile interface with these powerful floating panel patterns! ✨

🌟 Basic Usage

Start with the essentials! 🎪 The default height of FloatingPanel is 100px, and users can intuitively drag it to expand the panel to a height of 60% of the screen height for more content exploration.

⚓ Custom Anchors

Create precise stopping points for ultimate user control! 🎯 Set custom anchor positions through the anchors attribute, and control the display height dynamically with v-model:height.

Perfect for multi-level content reveal! 📊 For example, make your panel stop at three strategic positions: 100px, 40% of the screen height, and 70% of the screen height.

import { ref } from'vue'; exportdefault { setup() { const anchors = [ 100, Math.round(0.4 * window.innerHeight), Math.round(0.7 * window.innerHeight), ]; const height = ref(anchors[0]); return { anchors, height }; }, };

🎛️ Head Drag Only

Fine-tune user interaction! ✋ By default, both the header and content areas are draggable, but you can restrict dragging to just the header area using the content-draggable attribute for more controlled interactions.

🔧 API

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

📋 Props

Attribute	Description	Type	Default
v-model:height	The current display height of the panel	*number	string*
anchors	Setting custom anchors, unit px	number[]	[100, window.innerHeight * 0.6]
duration	Transition duration, unit second	*number	string*
content-draggable	Allow dragging content	boolean	true
lock-scroll v4.6.4	When not dragging, Whether to lock background scroll	boolean	false
safe-area-inset-bottom	Whether to enable bottom safe area adaptation	boolean	true

🎪 Events

Stay connected to panel interactions! 🎯 Listen to height changes and user gestures for dynamic responses.

Event	Description	Arguments
height-change	Emitted when panel height is changed and the dragging is finished	{ height: number }

🎨 Slots

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

Name	Description
default	Custom panel content
header	Custom panel header

📝 Types

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

importtype { FloatingPanelProps } from'vant';

🎨 Theming

🎯 CSS Variables

Customize every visual aspect of your floating panel! 🎨 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-panel-border-radius	16px	-
--van-floating-panel-header-height	30px	-
--van-floating-panel-z-index	999	-
--van-floating-panel-background	var(--van-background-2)	-
--van-floating-panel-bar-width	20px	-
--van-floating-panel-bar-height	3px	-
--van-floating-panel-bar-color	var(--van-gray-5)	-

📚 Related Docs

• FloatingBubble - Floating action buttons
• Popup - Modal and overlay components
• ActionSheet - Bottom action menus
• BackTop - Scroll to top functionality
• Overlay - Background overlay effects
• PullRefresh - Pull-to-refresh interactions
• Swipe - Touch gesture handling
• Sticky - Sticky positioning components
• ConfigProvider - Global configuration and theming
• Advanced Usage - Tips and best practices