🖼️ html-thumb-view

See your HTML files as thumbnails in Windows Explorer — not generic browser icons.

---

A tiny Windows shell extension that makes File Explorer show a live rendered preview of every .html, .htm and .xhtml file — exactly like image thumbnails — instead of the boring generic browser icon. Great for folders full of mockups, reports, exported dashboards, email templates, design prototypes, or any HTML you browse visually.

It renders each file with Microsoft Edge in headless mode, so what you see is the real page — modern CSS, flexbox/grid, web fonts, gradients, the works.

✨ Features

• 🎨 Real rendering — uses the Edge (Chromium) engine, so thumbnails look like the actual page.
• 🔗 Relative assets work — the provider gets the file path (not just a stream), so linked CSS/images/fonts resolve correctly.
• 👤 No admin required — installs per-user in HKCU. No UAC prompt.
• 🧩 Covers .html, .htm, .xhtml out of the box (easy to add more).
• ⚡ Cached by Windows — each file renders once; Explorer caches the result in its thumbnail cache.
• 🧹 Clean uninstall — one script puts everything back.

🚀 Quick start

git clone https://github.com/lucasftas/html-thumb-view
cd html-thumb-view
pwsh -File scripts\Install-HtmlThumbnails.ps1 -ClearCache

That's it. Open any folder with HTML files and you'll see rendered previews. Want to see it immediately on a sample? Try the included examples/ folder.

-ClearCache flushes Explorer's thumbnail cache and restarts Explorer so already-cached icons get re-rendered. Drop it if you only care about files Explorer hasn't cached yet.

🧪 Verify it works (without trusting the cache)

pwsh -File scripts\Test-HtmlThumbnail.ps1 -Path examples\dashboard.html

This calls the real shell pipeline (IShellItemImageFactory::GetImage with SIIGBF_THUMBNAILONLY, which fails instead of falling back to an icon) and saves the produced thumbnail to a PNG — proof the provider ran end-to-end.

🗑️ Uninstall

pwsh -File scripts\Uninstall-HtmlThumbnails.ps1 -ClearCache

Removes the registry entries and binaries; HTML files go back to the default browser icon.

📋 Requirements

OS	Windows 10 / 11 (x64)
Edge	Microsoft Edge (Chromium) — used as the headless renderer (ships with Windows)
.NET	.NET SDK 10 — used by the install script to build the provider (dotnet publish)

⚙️ Configuration

Defaults live in src/ThumbnailProvider.cs:

• Framing — renders a 1280×1024 viewport and crops the top of the page (browser-preview look). Tweak RenderW / RenderH and the crop logic in BuildHBitmap.
• Extensions — edit the $Extensions array in scripts/Install-HtmlThumbnails.ps1 (e.g. add .svg).
• Debug log (off by default) — set HTMLTHUMB_LOG=1 or create %TEMP%\htmlthumb.logon; the provider writes each step to %TEMP%\htmlthumb.log.

🔍 How it works

Windows asks registered IThumbnailProvider COM handlers to produce thumbnails. This one:

1. Implements IThumbnailProvider + IInitializeWithFile (.NET 10, COM-hosted via EnableComHosting).
2. On request, launches msedge.exe --headless=new --screenshot against the file's file:// URL.
3. Decodes the PNG, crops/scales it, and returns a 32-bit top-down DIB as the HBITMAP.

The one gotcha that makes or breaks it: DisableProcessIsolation

By default Windows loads thumbnail providers inside an isolated surrogate (prevhost.exe), which only hands the provider an IInitializeWithStream — never a file path. A provider that relies on IInitializeWithFile (like this one, so relative assets resolve) gets instantiated but never initialized, and extraction fails with WTS_E_FAILEDEXTRACTION (0x8004B200).

The fix is a single registry value on the CLSID:

HKCU\Software\Classes\CLSID\{…}\DisableProcessIsolation = 1   (DWORD)

This loads the provider in-process in explorer.exe, where the file-based init is used. The install script sets it automatically and registers the handler in every place the shell looks (the bare extension, SystemFileAssociations\<ext>, and the effective ProgId from the user's UserChoice — e.g. Edge's MSEdgeDHTML), because registering only on the bare extension is silently overridden by the ProgId.

🛠️ Building from source

dotnet publish src -c Release -r win-x64 --self-contained false

Produces HtmlThumbnailProvider.comhost.dll plus the managed assembly. The install script does this for you and copies the output to %LOCALAPPDATA%\Programs\HtmlThumbnailProvider.

❓ FAQ

Is it slow? The first thumbnail per file spins up Edge headless (~1–2 s). After that Windows caches it, so it's instant until the file changes.

Does it run my page's JavaScript? Yes — it's a real Chromium render, with a short virtual-time budget so async content has a moment to settle.

Is it safe? It renders local files headlessly and returns a bitmap. Because it loads in-process in Explorer, every code path is wrapped to fail closed (returns "no thumbnail") rather than disturb Explorer.

Why per-user / no admin? Registration is under HKCU, so you don't need elevation and it only affects your account.

🤝 Contributing

Issues and PRs welcome — more file types, smarter framing, prebuilt release binaries, a WIC-based renderer to drop the Edge dependency… have at it.

📄 License

MIT © lucasftas — see LICENSE.

_{If this saved you from a wall of identical browser icons, consider leaving a ⭐.}