element-scale

A lightweight element scaling library that automatically adjusts element size based on device pixel ratio, designed for high-DPI displays and responsive layouts.

Features

• 🚀 Automatic scaling based on window.devicePixelRatio
• 🎯 Supports both CSS transform: scale() and zoom properties
• 📐 Built-in ResizeObserver for responsive scaling
• 🖼️ Automatic canvas handling with inverse scaling
• 📦 Lightweight with zero dependencies
• 🔒 TypeScript support with full type definitions

Installation

npm install element-scale

or

pnpm add element-scale

or

yarn add element-scale

Usage

Basic Usage

import { startScale, ElementScale } from 'element-scale';

const container = document.getElementById('container') as HTMLElement;

const scaleInstance = startScale({
  elements: ['.box', '#header', document.querySelector('.footer') as HTMLElement],
  container: container
});

With Options

import { startScale } from 'element-scale';

const container = document.getElementById('container') as HTMLElement;

const scaleInstance = startScale({
  elements: ['.box', '#header'],
  container: container,
  useZoom: true,
  minScale: 0.5,
  maxScale: 1,
  targetScale: 1,
  callback: (scale, elements) => {
    console.log(`Current scale: ${scale}`);
  }
});

Class API Usage

import { ElementScale } from 'element-scale';

const container = document.getElementById('container') as HTMLElement;

const scaleManager = new ElementScale({
  elements: ['.box', '#header'],
  container: container,
  useZoom: false,
  minScale: 0.6,
  maxScale: 1,
  targetScale: 1,
  callback: (scale, elements) => {
    console.log('Scale updated:', scale);
  }
});

// Later, to destroy the instance
scaleManager.destroy();

Destroy Scale

import { startScale } from 'element-scale';

const container = document.getElementById('container') as HTMLElement;
const scaleInstance = startScale({
  elements: ['.box'],
  container: container
});

// Destroy after 5 seconds
setTimeout(() => {
  scaleInstance.destroy();
}, 5000);

API

startScale(options)

Creates and starts an ElementScale instance.

startScale(options: ElementScaleOptions): ElementScale

new ElementScale(options)

Class constructor for more control over the scaling instance.

constructor(options: ElementScaleOptions)

ElementScaleOptions

| Property | Type | Default | Description | |----------|------|---------|-------------| | elements | ScaleElement[] | Required | Array of elements to scale (CSS selectors or HTMLElement) | | container | HTMLElement | Required | Container element to observe for resize events | | useZoom | boolean | true | Use CSS zoom instead of transform: scale() | | minScale | number | 0.6 | Minimum scale factor | | maxScale | number | 1 | Maximum scale factor | | targetScale | number | 1 | Target scale factor for calculation | | callback | (scale: number, elements: ScaleItem[]) => void | undefined | Callback function called when scale changes |

ScaleElement

type ScaleElement = string | HTMLElement;

• string: CSS selector (e.g., .box, #header)
• HTMLElement: Direct DOM element reference

ScaleItem

interface ScaleItem {
  el: HTMLElement;
  reset: () => void;
  update: (scale: number) => void;
}

Methods

runScale()

Manually trigger scale recalculation.

scaleInstance.runScale(): void

destroy()

Stop scaling, clean up observers, and reset all elements.

scaleInstance.destroy(): void

Properties

isInitialized

Check if the instance is initialized.

scaleInstance.isInitialized: boolean

How It Works

1. Device Detection: Detects the operating system (Mac or Windows)
2. DPR Calculation: Gets window.devicePixelRatio with fallback for older browsers
3. Scale Calculation: Computes scale factor using formula: min(maxScale, max(targetScale / dpr, minScale))
4. Auto-observation: Uses ResizeObserver to monitor container size changes
5. Canvas Handling: Automatically applies inverse scaling to canvas elements within the container

Scale Rules

• Scale ≥ 1: No scaling applied, all styles are reset
• Scale < 1: Elements are scaled down using either transform: scale() or zoom based on the useZoom option
• Canvas elements: Inversely scaled (multiplied by 1/scale) to maintain clarity at high DPI

Browser Support

• Chrome 60+
• Firefox 55+
• Safari 13.1+
• Edge 79+

Requires ResizeObserver support. For older browsers, consider using a polyfill.

Type Definitions

Full TypeScript type definitions are included and exported:

import type { 
  ScaleElement, 
  ScaleItem, 
  ElementScaleOptions, 
  DestroyScale 
} from 'element-scale';

License

MIT © SinJayXie