mcwidgets

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.

Try it in one line

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:

<iframe
  src="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:

<div id="tree" style="position: relative; width: 100%; height: 420px;"></div>

<script type="module">
  import { mountAdvancements } from "https://mcwidgets.kaban.sh/advancements/viewer.js";

  await mountAdvancements(document.getElementById("tree"), {
    bundleUrl: "https://mcwidgets.kaban.sh/bundles/vanilla/bundle.json",
  });
</script>

See Embedding with iframe and JavaScript API.

Show your own content

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.

Host it yourself

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.

Packages

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

Working on the repository

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.

Licence

MIT.

Minecraft textures and fonts are © Mojang Studios. Redistributing them, which self-hosting does, is subject to Mojang's usage guidelines.