JSON UI Architecture and Reference

All user interface files live inside the ui/ directory of your Resource Pack. Unlike blocks or entities, the game does not automatically scan every file in this folder. Instead, it relies on a master registry file located at RP/ui/_ui_defs.json. If you create a wholly new JSON file for your interface templates, you must list its path inside the ui_defs array of this file, otherwise the engine will ignore it.

When you want to alter an existing vanilla screen—such as the HUD (hud_screen.json), the pause menu (pause_screen.json), or the chest interface (chest_screen.json)—you create a file with the exact same name and path in your pack. Bedrock merges your file on top of the vanilla definition. This means you do not need to copy the entire vanilla file into your pack; you only need to declare the specific namespace and the elements you intend to add or modify.

A second global file, RP/ui/_global_variables.json, holds color palettes and constant values prefixed with a dollar sign (such as $generic_button_text_color). You can override these variables or define your own constants here to maintain consistent styling across multiple screens.

{
  "ui_defs": [
    "ui/my_custom_elements.json",
    "ui/hud_screen.json"
  ]
}

Every JSON UI file requires a top-level "namespace" string. This acts as an address book for all elements defined inside that file. Every other key at the root of the JSON document is a UI control definition. Controls are the building blocks of a screen, ranging from invisible layout containers to text labels, textures, and interactive buttons.

To avoid repeating properties, JSON UI uses template inheritance through the @ symbol in a control's key. Writing "[email protected]_panel" tells the parser to create a control named my_label that inherits all properties from the empty_panel control inside the common namespace. If the template you are inheriting from resides in the same file, you omit the namespace and just write "my_sub_label@my_label".

You can pass custom values into an inherited template using variables prefixed with a dollar sign ($). Inside the template definition, you can assign a default value to that variable using the |= operator. When another control inherits that template, it can supply a new value for the variable, allowing you to build reusable components like standardized item slots or styled headers.

{
  "namespace": "custom_ui",

  "base_greeting_label": {
    "type": "label",
    " $text_content|default": "Hello World",
    "text": "$text_content",
    "color": [ 1.0, 0.8, 0.2 ],
    "shadow": true
  },

  "custom_banner@custom_ui.base_greeting_label": {
    "$text_content": "Welcome to the Server!"
  }
}

Every base control must declare a "type" property. Sizing and positioning are relative to the parent control. The "size" property accepts a two-element array representing width and height. Values can be absolute pixels (such as 100), percentages of the parent's size ("50%"), sized to fit their children ("100%c"), or sized relative to the sibling controls.

Alignment is controlled by pairing "anchor_from" and "anchor_to". The anchor_from property chooses which point on the parent control to attach to, while anchor_to chooses which point on the child control touches that parent point. Valid anchor strings are top_left, top_middle, top_right, left_middle, center, right_middle, bottom_left, bottom_middle, and bottom_right. Once anchored, the "offset" array shifts the element in [X, Y] pixels or percentages.

If you overwrite the root control of a vanilla screen directly, your pack will conflict with any other pack that touches the same screen, and it may break when Minecraft updates the base UI. To avoid this, use the "modifications" array. This feature lets you inject, move, or remove child controls inside a vanilla panel without replacing the panel's entire definition.

In the example below, a custom watermark panel is injected at the back of the vanilla HUD screen's root_panel. By using "insert_back", the game preserves all existing HUD elements—like the hotbar, health bars, and chat—and simply appends the new control to the end of the children list.

{
  "namespace": "hud",

  "watermark_panel": {
    "type": "panel",
    "size": [ 100, 20 ],
    "anchor_from": "top_right",
    "anchor_to": "top_right",
    "offset": [ -10, 10 ],
    "controls": [
      {
        "title@custom_ui.custom_banner": {}
      }
    ]
  },

  "root_panel": {
    "modifications": [
      {
        "array_name": "controls",
        "operation": "insert_back",
        "value": [
          {
            "[email protected]_panel": {}
          }
        ]
      }
    ]
  }
}

Because JSON UI is not a scripting language, it cannot read arbitrary game states or run Molang queries. Instead, it communicates with the game engine through the "bindings" array. Hardcoded C++ data sources—exposed with a hashtag prefix like #hud_title_text_string or #visible—can be bound to JSON UI properties that start with a hashtag.

A common pattern for add-on creators is intercepting the text of a title command or an actionbar message, checking if it matches a specific tag, and turning a custom UI panel visible when it does. You read a hardcoded value using "binding_name", rename it using "binding_name_override", and then evaluate it inside a special "#visible" binding using "binding_type": "view" and a simple expression string.

Keep in mind that available hashtag bindings are strictly limited to the screen they belong to. You cannot pull an anvil's text input binding onto the HUD screen, nor can you invent custom binding names in a Behavior Pack script unless you pass them through an existing text channel like the title, actionbar, or scoreboard objective name.

{
  "namespace": "hud",

  "conditional_alert_label": {
    "type": "label",
    "text": "DANGER ZONE",
    "color": [ 1.0, 0.2, 0.2 ],
    "bindings": [
      {
        "binding_name": "#hud_title_text_string"
      },
      {
        "binding_type": "view",
        "source_property_name": "(#hud_title_text_string = 'show_danger_ui')",
        "target_property_name": "#visible"
      }
    ]
  }
}

Applies to all modern Bedrock versions (1.16.0 through 1.21+). Does not require any experimental toggles, as JSON UI is a core Resource Pack system.

Read out of the game itself, so the ids match the version you are building for.