jiaiyan Naive UI Float Button Component
Floating action button for quick access to primary actions with menu and group support.
When to Use
Use this component when:
- Quick actions: Provide floating action buttons for primary operations
- Navigation: Create floating navigation controls
- Back to top: Alternative to BackTop with more customization
- Action menus: Group multiple actions in a collapsible menu
- Notifications: Display badges on floating buttons
When to Invoke
Invoke this skill when:
- User needs floating action buttons (FAB)
- User wants to create floating button groups
- User needs expandable menu from float button
- User wants to add badges to floating buttons
- User needs positioned floating elements
Features
- Position Control: Fixed, absolute, or relative positioning
- Shape Options: Circle or square shapes
- Button Types: Default and primary types
- Menu Support: Collapsible submenu with hover/click trigger
- Button Groups: Group multiple float buttons together
- Badge Integration: Works with n-badge component
- Description Slot: Add text description to buttons
API Reference
FloatButton Props
| Name | Type | Default | Description |
|---|---|---|---|
| bottom | number | string |
40 |
CSS bottom property. |
| height | number | string |
40 |
CSS height property. |
| left | number | string |
undefined |
CSS left property. |
| menu-trigger | 'click' | 'hover' |
undefined |
Trigger action to show submenu. |
| position | 'relative' | 'absolute' | 'fixed' |
'fixed' |
CSS position property. |
| right | number | string |
undefined |
CSS right property. |
| shape | 'circle' | 'square' |
'circle' |
Shape of the button. |
| show-menu | boolean |
undefined |
Whether submenu is shown (controlled). |
| top | number | string |
undefined |
CSS top property. |
| type | 'default' | 'primary' |
'default' |
Type of the button. |
| width | number | string |
undefined |
CSS width property. |
| on-update:show-menu | (value: boolean) => void |
undefined |
Callback when menu opens/closes. |
FloatButtonGroup Props
| Name | Type | Default | Description |
|---|---|---|---|
| bottom | number | string |
undefined |
CSS bottom property. |
| left | number | string |
undefined |
CSS left property. |
| position | 'relative' | 'absolute' | 'fixed' |
'fixed' |
CSS position property. |
| right | number | string |
undefined |
CSS right property. |
| shape | 'circle' | 'square' |
'circle' |
Shape of the button group. |
| top | number | string |
undefined |
CSS top property. |
FloatButton Slots
| Name | Parameters | Description |
|---|---|---|
| default | () |
Icon content of the button. |
| description | () |
Description text for the button. |
| menu | () |
Submenu content (nested float buttons). |
Basic Usage
Basic Float Button
<template>
<div style="height: 200px; transform: translate(0)">
<n-float-button :right="20" :bottom="20">
<n-icon>
<AddIcon />
</n-icon>
</n-float-button>
</div>
</template>
Positioned Float Buttons
<template>
<div style="height: 200px; transform: translate(0)">
<n-float-button :right="0" :bottom="0" shape="square">
<n-icon><CashIcon /></n-icon>
</n-float-button>
<n-float-button :left="0" :bottom="0" shape="square">
<n-icon><CashIcon /></n-icon>
</n-float-button>
<n-float-button :right="0" :top="0">
<n-icon><CashIcon /></n-icon>
</n-float-button>
<n-float-button :left="0" :top="0">
<n-icon><CashIcon /></n-icon>
</n-float-button>
</div>
</template>
With Badge
<template>
<n-flex>
<n-float-button position="relative">
<n-badge :value="9" :offset="[6, -8]">
<n-icon><AlarmOutlineIcon /></n-icon>
</n-badge>
</n-float-button>
<n-float-button position="relative">
<n-badge :value="100" :max="99" :offset="[6, -8]">
<n-icon><AlarmOutlineIcon /></n-icon>
</n-badge>
</n-float-button>
<n-float-button position="relative">
<n-badge dot :offset="[4, -4]">
<n-icon><AlarmOutlineIcon /></n-icon>
</n-badge>
</n-float-button>
</n-flex>
</template>
With Description
<template>
<div style="height: 120px; transform: translate(0)">
<n-float-button shape="square">
<n-icon><DocumentIcon /></n-icon>
<template #description>
Docs
</template>
</n-float-button>
</div>
</template>
Float Button Group
<template>
<n-flex align="flex-start">
<n-float-button-group shape="square" position="relative">
<n-float-button>
<n-icon><CashIcon /></n-icon>
</n-float-button>
<n-float-button>
<n-icon><CashIcon /></n-icon>
</n-float-button>
<n-float-button>
<n-icon><CashIcon /></n-icon>
</n-float-button>
</n-float-button-group>
<n-float-button-group position="relative">
<n-float-button>
<n-icon><CashIcon /></n-icon>
</n-float-button>
<n-float-button>
<n-icon><CashIcon /></n-icon>
</n-float-button>
</n-float-button-group>
</n-flex>
</template>
Expandable Menu
<template>
<n-flex>
<n-float-button position="relative" type="primary" menu-trigger="hover">
<n-icon><CashIcon /></n-icon>
<template #menu>
<n-float-button shape="square" type="primary">
<n-icon><CashIcon /></n-icon>
</n-float-button>
<n-float-button type="primary">
<n-icon><CashIcon /></n-icon>
</n-float-button>
<n-float-button type="primary">
<n-icon><CashIcon /></n-icon>
</n-float-button>
</template>
</n-float-button>
</n-flex>
</template>
Common Patterns
With Tooltip
<template>
<n-tooltip trigger="hover" placement="right">
<template #trigger>
<n-float-button position="relative">
<n-icon><CashIcon /></n-icon>
</n-float-button>
</template>
Add new item
</n-tooltip>
</template>
Controlled Menu
<template>
<n-float-button
position="relative"
type="primary"
menu-trigger="click"
:show-menu="showMenu"
@update:show-menu="showMenu = $event"
>
<n-icon><AddIcon /></n-icon>
<template #menu>
<n-float-button type="primary" @click="handleAction('edit')">
<n-icon><EditIcon /></n-icon>
</n-float-button>
<n-float-button type="primary" @click="handleAction('delete')">
<n-icon><DeleteIcon /></n-icon>
</n-float-button>
</template>
</n-float-button>
</template>
<script setup>
import { ref } from 'vue'
const showMenu = ref(false)
const handleAction = (action) => {
showMenu.value = false
console.log('Action:', action)
}
</script>
Back to Top Alternative
<template>
<n-float-button
v-show="showBackTop"
:right="40"
:bottom="80"
@click="scrollToTop"
>
<n-icon><ArrowUpIcon /></n-icon>
</n-float-button>
</template>
<script setup>
import { ref, onMounted, onUnmounted } from 'vue'
const showBackTop = ref(false)
const handleScroll = () => {
showBackTop.value = window.scrollY > 200
}
const scrollToTop = () => {
window.scrollTo({ top: 0, behavior: 'smooth' })
}
onMounted(() => window.addEventListener('scroll', handleScroll))
onUnmounted(() => window.removeEventListener('scroll', handleScroll))
</script>
Best Practices
Use primary type for main actions: Primary float button for the most important action
<n-float-button type="primary"> <n-icon><AddIcon /></n-icon> </n-float-button>Position appropriately: Use right/bottom for typical FAB placement
<n-float-button :right="24" :bottom="24"> <n-icon><AddIcon /></n-icon> </n-float-button>Group related actions: Use FloatButtonGroup for multiple related actions
<n-float-button-group shape="circle"> <!-- Multiple buttons --> </n-float-button-group>Use menu for expandable actions: Collapsible menu for secondary actions
<n-float-button menu-trigger="click"> <template #menu> <!-- Secondary actions --> </template> </n-float-button>Add tooltips for clarity: Provide context for icon-only buttons
<n-tooltip> <template #trigger> <n-float-button>...</n-float-button> </template> Action description </n-tooltip>Use relative position for inline: Set
position="relative"when embedding in layout