JSON UI Best Practices

When you put a file such as hud_screen.json into your resource pack, the game merges your file on top of the vanilla one from the bottom of the pack stack upward. If you copy the entire vanilla file into your pack and edit a few lines in the middle, you overwrite every single control in that file.

This causes two immediate problems. First, the next time a game update adds a new button or changes a vanilla binding on that screen, your pack will erase the new vanilla element or crash the screen because a required binding is missing. Second, your pack will be completely incompatible with any other resource pack touching the same screen.

Instead, declare only the namespace and the specific control you need to alter, then use the modifications array. The engine supports operations like insert_back, insert_front, remove, and replace to surgically alter a control's children without redefining the parent.

{
  "namespace": "hud",

  "my_pack_custom_badge": {
    "type": "image",
    "texture": "textures/ui/my_pack/badge",
    "size": [16, 16],
    "anchor_from": "top_right",
    "anchor_to": "top_right",
    "offset": [-4, 4]
  },

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

Every JSON UI file declares a namespace at the top, or inherits one from the file it is merging with. If you place twenty helper templates directly inside the hud or start_screen namespace using generic names like icon_panel or title_text, you risk colliding with either a future vanilla control or another creator's pack.

Keep your modification files tiny. Put all of your complex panel hierarchies, button templates, and animations into your own dedicated files registered in _ui_defs.json, under a namespace prefixed with your studio or pack identifier. In the vanilla screen file, reference your external template across namespaces using the @namespace.control_name inheritance syntax.

{
  "ui_defs": [
    "ui/my_pack/common_templates.json",
    "ui/my_pack/custom_hud_panels.json"
  ]
}

JSON UI is an inheritance-driven language. Copy-pasting a fifty-line button or slot definition ten times makes your file hard to read and slow for the game to parse at screen load.

Define a single base control and expose the parts that change as $-prefixed variables with sensible default values. When you instantiate that template inside a controls array, pass only the variables that differ for that specific instance. Note that variables are resolved when the UI tree is built, not at runtime; if a value needs to change while the screen is open, it must be driven by a data binding instead of a variable.

{
  "namespace": "my_pack_common",

  "stat_row": {
    "type": "stack_panel",
    "orientation": "horizontal",
    "size": ["100%", 14],
    "$stat_label|default": "Stat",
    "$stat_texture|default": "textures/ui/WarningGlyph",
    "controls": [
      {
        "icon": {
          "type": "image",
          "texture": "$stat_texture",
          "size": [12, 12]
        }
      },
      {
        "padding": {
          "type": "panel",
          "size": [4, "100%"]
        }
      },
      {
        "label": {
          "type": "label",
          "text": "$stat_label",
          "color": "$body_text_color",
          "size": ["fill", "default"]
        }
      }
    ]
  }
}

JSON UI cannot read scoreboards, entity properties, or dynamic properties directly. It can only read the internal C++ data bindings that the current screen exposes. When you need to send custom gameplay data from a behaviour pack (commands or Script API) to the HUD or a form, the standard pattern is to encode a prefix tag into a string binding the screen already receives, such as #hud_title_text_string or #form_button_text.

Make your prefix distinct—for example, a short alphanumeric tag specific to your pack—and use string comparison in the target_property_name:#visible binding expression. Always hide or resize the vanilla title display only when your specific prefix is NOT present, or intercept it on a duplicate control so normal /title commands and other add-ons using the same channel continue to work.

{
  "namespace": "my_pack_hud",

  "mana_bar_panel": {
    "type": "panel",
    "size": [100, 12],
    "bindings": [
      {
        "binding_name": "#hud_title_text_string",
        "binding_name_override": "#title_text",
        "binding_type": "global"
      },
      {
        "binding_type": "view",
        "source_property_name": "(not ((#title_text - 'MYPACK_MANA:') = #title_text))",
        "target_property_name": "#visible"
      }
    ]
  }
}

Screen resolutions and GUI scale sliders vary wildly across phones, consoles, and PCs. Avoid hardcoding pixel offsets from the edges of the screen to center an element. Instead, use anchor_from and anchor_to (such as center, bottom_middle, or top_right) combined with percentage sizes like "100%c" (fit to children) or "fill" inside a stack_panel.

Be deliberate with the layer property. Every child control inherits its parent's layer plus its own layer offset. If your custom panel renders behind a vanilla slot highlight or overlaps the chat screen, give your root container a modest layer offset rather than setting layer: 9999, which can cause your HUD element to draw on top of the pause menu or inventory tooltips.

When adding custom background panels, include a companion .json file right next to your .png texture in textures/ui/ defining nineslice_size. A 9-slice definition lets a tiny 16x16 border texture stretch cleanly to any panel size without blurring the corners.

Mojang is gradually replacing older JSON UI screens (such as the play screen, settings, and death screen) with a newer web-based interface framework internally called Ore UI. Once a vanilla screen is migrated to the new system, its old JSON UI file stops being used by the game.

Before investing weeks into a complex overhaul of a menu screen, check whether that screen is still driven by JSON UI in current Bedrock previews. For in-game menus driven by behaviour packs, prefer modifying server_form.json (used by ActionFormData and ModalFormData in the Script API) or the HUD, as these remain heavily relied upon by add-on creators.

Applies to all modern Bedrock versions (1.16.0 through 1.21+). No experimental toggle is required, as JSON UI loads directly from any active Resource Pack. Note that individual vanilla screens are gradually being replaced by Ore UI in newer 1.21+ updates.

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