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() React & Next.js

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.

Coming soon A browser extension is in testing ahead of its Chrome Web Store launch, for a one-click check on any page: no window.gsap exposure or install step required.

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

FAQs

Common questions.

Is timeline-lens free?

Yes. It is MIT licensed and free, with no paid tier. If it saves you debugging time, a Buy Me a Coffee tip toward development is appreciated, but never required.

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?

Coming soon. See Browser extension below.

Support the project

Free and MIT licensed, always.

timeline-lens is free to use, with no paid tier planned. If it's saved you a debugging session, the best ways to help keep it going are a coffee or a star.

Buy me a coffee Star it on GitHub

Contact

Questions, bugs, ideas?

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