Item GUI Reference

Every setting the item GUI accepts. The iframe shell and the JavaScript API expose the same settings under different names, listed side by side below.

For task-shaped guidance, see Embedding with iframe and JavaScript API.

Settings

JavaScript option	Query parameter	Type	Default
bundleUrl	bundle	URL	required
gui	gui	GUI id	required when the bundle has more than one
items	items	object, or a slot=item string	none
itemsUrl	itemsUrl	URL of a JSON binding file	none
assetBase	assetBase	URL ending in /	assets/ beside the widget module
coreAssetBase	coreAssetBase	URL ending in /	the value of assetBase
scale	scale	1, 2, 3, 4, or auto	auto
backdrop	backdrop	transparent, dim, or a CSS colour	transparent
langUrls	lang	array of URLs, parameter repeatable	none
font	font	CSS font family	the bundled pixel font
fontUrl	fontUrl	URL of a font file	none
static	static	boolean	false

bundleUrl

The bundle.json produced by the preprocessor. See Building Item GUI Bundles.

Relative values resolve against the page that runs the widget, which for an iframe embed is embed.html on the embed host, not your page.

Texture and icon paths inside the bundle resolve against the bundle's own URL. Paths starting with http:, https:, data:, or blob: are used as written.

gui

Which GUI in the bundle to render, by its id. A bundle with exactly one GUI does not need this. A bundle with several rejects the mount without it, and the error lists the valid ids.

items and itemsUrl

Bindings from slot name to item name. Both names come from the bundle: slot names from the GUI definition, item names from the item library.

items accepts an object:

items: { crafting1: "diamond", result: "diamond_sword" }

or the string form, which is what the query parameter takes:

items=crafting1=diamond,result=diamond_sword

Percent-encode any , or = inside a slot or item name. A malformed pair fails the mount rather than being dropped, so a typo is visible.

itemsUrl points at a JSON file of the same shape as the object form. Load a layout from a file and patch one slot from the URL: itemsUrl is applied first and items wins per slot.

An unknown slot or item name fails the mount, and the error lists the valid names.

Slots with no binding stay empty. Empty slots still highlight under the pointer unless the GUI definition turns highlighting off for them.

assetBase

Where the widget's own files live: the slot highlight sprites, the tooltip frame, and the default font. The widget appends textures/gui/ and fonts/ to this value, so the URL must end with a slash. A value without a trailing slash gets one added.

It defaults to the assets/ directory beside the widget module, so every layout that keeps the two together needs no value. That covers the embed host, a copied .host/ tree, and the built dist/.

Set it when you have separated the module from its assets, which in practice means you ran the widget through your own bundler.

The tooltip box is nine-sliced from these files before the first frame is drawn, so a base that does not serve them fails the mount with a Could not load sprite error. An asset directory on another origin must send Access-Control-Allow-Origin, because these sprites are loaded with crossOrigin="anonymous" so they can be cropped.

coreAssetBase

Overrides where the tooltip sprites and the default font come from. It defaults to assetBase, because the widget ships its own copy of both.

Set it only to point several widgets at one shared copy.

scale

GUI scale, in the game's sense: one Minecraft pixel becomes this many screen pixels. auto picks the largest whole number that fits the container. Values below 1 or above 4 are clamped, and fractions are rounded down.

A forced scale that does not fit shrinks the visible area rather than clipping it.

backdrop

What is painted behind the GUI texture.

• transparent shows the page through. This is the default.
• dim draws the vertical gradient the game paints behind a container screen.
• Any other value is used as a CSS background colour, so #202020 or rgba(0,0,0,.6) both work. In a query string, percent-encode the # as %23.

langUrls and lang

JSON files of translation keys, applied in order, with later files overriding earlier ones. Label texts and item tooltips that use translate components read from them. See Text and Fonts.

In a query string the parameter repeats: &lang=base.json&lang=overrides.json.

font and fontUrl

font is a CSS font family. fontUrl loads a font file and uses it. See Text and fonts.

static

Freezes every rotation group on its first member, so nothing animates. Use it for a screenshot, a print stylesheet, or a page where motion is unwelcome.

In a query string, any value other than 0 turns it on: &static=1.

What the reader can do

• Hover a slot to highlight it and see the item's tooltip. The tooltip follows the pointer.
• On touch, tap a slot to select it. The highlight and tooltip stay until another slot is tapped.

The widget is view only. Nothing can be picked up, moved, or changed.

Tooltips may overflow the GUI and reach the edge of the container, exactly as they do in the game.

Sizes

The GUI texture's own size is the minimum. A vanilla crafting table page is 176 by 166 GUI pixels, so at scale 1 that is 176 by 166 CSS pixels. The GUI is centred in whatever container it gets and is never stretched.

The container needs an explicit width and height. See JavaScript API for the container rules.