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