# Text Hover Distortion
> Characters react to cursor proximity with push, pull, wave, or rotation effects. The pointer field can be read from a whole section, and buttons anywhere on the page can switch mode live.
Canonical: https://gsapvault.com/effects/text-hover-distortion
Live demo: https://gsapvault.com/demos/text-hover-distortion/index.html
| Property | Value |
|----------|-------|
| Type | effect |
| Tier | paid |
| Price | £5 |
| Difficulty | advanced |
| Plugins | Core GSAP only |
| Techniques | text-animation, cursor-effects, micro-interaction, physics |
| Uses Lenis | No |
## Overview
An interactive text effect where individual characters react to cursor proximity with physics-based displacement. Characters push away, pull toward, wave, or rotate based on their distance from the pointer, and the pointer field can be read from a containing section so the type starts reacting before the cursor is on top of it. Every setting can be retuned at runtime, so a single line of type can demonstrate all four modes. The demo is a type specimen sheet: one display line and two smaller sizes sharing the same field, with a toolbar that switches mode and depth live. Uses pure GSAP without any additional libraries.
## Features
- Four distortion modes: push, pull, wave, and rotation
- Per-character physics calculations based on cursor distance
- Configurable influence radius, displacement strength and falloff curve
- Pointer field readable from any container, not just the text itself
- Runtime retuning with setMode and setOptions, plus external mode and depth buttons
- Live readouts of the current settings and a bubbling distort:change event
- Smooth return-to-origin with three easing presets
- Works with any font, size, and text content
- Real-time position tracking at 60fps with GSAP quickTo
- Desktop-focused with a tap-to-ripple mobile fallback
## Use Cases
- Interactive hero headings on portfolio sites
- Type specimen and foundry pages
- Creative navigation menus and sidebar links
- About page name and title displays
- Interactive exhibit and gallery labels
- Experimental typography showcases
## Vibe-Code Ready Setup
This effect includes `START-HERE-AI.md`, a product-specific copy-paste setup prompt for Cursor, Claude Code, ChatGPT, GitHub Copilot, Windsurf, and other coding assistants. It tells the assistant to inspect the existing stack, integrate the supplied files, preserve the design, scope selectors, retain accessibility and responsive behaviour, add framework-appropriate GSAP cleanup, and report what it tested.
[How AI-assisted setup works](https://gsapvault.com/vibe-coding)
## How It Works
Each character is wrapped in its own inline-block span. While the pointer is inside the tracked area — the text element, or any container named with data-distort-area — a requestAnimationFrame loop measures the distance from the cursor to each character's centre and scales the displacement by the chosen falloff curve, so closer characters move further. The mode setting decides the direction: away, toward, a radial wave, or a rotation facing the cursor. GSAP quickTo interpolates every character back to rest, and changing a setting at runtime rebuilds only the quick setters that changed.
## Integration Preview
How this effect integrates into a page. The full documentation (examples, events, programmatic API, customization guide) ships with the download.
### Quick Start
**1. Add to your HTML ``:**
```html
```
**2. Add before closing `` tag:**
```html
```
**3. Add data attributes to any text element:**
**HTML:**
```html
SCATTER
MAGNETIC
RIPPLE
```
### Options
| Attribute | Values | Default | Description |
|-----------|--------|---------|-------------|
| `data-distort-mode` | `push`, `pull`, `wave`, `rotate` | `push` | Distortion behavior |
| `data-distort-strength` | 1-100 | `30` | Maximum displacement in pixels |
| `data-distort-radius` | Pixels | `150` | Cursor influence radius |
| `data-distort-ease` | `smooth`, `elastic`, `snappy` | `smooth` | Animation easing |
| `data-distort-falloff` | `linear`, `quadratic`, `exponential` | `quadratic` | How effect fades with distance |
| `data-distort-area` | CSS selector | The text element | Element whose pointer movement drives the effect |
| `data-distort-scale` | Presence | - | Enable scale modifier |
| `data-distort-opacity` | Presence | - | Enable opacity modifier |
### Accessibility
- Respects `prefers-reduced-motion` — no animation for users who prefer reduced motion
- Original text preserved for screen readers via `aria-hidden` wrapper
- Keyboard users see static text (effect requires pointer input)
- Mode buttons carry `aria-pressed`, kept in sync by the effect
### Browser Support
Modern browsers (ES6+). Not compatible with IE11.
### Dependencies
- GSAP 3.12+
## What You Get
- `index.html`: working demo page
- `assets/script.js`: commented, readable source
- `assets/style.css`: effect styles
- `README.md`: full documentation with examples and framework integration notes
- `START-HERE-AI.md`: product-specific copy-paste prompt for AI-assisted setup
- `LICENSE.txt`: standard license terms
- Lifetime updates: re-download anytime from your library
## Get the Code
This is a premium effect. The standard license costs £5 one-time and covers unlimited personal and commercial projects with no attribution required. The only restrictions: no redistribution of the code itself and no competing effect libraries.
- [Buy Text Hover Distortion](https://gsapvault.com/effects/text-hover-distortion)
- [Effects & Templates Vault (£39 one-time, best value): every current and future effect and template](https://gsapvault.com/effects)
## Judge the Code Quality First
These related effects are free with complete source published, written to the same production standard (cleanup functions, reduced-motion support, framework-agnostic):
- [Typewriter Text](https://gsapvault.com/effects/typewriter-text.md): A sharp terminal-style typewriter that types, holds, accelerates through deletion, and cycles to the next phrase in sync with cursor and progress signals.
- [Scroll Text Highlight](https://gsapvault.com/effects/scroll-text-highlight.md): A scrubbed orange-to-lime reading front lifts each active word before completed copy settles to white and unread copy remains ghosted.
- [Hover Underline](https://gsapvault.com/effects/hover-underline.md): Three material link underlines—an exit-through line, marker sweep, and hand-drawn wave—with coordinated type and active-index responses.
---
From [GSAP Vault](https://gsapvault.com): production-ready GSAP animation effects. Full catalog for agents: https://gsapvault.com/llms-full.txt