Documentation

Get up and running.

Everything you need to install timeline-lens, read what it shows you, and get the most out of it.

What it does

A read-only visual debugger, not an editor.

Your animations already exist: GSAP tweens, CSS keyframes and transitions, WAAPI calls. timeline-lens walks gsap.globalTimeline and polls document.getAnimations() to find every one already running on the page, including ones that already finished and got pruned, then lays them out as scrubbable tracks in a floating panel.

Nothing is created, edited, or exported. It's scoped the same way GreenSock's own GSDevTools plugin is: pure inspection of code you already wrote.

Timelines ScrollTrigger matchMedia CSS animations Transitions element.animate() Astro React Next.js JavaScript or TypeScript

How to install

Four steps, start to finish.

Before you start: you need a project that already has some animation in it, a GSAP tween, a CSS transition, an element.animate() call. timeline-lens detects animations, it does not create them.

  1. Install the package as a dev dependency.

    npm install --save-dev timeline-lens

  2. Import it behind a dev-only guard so it never reaches production. Open the section that matches your setup:

    React, Astro, SvelteKit, Vue - anything on Vite

    Use import.meta.env.DEV in your app's entry file, e.g. src/main.ts or src/main.tsx:

    if (import.meta.env.DEV) {   import('timeline-lens').then((m) => m.init()); } // dev-only. Ships nothing to production.
    Next.js

    App Router - the panel has to run in the browser, so wrap it in a small client component. Create app/timeline-lens.tsx:

    'use client';   import { useEffect } from 'react';   export function TimelineLens() {   useEffect(() => {     if (process.env.NODE_ENV === 'development') {       import('timeline-lens').then((m) => m.init());     }   }, []);   return null; }

    Then render it once from the root layout, app/layout.tsx:

    import { TimelineLens } from './timeline-lens';   export default function RootLayout({ children }) {   return (     <html lang="en">       <body>         {children}         <TimelineLens />       </body>     </html>   ); }

    Pages Router - add the same guard to pages/_app.tsx:

    import { useEffect } from 'react'; import type { AppProps } from 'next/app';   export default function App({ Component, pageProps }: AppProps) {   useEffect(() => {     if (process.env.NODE_ENV === 'development') {       import('timeline-lens').then((m) => m.init());     }   }, []);   return <Component {...pageProps} />; }
    Webpack - Create React App or a plain config

    Check process.env.NODE_ENV near the top of your entry file, e.g. src/index.tsx, before the app renders:

    if (process.env.NODE_ENV === 'development') {   import('timeline-lens').then((m) => m.init()); }
    No bundler

    Skip the npm install and load it as an ES module straight from a CDN, inside a plain <script type="module"> tag on your page:

    <script type="module">   if (location.hostname === 'localhost') {     import('https://esm.sh/timeline-lens').then((m) => m.init());   } </script>

    No bundler means no process.env or import.meta.env, so swap the hostname check for whatever actually marks your dev environment.

  3. Start your dev server and reload the page. A small trigger button mounts in the corner of the screen, rendered inside a Shadow DOM root so its styles can never collide with yours.

  4. Click the trigger. Every GSAP tween, CSS animation or transition, and WAAAPI call already running on the page shows up as a scrubbable track, nothing else to configure.

gsap is never a hard dependency: it resolves through a dynamic import that's allowed to fail, so the panel still works for CSS and WAAPI detection even when GSAP isn't installed.

Prefer not to touch your codebase at all? See the browser extension below.

How to use

Open it, scrub it, close it.

init() mounts a floating trigger button and renders the panel inside a Shadow DOM root, so its styles never collide with your page. Once open:

  • Every detected animation appears as a named, scrubbable track: GSAP tweens and timelines, CSS animations and transitions, and element.animate() calls all show up side by side.
  • Play, pause, reverse, change speed, or drag the playhead directly. You're driving the real animation instances, not a recording.
  • Hover a track and its real DOM target highlights on the page, so you always know exactly what's moving.
  • If an animation disappears from the page, hover over the item in the list and force a reset of the html/css state to see it again. This is useful for CSS transitions that only exist while a class is applied, or GSAP tweens edit the style of elements after they finish.
  • Click a track to see its full properties: targets, timing, easing, keyframes, and a best-effort reconstruction of the call that authored it.
  • A compact mini player is available for when you want the transport controls without the full track list on screen.

Call toggle() instead of init() if you want one function that mounts when closed and unmounts when open. See it for yourself:


Get the NPM package

Installing GSAP

If you don't have GSAP already, install it first.

npm install gsap

No extra configuration needed. Once GSAP is installed, timeline-lens will automatically read gsap.globalTimeline to detect and display every tween and timeline you create, including ones that already finished and got pruned.

For more information on GSAP, see gsap.com

Browser extension

Free to install. Pro is $9.99, once.

The npm package above is free forever, and so is the extension's core: install it from the Chrome Web Store to get the same detection engines as the npm package (GSAP, CSS animations and transitions, element.animate() and WAAPI) on any page you visit, whether or not it exposes window.gsap, with nothing to install in your own project. A one-time $9.99 Pro upgrade is optional - no subscription, no recurring charge - and goes straight to funding development.

Free · Pro $9.99 one-time

Click the button below or search for Timeline Lens on the Chrome Extension Store to install. Click the toolbar icon to mount the panel, click again to toggle it away.

If you're upgrading to Pro, you'll need to reload the page once payment has been completed. Payment and licensing for the Pro upgrade are handled by Extension Pay, not stored by us - see our Privacy Policy for what that involves.

Install Chrome extension - Beta

Purchasing & refunds

Not happy with the Pro upgrade? You have 14 days.

The npm package is free forever and the basic browser extension is free too. The only thing you can buy is the browser extension's Pro upgrade - a one-time $9.99 payment. Before you request a refund, please see our FAQs for common questions about what the Pro upgrade does and how it works.

14-day money-back guarantee

If you're not happy with the Pro upgrade, you have 14 days from the date of purchase to request a full refund. Email [email protected] with the email address you paid with, and we'll process it - no reason required.

Refunds are issued back through Stripe to your original payment method. See our Terms of Service for the full purchasing terms.

FAQs

Common questions.

Is timeline-lens free?

Yes. The npm package is completely free - no paid tier, ever. The browser extension has a free version too; a one-time $9.99 unlocks Pro. See Browser extension below for what that gets you.

Does it create, edit, or export animations?

No. It is read-only from start to finish: it detects and displays animations that already exist in your hand-written code. Nothing is authored, rewritten, or exported.

Does it work with React, Next.js or Vue?

Yes. It reads gsap.globalTimeline and document.getAnimations() directly, so it is framework-agnostic. It has been verified against a vanilla JS site, a React + @gsap/react site, and a server-rendered Next.js (App Router) site.

Will it bloat my production bundle?

Not if you guard it. Mount it behind import.meta.env.DEV (or your bundler's dev-only equivalent) and it never ships to production at all. See How to install.

Is there a browser extension?

Yes. It’s free on the Chrome Web Store, with a one-time $9.99 Pro upgrade available. See Browser extension above.

I've bought the Pro upgrade, but the panel says upgrade?

Once you've completed payment, reload chrome and the panel will unlock.

Why doesn't the extension always detect GSAP animations on every site?

The extension reads GSAP straight off window.gsap in the page's own JavaScript. Sites that load GSAP via a <script> tag expose it there automatically. But most modern sites bundle GSAP as a module (Webpack, Vite, Next.js) and never attach it to window - so there's nothing for the extension to read. It's not a bug, just how JS modules work. This is primarily a debugging tool for your own development sites. Live sites have different bundling setups, so the extension can't always see GSAP or animations.

If it can't read window.gsap, does the extension show anything at all?

Often, yes. Even without a live reference, the extension can usually tell GSAP is running by spotting the internal marker GSAP stamps onto elements it animates. You'll see a note confirming GSAP is present, just without the ability to list or scrub individual animations.

Does this affect CSS animations and transitions too?

No. CSS animations, CSS transitions, element.animate() calls, and Motion-authored animations are detected through the browser's own Web Animations API, which works the same regardless of how the page was bundled. These show up even on sites where GSAP itself can't be inspected.

Why is it missing an animation I can definitely see happening?

A few common causes: Timing. The extension only scans when you click Scan/Rescan, not continuously, so a finished non-repeating animation may already be gone; Callback tweens. scheduled function calls are filtered out on purpose, not shown as animations; and Multiple GSAP copies. if a page loads more than one instance of GSAP, only the one on window.gsap is visible.

Is there a way to get full detection on a site where GSAP isn't exposed?

If it's your own site, use the npm package instead - installed directly into your project, it shares the exact same GSAP module the page uses, so it doesn't depend on window.gsap being exposed at all. For sites you don't control, this is a limitation of inspecting from outside the page.

Support the project

Free npm package. Free extension. $9.99 Pro.

The timeline-lens npm package is free to use,no paid tier, ever. The browser extension is free too - a one-time $9.99 Pro upgrade is optional, and it's the main way this project stays funded. If the npm package alone has saved you a debugging session, a coffee or a star also helps keep it going.

Install Chrome extension - Beta Buy me a coffee Star it on GitHub

Contact

Questions, bugs, ideas?

Reach the team behind timeline-lens by opening an issue on GitHub.