normalized-mouse-position

Convert mouse coordinates to normalized values relative to any origin point for smooth UI interactions and animations.


Installation

``bash
npm i normalized-mouse-position
`
`bash
pnpm add normalized-mouse-position
`

Quick Start

`typescript
import { getNormalizedMousePosition } from 'normalized-mouse-position';

// Basic usage - mouse position relative to center
const pos = getNormalizedMousePosition({
x: mouseEvent.clientX,
y: mouseEvent.clientY,
origin: "50% 50%" // center origin
});
// Result: {x: 0.3, y: -0.8, origin: {x: 0.5, y: 0.5}, size: {width: 800, height: 600}}
`

Key Features

- 🎯 Configurable Origin - Use any point as reference: center, corners, or custom positions
- 📏 Normalized Output - Always get predictable [-1, 1] range (or beyond if unclamped)
- 🔄 Axis Inversion - Perfect for 3D controls and mirror effects
- 🎨 Multiple Targets - Works with window or any DOM element
- 📦 TypeScript Ready - Full type safety with comprehensive JSDoc

Examples

$3


`typescript
// Center origin (default)
const centerPos = getNormalizedMousePosition({
x: mouseEvent.clientX,
y: mouseEvent.clientY,
origin: "50% 50%"
});

// Top-left origin
const topLeftPos = getNormalizedMousePosition({
x: mouseEvent.clientX,
y: mouseEvent.clientY,
origin: "0 0"
});

// Custom origin
const customPos = getNormalizedMousePosition({
x: mouseEvent.clientX,
y: mouseEvent.clientY,
origin: "25% 75%"
});
`

$3


`typescript
const elementPos = getNormalizedMousePosition({
x: mouseEvent.clientX,
y: mouseEvent.clientY,
target: document.querySelector('.my-element'),
origin: "50% 50%"
});
`

$3

`typescript
const controlPos = getNormalizedMousePosition({
x: mouseEvent.clientX,
y: mouseEvent.clientY,
origin: "50% 50%",
invertY: true, // Mouse up = positive Y (like 3D coordinates)
clamp: false // Allow values beyond [-1, 1]
});
`

$3

`typescript
import { gsap } from "gsap";
import { Observer } from "gsap/Observer";
import { getNormalizedMousePosition } from 'normalized-mouse-position';

function gsapMouseParallaxImage() {
gsap.registerPlugin(Observer);

document.querySelectorAll('[data-mouse-parallax-parent]').forEach(parentTarget => {
const childTarget = parentTarget.querySelector('[data-mouse-parallax-target]');
if (!childTarget) return;

Observer.create({
target: parentTarget,
type: "pointer",
onMove: ({x, y, target}) => {
const pos = getNormalizedMousePosition({x, y, target});
const parallaxIntensity = -20; // Negative for opposite direction

gsap.to(childTarget, {
force3D: true,
x: pos.x * parallaxIntensity,
y: pos.y * parallaxIntensity,
duration: 1,
ease: "power1.out"
});
}
});
});
}
`

$3


`typescript
// Mouse parallax with GSAP
document.addEventListener('mousemove', (e) => {
const pos = getNormalizedMousePosition({
x: e.clientX,
y: e.clientY,
origin: "50% 50%"
});

gsap.to('.parallax-element', {
x: pos.x * 50,
y: pos.y * 50,
duration: 0.3
});
});
`

API

$3

Parameters:
- x: number - Mouse X coordinate
- y: number - Mouse Y coordinate
- origin?: string - Origin point as "x% y%" (default: "50% 50%")
- target?: Window | Element - Reference element (default: window)
- clamp?: boolean - Limit to [-1, 1] range (default: true)
- invertX?: boolean - Invert X axis (default: false)
- invertY?: boolean - Invert Y axis (default: false)

Returns:
`typescript
{
x: number; // Normalized X coordinate
y: number; // Normalized Y coordinate
origin: { // Origin as decimal values
x: number;
y: number;
};
size: { // Target dimensions
width: number;
height: number;
};
}
`

Development


`bash

Install dependencies

pnpm install

Run tests

pnpm test

Build the package

pnpm run build

Run tests in watch mode

pnpm run test:watch
``

License

MIT © phucbm