NGX-FLOATING

A lightweight and powerful Angular floating UI solution with flexible positioning and draggable support.

中文文档 | English

---

✨ Features

• 🚀 Lightweight – No external dependencies
• 📦 Multiple Usage Modes – Component, Directive, or Service
• 🎯 Flexible Positioning – Dynamic alignment with inner/outer positioning support
• 🖱️ Drag & Drop Support – Optional movable functionality with boundary constraints
• 🔄 Auto Boundary Detection – Smart repositioning within containers
• 🎨 Customizable Styling – Full control over appearance and content
• 🔧 Responsive Design – Automatically adjusts to container size changes

---

🛠 Installation

npm install ngx-floating

---

🚀 Usage

1. Import the Module

import { NgxFloatingComponent, NgxFloatingDirective } from 'ngx-floating';

@Component({
  // ...
  imports: [NgxFloatingComponent, NgxFloatingDirective],
})

2. Component Mode

<div #target>
  <ngx-floating 
    [at]="target" 
    [movable]="true" 
    [handler]="'.drag-handle'" 
    [offset]="{ right: 10, bottom: 10, inner: true }" 
    [boundary]="target">
    <div class="drag-handle">Drag Here</div>
    <div>Floating Content</div>
  </ngx-floating>
</div>

3. Directive Mode

<div #target>
  <div [ngxFloating]="true" 
       [movable]="true" 
       [at]="target" 
       [offset]="{ top: 0, right: 0 }"
       [ignoreBoundary]="false">
    Floating Content
  </div>
</div>

4. Service Mode

import { NgxFloatingService } from 'ngx-floating';

export class YourComponent {
  constructor(private floatingService: NgxFloatingService) {}

  createFloating() {
    this.floatingService.create('floating-id', {
      at: targetElement,
      movable: true,
      offset: { top: 0, right: 0 },
      content: 'Floating Content' // Supports string, template ref, or component
    });
  }

  toggleVisibility() {
    this.floatingService.show('floating-id'); // Show
    this.floatingService.hide('floating-id'); // Hide
  }

  cleanup() {
    this.floatingService.destroy('floating-id'); // Destroy
  }
}

---

📚 API Reference

NgxFloatingComponent / NgxFloatingDirective

Property	Type	Default	Description
at	HTMLElement	Required	Target element for positioning
movable	boolean	false	Enable drag-and-drop functionality
handler	string | HTMLElement	-	Drag handle element or CSS selector for drag trigger area
offset	FloatingOffset	{ top: 0 }	Positioning offsets
boundary	HTMLElement	documentElement	Boundary element to constrain movement
ignoreBoundary	boolean	false	Disable boundary constraints
zIndex	number	2	Z-index of the floating element
isVisible	boolean	true	Control visibility
content	TemplateRef | Type | string	-	Content (Service mode only)

FloatingOffset Interface

interface FloatingOffset {
  top?: number;
  right?: number;
  bottom?: number;
  left?: number;
  inner?: boolean; // Position relative to the inner area of the target
}

Component Instance Methods

Method	Description
show()	Show the floating element
hide()	Hide the floating element
reset()	Reset position to initial state

NgxFloatingService Methods

Method	Parameters	Description
create	(id: string, options: NgxFloatingServiceOptions)	Create a floating instance
destroy	(id: string)	Destroy a floating instance
show	(id: string)	Show the floating element
hide	(id: string)	Hide the floating element
reset	(id: string)	Reset position to initial state
get	(id: string)	Retrieve a floating instance by ID

---

🌐 Live Demo

Explore interactive examples at the Demo Page.

---

📜 License

MIT © 2025 Eternal Heart