# Transformer Explainer: a GPT-2 model running in the browser, with the internals on screen

> Transformer Explainer is an MIT-licensed SvelteKit visualization that loads GPT-2 client-side and shows attention, embeddings and next-token probabilities as you type. It is a teaching tool, not an inference server.

**poloclub/transformer-explainer** — Transformer Explained Visually: Learn How LLM Transformer Models Work with Interactive Visualization

- Repository: https://github.com/poloclub/transformer-explainer
- Website: https://poloclub.github.io/transformer-explainer/
- Stars: 8,593 · Forks: 967
- Language: JavaScript
- License: MIT
- Published: 2026-09-09 · Updated: 2026-09-09 · Language: en
- Canonical page: https://hysenlabs.com/projects/poloclub-transformer-explainer

## What Transformer Explainer is for, and who it is aimed at

The README describes Transformer Explainer as an interactive visualization tool for learning how Transformer-based models like GPT work. The specific problem it addresses is that the internals of a text-generative model are invisible in normal use: you type a prompt, tokens come back, and the arithmetic that produced them stays hidden. Transformer Explainer puts that arithmetic on screen. You supply your own text, and the tool shows how internal components and operations combine to predict the next tokens.

The audience follows from that framing. It is written for anyone learning the architecture, which in practice means students in an NLP or deep learning course, instructors who want a live demo rather than a diagram, and engineers who work with LLM APIs but have never traced a forward pass. The project is academic in origin: it comes from the Polo Club at Georgia Institute of Technology, and the README points to a paper published in the Proceedings of the 2026 CHI Conference on Human Factors in Computing Systems. That matters for how you read the tool. It is built to explain a mechanism, not to serve traffic or host models.

## How the visualization works: GPT-2 in the browser, not on a server

The mechanism is visible in package.json. The runtime dependencies are @xenova/transformers, onnxruntime-web, gsap and katex. @xenova/transformers runs Hugging Face Transformers models in JavaScript, and onnxruntime-web executes the exported ONNX graph in the browser. Together they mean the GPT-2 forward pass happens on the client. No request leaves the machine to compute a prediction, and there is no backend in the repository to deploy.

The interface layer is SvelteKit with Tailwind CSS, and the diagrams are drawn with d3 and d3-sankey. A Sankey layout is a sensible choice for the flow through attention heads and the feed-forward block, because it shows how weight is distributed across paths rather than only which paths exist. KaTeX is present for rendering the equations that accompany the diagrams, and GSAP handles the transitions between views.

The consequence of this architecture is that the model is fixed. The README says the tool runs a live GPT-2 model, and nothing in the file listing or package.json suggests a configuration path for swapping in a different checkpoint. If you want to explain a modern instruction-tuned model, the visual explanation will be of GPT-2's architecture, which is the same family but not the same scale.

## Running Transformer Explainer locally: clone, npm install, npm run dev

The README gives prerequisites of Node.js v20 or higher and NPM v10 or higher, and the package.json engines field agrees, requiring Node.js at least 20. The steps are four commands.

```bash
git clone https://github.com/poloclub/transformer-explainer.git
cd transformer-explainer
npm install
npm run dev
```

npm run dev maps to vite dev, which starts the Vite development server. The README says to open http://localhost:5173 in your browser afterwards. That port is Vite's default, and the README states it explicitly, so if something else already holds 5173 the server will report a different one and you should read the terminal output rather than assume.

Expect the first load to take longer than later ones. The model weights have to reach the browser before any prediction can be shown, and the repository has no bundled weights: the dependencies are the JavaScript runtime for Transformers and the ONNX web runtime, not the model itself. If you are demonstrating this in a room with unreliable Wi-Fi, load the page once before the session starts.

The README also lists a build script (vite build), a preview script, and a deploy script that pushes the build directory to GitHub Pages with gh-pages. The live demo at poloclub.github.io/transformer-explainer is the hosted version of that same static build.

## What Transformer Explainer will not tell you

The clearest limitation is the model. Everything the tool visualizes is GPT-2, and the README does not describe a way to load another checkpoint. If your question is why a specific production model refuses a request, hallucinates a citation or follows one instruction format better than another, this tool cannot answer it. Architecture explanation and model behaviour debugging are different jobs.

The second limitation is scale. GPT-2 is small enough that its attention matrices and token probabilities can be drawn legibly in a browser tab. That legibility is exactly what makes it a good teaching subject and a poor proxy for a model with orders of magnitude more parameters. A student who understands GPT-2's attention pattern has understood the mechanism, not the behaviour of a large model.

The third is that the project is a visualization, not a library. There is no documented API for embedding the components in your own application, no published package name to install, and the version field in package.json is still 0.0.1, matching the single release from 2024-06-11. The README's contact section directs questions to the issue tracker rather than to a support channel. Treat it as a site you visit or fork, not a dependency you add.

One more practical point: the README does not document rollback, version pinning for the model weights, or an offline mode. If your environment blocks the network fetch that supplies the weights, the visualization has nothing to show.

## How it compares with CNN Explainer and Diffusion Explainer

The README itself points to sibling projects from the same group: CNN Explainer, GAN Lab and Diffusion Explainer. The difference in approach is the subject matter and what the interactive surface controls. CNN Explainer visualizes a convolutional network for image classification, where the input is an image and the interesting structure is spatial, so the explanation revolves around filters and feature maps. Diffusion Explainer covers how Stable Diffusion turns a text prompt into an image, a process with a denoising loop rather than a single forward pass.

Transformer Explainer sits on the text side, where the input is a string you type and the output is a probability distribution over the next token. That makes the interaction cheaper: no image upload, no sampling loop to step through, just text in and token probabilities out, with the internal attention and feed-forward operations shown along the way. If your subject is autoregressive text generation, this is the sibling to use. If your subject is vision, the other two cover ground this one does not.

A different kind of alternative is a notebook walkthrough such as a TransformerLens or nnsight session, where you load a model in Python and inspect activations directly. That approach scales to models the browser cannot hold and lets you script experiments, but it requires a Python environment and gives you arrays, not diagrams. Transformer Explainer trades that flexibility for a page a student can open and start typing into.

## Maintenance, licence and what a fork costs you

The repository is not archived, and the last push was on 2026-06-06, roughly three months before this writing. There is one release, v0.0.1, dated 2024-06-11, so the version number tells you little about the state of the code; the commit history does. The dependency list is current for a SvelteKit project, with Svelte 5, SvelteKit 2 and Vite 5, which suggests the maintainers have kept the toolchain moving even without cutting a new release.

The software is under the MIT License, per the README and the LICENSE file at the repository root. MIT is permissive: you can reuse the code, including in a commercial teaching product, provided you keep the copyright notice and licence text. That is a summary of the licence, not legal advice; read the LICENSE file and the citation block in the README, which asks that academic use cite the CHI 2026 paper.

The upgrade cost of a fork is mostly the frontend toolchain. Svelte 5 and SvelteKit 2 are both major versions with their own migration notes, and the project also carries ESLint 8 with the older @typescript-eslint 7 packages, plus Prettier 3 with the Tailwind plugin pinned at 0.5. If you fork and want to keep dependencies current, expect to spend your time on the lint and format configuration before you touch the visualization. The scripts for that are npm run lint, npm run format and npm run check, the last of which runs svelte-check against tsconfig.json.

## Conclusion

Adopt Transformer Explainer if you teach, study or write about how a decoder-only Transformer produces the next token, and you want students to change the input themselves instead of watching a slide. Do not adopt it if you need to inspect a model you actually deploy: the README describes GPT-2 running in the browser through @xenova/transformers and onnxruntime-web, and nothing in the repository suggests a way to point it at another checkpoint or a hosted endpoint. Verify two things before you build a lesson around it: that the static build still resolves its model weights from the network on first load, and that the npm run dev server on port 5173 starts on your machine with Node.js v20 or higher.

## FAQ

### What is Transformer Explainer?

It is an interactive visualization tool for learning how Transformer-based models such as GPT work, built by the Polo Club at Georgia Institute of Technology. It runs a live GPT-2 model in the browser so you can enter your own text and watch the internal components predict the next tokens.

### What is a transformer explainer?

In this project the term names a specific tool rather than a category: a web page that shows the operations of a text-generative Transformer as you interact with it. The README describes it as running GPT-2 in the browser and visualizing how internal components and operations work together to predict the next tokens.

### Can you explain transformers in a simple way?

The project's answer is to show rather than tell: you type text, and the visualization displays how the model's internal components and operations combine to produce the next-token prediction. The README frames the goal as helping anyone learn how Transformer-based models like GPT work, with a demo video linked for an overview before you try it.

### How do you explain transformers to someone?

The README's approach is to let the person experiment with their own text and observe in real time how the internal components and operations work together to predict the next tokens. The tool is available as a hosted page at poloclub.github.io/transformer-explainer, so no setup is needed to start.

## Sources

- [License: MIT](https://github.com/poloclub/transformer-explainer/blob/main/LICENSE)
- [poloclub/transformer-explainer on GitHub](https://github.com/poloclub/transformer-explainer)
- [Project website](https://poloclub.github.io/transformer-explainer/)
- [README](https://github.com/poloclub/transformer-explainer/blob/main/README.md)
- [Releases](https://github.com/poloclub/transformer-explainer/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/poloclub-transformer-explainer