Embeddable Minecraft GUI widgets for the web. They draw real game screens on a page, using the real textures at the real pixel sizes, so a guide site can show a screen instead of describing one.
Two widgets ship today.
Advancement viewer (@mcwidgets/advancements). The advancement screen, with tabs, connecting lines, frames, and hover tooltips. Point it at any datapack, vanilla or custom. Unlike the in-game screen it resizes: the window is nine-sliced and the tab strip re-flows to fit the box you give it.
Item GUI (@mcwidgets/itemgui). A view-only container screen. Use a vanilla texture such as the crafting table, or draw your own layout, then bind items to slots. Slots highlight under the pointer and show a vanilla-style item tooltip.
Everything is static. No server component, no connection to a running game, no accounts. Both widgets are self-contained ES modules with no runtime dependencies, and they ship no CSS file to fight with your stylesheet.
Full documentation lives in the wiki.
https://mcwidgets.kaban.sh serves the widgets, their textures, and a bundle of the vanilla advancement tree, with permissive cross-origin headers. Paste this into a page:
<iframesrc="https://mcwidgets.kaban.sh/advancements/embed.html?bundle=/bundles/vanilla/bundle.json"
style="width: 100%; height: 420px; border: 0;"
title="Minecraft advancements"
></iframe>Or mount it into your own DOM:
<divid="tree" style="position: relative; width: 100%; height: 420px;"></div><scripttype="module">import{mountAdvancements}from"https://mcwidgets.kaban.sh/advancements/viewer.js";awaitmountAdvancements(document.getElementById("tree"),{bundleUrl: "https://mcwidgets.kaban.sh/bundles/vanilla/bundle.json",});</script>See Embedding with iframe and JavaScript API.
Neither widget reads datapack JSON or game assets at runtime. You compile your content into a bundle first: one bundle.json plus the icons and textures it references. A command line preprocessor does that once, downloading every vanilla icon it needs, and the widget loads the finished bundle over HTTP.
npm ci
npm run build
node packages/advancements/bin/mcw-adv-preprocess.mjs \
--input ~/server/world/datapacks/my_pack \
--output ./public/advancements \
--exclude recipes \
--bake-lang ./en_us.json
Serve the output directory, then point the widget's bundle at its bundle.json.
The item GUI has its own preprocessor and its own small authoring format, a GUI definition plus an item library:
node packages/itemgui/bin/mcw-itemgui-preprocess.mjs --input ./my-gui --output ./public/crafting
See Building Advancement Bundles and Building Item GUI Bundles.
One command assembles the entire site, and it is the same command behind the container image and the Pages deployment.
npm run build
npm run stage # writes .host/, copy it to any static server
npm run host # or serve it locally on :8080
.host/ uses relative URLs throughout, so it works at a domain root and under a subdirectory alike, and each widget finds its own textures and font in the assets/ beside its module, so an embed needs nothing but a bundle. A production server needs Access-Control-Allow-Origin: *, Cross-Origin-Resource-Policy: cross-origin, and correct MIME types for .ttf. The nginx configuration in docker/default.conf is the reference.
See Self-hosting.
| Package | What it is |
|---|---|
@mcwidgets/advancements | The advancement viewer, and mcw-adv-preprocess |
@mcwidgets/itemgui | The item GUI, and mcw-itemgui-preprocess |
@mcwidgets/core | The shared toolkit both widgets are built on |
npm ci
npm run build # widget modules, type declarations, and both CLIs
npm test # vitest, once
npm run typecheck # every package
npm run host # stage the site and serve it on :8080
Node 20.19 or later, or Node 22.12 or later.
MIT.
Minecraft textures and fonts are © Mojang Studios. Redistributing them, which self-hosting does, is subject to Mojang's usage guidelines.