sb-floating-panel-vue

🔥 Features

• 🧩 Floating panel positioning with arrow and smart shifting
• ⚡ Built on top of @floating-ui/vue
• 🎯 Support for resize syncing and animated transitions
• 🧪 Dual usage: composable or plug-and-play components

---

👤 Author

Created with ❤️ by Stefano Biddau

---

❓ Why This Library?

sb-floating-panel-vue was designed to make it extremely easy to implement dropdowns, tooltips, and floating panels in Vue 3, without worrying about placement logic, arrow positioning, or responsive syncing. It wraps @floating-ui/vue into a more ergonomic composable or ready-to-use components.

---

📦 Installation

# npm
npm install sb-floating-panel-vue

# yarn
yarn add sb-floating-panel-vue

# pnpm
pnpm add sb-floating-panel-vue

---

🧠 Composable Usage

Use the composable useSbFloatingPanel() for complete control.

Options

Option	Type	Required	Default	Description
placement	Placement	Yes	—	Placement of the floating panel
strategy	'absolute' | 'fixed'	Yes	—	CSS positioning strategy
offsetValue	number	Yes	—	Offset between reference and floating
hasArrow	boolean	No	false	Whether to render arrow
hasResize	boolean	No	false	Sync width of floating to reference

Return Values

Property	Type	Description
reference	Ref<HTMLElement | null>	Ref for the trigger element
floating	Ref<FloatingElement | null>	Ref for the floating panel
floatingArrow	Ref<HTMLElement | null>	Ref for the arrow element
floatingPlacement	Ref<Placement>	The actual resolved placement
floatingStyle	ComputedRef<CSSProperties>	Style for the floating panel
floatingArrowStyle	ComputedRef<CSSProperties>	Style for the arrow
isOpen	Ref<boolean>	Panel visibility
toggle / open / close	() => void	Control methods to toggle visibility

Example

In your Vue component, you can use the composable like this:

In your script tag, import the composable and use it:

import { useSbFloatingPanel } from 'sb-floating-panel-vue';

const {
  reference,
  floating,
  floatingArrow,
  floatingStyle,
  floatingArrowStyle,
  isOpen,
  toggle,
} = useSbFloatingPanel({
  placement: 'bottom-start',
  strategy: 'absolute',
  offsetValue: 12,
  hasArrow: true,
});

In your template, you can bind the refs and styles:

<template>
  <button ref="reference" @click="toggle()">Open Panel</button>
  <div v-if="isOpen" ref="floating" :style="floatingStyle">
    Panel
    <div ref="floatingArrow" :style="floatingArrowStyle" />
  </div>
</template>

---

🧱 Component-Based Usage

Import the style

If you use components, you must import styles in main.ts:

import 'sb-floating-panel-vue/style.css';

Available Components

<SbContainer>

Wraps everything and provides the context.

Prop	Type	Default	Description
placement	Placement	'bottom-start'	Placement of the floating panel relative to the reference element
strategy	'absolute' | 'fixed'	'absolute'	CSS positioning strategy for the floating panel
offsetValue	number	15	Offset in pixels between reference and floating panel
hasArrow	boolean	false	Whether to render an arrow pointing to the reference
hasResize	boolean	false	Whether the floating panel should sync its width with the reference

<SbReference>

Trigger element

Prop	Type	Default	Description
referenceRef	Ref<HTMLElement | null>	required	Reference element to which the floating panel is attached
as	'button' | 'div' | 'span' | etc.	'button'	HTML tag to render. Defaults to <button> for accessibility
onClick	() => void	—	Optional click handler, often used to toggle the floating panel visibility

<SbFloating>

Floating panel

Prop	Type	Default	Description
floatingRef	Ref<HTMLElement | null>	required	The target element for the floating panel (popover, tooltip, etc.)
floatingArrowRef	Ref<HTMLElement | null>	optional	The element used as the floating arrow
isOpen	boolean	required	Controls visibility of the floating panel
floatingPlacement	Placement	required	Current placement as resolved by @floating-ui/vue
floatingStyle	CSSProperties	required	Inline style object applied to the floating panel
floatingArrowStyle	CSSProperties	optional	Inline style object applied to the arrow element
arrowDimensions	number	optional	Size (width/height) of the arrow in pixels
zIndex	number	undefined	Custom z-index applied to the floating and arrow elements
animation	'fade' | 'scale-fade' | 'none'	'scale-fade'	Defines the animation style for enter/leave transitions
duration	number	300	Duration in ms for the transition animations

---

🧪 Component Usage Example

In your project, you can use the components like this:

In your script tag, import the components:

import { SbContainer, SbFloating, SbReference } from 'sb-floating-panel-vue';

In your template, you can use the components as follows:

<SbContainer :has-arrow="true" strategy="fixed">
  <template #default="{
    reference,
    floating,
    floatingArrow,
    floatingPlacement,
    floatingStyle,
    floatingArrowStyle,
    isOpen,
    toggle
  }">
    <SbReference :reference-ref="reference" :onClick="toggle">Toggle</SbReference>
    <SbFloating
      :is-open="isOpen.value"
      :floating-ref="floating"
      :floating-arrow-ref="floatingArrow"
      :floating-placement="floatingPlacement.value"
      :floating-style="floatingStyle.value"
      :floating-arrow-style="floatingArrowStyle.value"
      :arrow-dimensions="12"
      :z-index="200"
    >
      Hello Panel!
    </SbFloating>
  </template>
</SbContainer>

---

⚠️ Directive Note (Teleport Limitation)

Due to <teleport> in <SbFloating>, if you apply custom directives directly to the component, Vue will warn:

[Vue warn]: Extraneous non-props attributes ([directive-name]) were passed to component but could not be automatically inherited because component renders fragment or text or teleport root nodes.

Solution: Move the directive to an inner element using the slot.

Example Fix

<SbFloating ...>
  <div v-click-outside>...</div>
</SbFloating>

---

📄 License

MIT License © Stefano Biddau