tessl/npm-tether

A client-side library to make absolutely positioned elements attach to elements in the page efficiently.

—

Pending

Overview

Eval results

Files

Optimization and Performance

Name: tessl/npm-tether
Author: tessl

Performance optimizations and positioning strategies for smooth user experiences. Tether provides various optimization options to improve rendering performance and reduce layout thrashing.

Capabilities

Optimization Configuration

Configure performance optimizations for better positioning performance.

interface OptimizationOptions {
  /** Whether to move elements to optimize positioning (defaults to true) */
  moveElement?: boolean;
  /** Whether to allow position: fixed for better performance (defaults to true) */
  allowPositionFixed?: boolean;
  /** Whether to use GPU acceleration via transforms (defaults to true unless false) */
  gpu?: boolean;
}

Usage in Tether Options:

import Tether from "tether";

const tether = new Tether({
  element: '.tooltip',
  target: '.button',
  attachment: 'top center',
  targetAttachment: 'bottom center',
  optimizations: {
    moveElement: true,
    allowPositionFixed: true,
    gpu: true
  }
});

GPU Acceleration

Control GPU acceleration through CSS transforms for better performance.

/**
 * GPU acceleration options
 * - true (default): Use transforms with GPU acceleration
 * - false: Use traditional top/left positioning
 */
gpu?: boolean;

Performance Impact:

GPU enabled: Uses transform: translateX() translateY() translateZ(0) for hardware acceleration
GPU disabled: Uses top and left CSS properties for positioning
Automatic device pixel ratio handling: Rounds transform values to avoid blurry rendering

Usage Examples:

// Enable GPU acceleration (default)
{
  optimizations: {
    gpu: true
  }
}

// Disable GPU acceleration for compatibility
{
  optimizations: {
    gpu: false
  }
}

Position Strategy

Control CSS positioning strategy for optimal performance.

/**
 * Position strategy options
 * - allowPositionFixed: true - Use position: fixed when beneficial
 * - allowPositionFixed: false - Always use position: absolute
 */
allowPositionFixed?: boolean;

Positioning Strategies:

Fixed positioning: When element and target are both in viewport
Absolute positioning: When using offset parent optimization
Fallback absolute positioning: When other strategies don't apply

Usage Examples:

// Allow fixed positioning (default - better performance)
{
  optimizations: {
    allowPositionFixed: true
  }
}

// Force absolute positioning (compatibility mode)
{
  optimizations: {
    allowPositionFixed: false
  }
}

Element Movement Optimization

Control whether Tether can move elements in the DOM for better positioning.

/**
 * Element movement options
 * - moveElement: true - Allow moving element to optimize positioning
 * - moveElement: false - Keep element in original DOM location
 */
moveElement?: boolean;

Movement Behaviors:

When enabled: Tether may move the element to a better offset parent for more efficient positioning
When disabled: Element stays in its original DOM location, may impact performance
Automatic detection: Tether determines optimal offset parent based on target element

Usage Examples:

// Allow element movement (default - better performance)
{
  optimizations: {
    moveElement: true
  }
}

// Prevent element movement (preserve DOM structure)
{
  optimizations: {
    moveElement: false
  }
}

Performance Features

Automatic Caching

Tether automatically caches expensive computations for better performance.

/**
 * Internal caching system (automatic)
 * Caches: element bounds, target bounds, offset parent info, scrollbar size
 */
cache(key: string, getter: Function): any;
clearCache(): void;

Cached Values:

Element bounding rectangles
Target bounding rectangles
Offset parent calculations
Scrollbar size measurements
Transform key detection

Throttled Positioning

Built-in throttling prevents excessive positioning calls.

Throttling Features:

Frame rate limiting: Voluntary throttling when performance drops below 60fps
Event debouncing: Prevents rapid-fire positioning calls
Minimum interval: 10ms minimum between position calculations

Batch Updates

Deferred DOM updates reduce layout thrashing.

/**
 * Deferred update system (internal)
 * Batches CSS changes and class updates for better performance
 */
defer(callback: Function): void;
flush(): void;

Benefits:

Groups multiple DOM changes into single reflow
Reduces layout thrashing during complex positioning
Improves performance with multiple active tethers

Global Performance Controls

Global Positioning

Control all active tethers simultaneously.

/**
 * Global positioning function for all active tethers
 * Efficiently updates all tether instances at once
 */
Tether.position(): void;

Usage Example:

// Manually trigger positioning for all tethers
Tether.position();

// Useful after significant DOM changes
document.addEventListener('orientationchange', () => {
  setTimeout(Tether.position, 100);
});

Automatic Event Handling

Built-in event listeners for automatic repositioning.

Auto-handled Events:

window.resize - Viewport size changes
window.scroll - Window scrolling
touchmove - Touch-based scrolling
Element scroll events - For scroll parents

Performance Best Practices

Efficient Configuration

// Optimal configuration for performance
const tether = new Tether({
  element: '.element',
  target: '.target',
  attachment: 'top center',
  targetAttachment: 'bottom center',
  
  // Performance optimizations
  optimizations: {
    moveElement: true,        // Allow DOM restructuring
    allowPositionFixed: true, // Use fixed positioning when possible
    gpu: true                 // Enable hardware acceleration
  },
  
  // Efficient class management
  classPrefix: 'tether',      // Use short prefixes
  addTargetClasses: false     // Skip target classes if not needed
});

Memory Management

// Proper cleanup to prevent memory leaks
class MyComponent {
  constructor() {
    this.tether = new Tether({
      element: '.my-element',
      target: '.my-target',
      attachment: 'top center',
      targetAttachment: 'bottom center'
    });
  }
  
  destroy() {
    // Always destroy tether instances
    this.tether.destroy();
    this.tether = null;
  }
}

Multiple Tethers

// Efficient management of multiple tethers
class MultiTether {
  constructor() {
    this.tethers = [];
  }
  
  addTether(options) {
    const tether = new Tether(options);
    this.tethers.push(tether);
    return tether;
  }
  
  updateAll() {
    // Use global positioning for efficiency
    Tether.position();
  }
  
  destroy() {
    // Clean up all tethers
    this.tethers.forEach(tether => tether.destroy());
    this.tethers = [];
  }
}

Performance Monitoring

Custom Performance Tracking

// Monitor positioning performance
const tether = new Tether({
  element: '.element',
  target: '.target',
  attachment: 'top center',
  targetAttachment: 'bottom center'
});

tether.on('repositioned', function() {
  // Track positioning frequency
  console.time('reposition-time');
  requestAnimationFrame(() => {
    console.timeEnd('reposition-time');
  });
});

Debug Information

// Access internal positioning data for debugging
tether.on('repositioned', function() {
  // Check positioning history
  console.log('Position history:', this.history);
  
  // Check cache status
  console.log('Cache keys:', Object.keys(this._cache || {}));
});

Install with Tessl CLI