Image to Mosaic
A zero-dependency library for transforming images into interactive tile surfaces
How This Project Found Its Way Back
In 2009, I built a small open source library called imJQMosaic. It took an image, reconstructed it as a grid mosaic, and added simple animations and hover effects that felt new for the time. The code lived on Google Code for years and quietly did its job until the platform shut down in 2015.
Google offered an automatic migration to GitHub, so I assumed the project had moved. What I didn't realize was that the export had failed. The GitHub repo sat empty for almost a decade, and I never noticed.
There's a quiet lesson in that. We build on platforms that feel permanent until they aren't. Code that works today can vanish tomorrow — not through neglect, but through the shifting ground beneath it.
Fast forward to now. While building the M-Verse Playground and revisiting older creative experiments, I wanted to include that mosaic project. Opening the repository showed that everything was gone. No files. No history. Just an empty shell.
Losing the original codebase could have been the end of it. Instead, it became a fresh starting point.
After completing the rebuild, I discovered that another developer had preserved the original code in a gist years ago. The 2009 version still exists. But by then, the new library had already become something else entirely — not a restoration, but a reinvention.
Starting Again With a Clearer Idea
The first version depended on jQuery and belonged to an era where web graphics were limited and performance was modest. It did what it could with the tools available.
Rebuilding it meant I could rethink everything. What if the mosaic wasn't just a static grid? What if patterns, motion, spacing, and interactivity could all become part of the expression? How flexible could it be if it had no dependencies at all?
These questions shaped the new library: image-to-mosaic.
What the New Mosaic Layer Offers
The updated version goes far beyond the original concept. It can reconstruct an image using patterns like grid, brick, diamond, strips, voronoi, or puzzle. It supports density controls, spacing, tile shapes, reveal animations, and hover interactions.
Tiles can fade, scale, flip, slide, or scatter into place. On hover, they can lift with shadows, glow, zoom, tilt dynamically with mouse position, blur, pop, or spotlight. You can drag them, shuffle them, or bind click events. Everything responds smoothly and updates in real time.
Instead of a single visual effect, the mosaic becomes an interactive surface — something you engage with rather than simply look at.
Principles Behind the Rebuild
Several design ideas guided the project.
Focus on lightness
The library is about 10KB when compressed and uses no external dependencies. This makes it easy to try, embed, and adopt.
Treat patterns as expressive tools
Each pattern gives the image a different mood. A grid feels structured and rational. A brick layout introduces rhythm through offset. A diamond pattern adds angular energy. Voronoi feels organic and irregular, almost cellular. Puzzle pieces interlock with curved tabs that invite interaction. The pattern becomes part of the storytelling — the same photograph can feel clinical or alive depending on how it's fragmented.
Let motion guide attention
Animations, delays, and easing curves give the mosaic a sense of unfolding. Tiles can appear sequentially, randomly, spiraling from center, or radiating outward. The image arrives over time, which changes how it is perceived. There's something cognitively different about watching a picture assemble itself — you notice parts before you grasp the whole.
Encourage interaction
Hover effects, dragging, tile shuffling, and callbacks make the viewer part of the experience. The image stops being a fixed object and becomes something you can touch, rearrange, and explore.
Make usage simple
You can control everything through JavaScript or place a single tag in a page:
<mosaic-image src="photo.jpg" pattern="diamond" density="40"></mosaic-image>
This keeps the barrier to entry low.
Under the Hood
The engine follows a clear pipeline designed for flexibility and real-time responsiveness.
Tile generation creates and positions elements according to the chosen pattern and density. Each pattern has its own geometry logic — grid uses simple rows and columns, brick offsets alternating rows, diamond applies CSS clip-paths to create rotated squares. Voronoi distributes jittered points across a grid and computes cell boundaries through polygon clipping against half-planes. Puzzle generates SVG paths with bezier curve tabs and holes that interlock naturally.
Image display avoids expensive pixel manipulation entirely. Each tile is a div with the source image as its background. The library calculates background-size to match the container and background-position to show the correct slice. This approach is fast, resolution-independent, and lets the browser handle all the heavy lifting.
Animation orchestration sequences tile reveals using CSS animations and custom properties. Delay calculators determine when each tile appears — sequentially by index, randomly, radiating from center, or spiraling outward. The timing engine sets --animation-delay on each tile, letting CSS handle the actual motion.
Interaction layer handles hover effects and drag behavior through event delegation. Hover states like tilt track mouse position and update CSS custom properties in real time. Drag operations update tile coordinates directly and can swap positions when tiles overlap. State changes are scoped to individual elements, keeping everything smooth even at high densities.
The architecture separates concerns cleanly — patterns, delay calculators, animations, and hover effects are independent modules with consistent interfaces. New patterns or effects can be registered without touching core logic.
Why Fragmentation Changes How We See
There's something worth pausing on here.
When you break an image into pieces, you change the act of looking. A photograph viewed whole is absorbed in a glance — the eye takes in the composition, the subject, the mood, and moves on. But a mosaic forces a different kind of attention. You see the tiles before you see the picture. You notice color relationships, density variations, the rhythm of the pattern.
This isn't just a visual trick. It's a shift in perception. The image becomes something you read rather than something you receive. Fragmentation slows the eye down and makes the familiar strange again.
That's what makes mosaic effects more than decoration. At their best, they're a way of asking: what happens when we look more carefully?
What Stayed With Me
I didn't expect this project to mean much beyond a portfolio piece. But rebuilding something I thought was lost turned out to feel different than building something new.
The original code is gone, and that's fine. What mattered was the idea — that images don't have to be static, that interaction can be part of seeing, that a grid of colored tiles can hold more life than a flat photograph.
Some ideas survive their implementations. This one waited a decade for another chance.