Introduction to Custom Items

In modern Minecraft Bedrock (format version 1.20.50 and newer), an item is defined almost entirely inside a single JSON file in your behavior pack's items folder. This file declares the item's unique identifier, where it appears in the Creative inventory, and a list of components that dictate how it looks and behaves.

Your resource pack still plays a role, but you no longer need a matching item definition file inside the resource pack. Instead, the resource pack holds the PNG image file, a mapping file called item_texture.json that gives that image a short name, and a language file for clean localization. The behavior pack references that short texture name directly using the minecraft:icon component.

Every custom item starts in the BP/items/ directory. You can organize this folder with subdirectories however you like; the game reads every JSON file inside it. The root object requires a format_version and a minecraft:item object containing a description and components.

In the description block, you must declare an identifier using a custom namespace (never use minecraft as your namespace). You can also add a menu_category block to place the item into the Creative inventory. Without a menu_category, the item is still obtainable via the /give command, but players browsing the Creative tabs will not see it.

Inside the components block, you attach built-in mechanics. Even the most basic crafting ingredient needs an icon so it does not render as a blank or broken slot. In the example below, we create a simple ruby item that stacks up to 64, shows a custom icon, and sits in the Items tab of the Creative menu.

{
  "format_version": "1.20.50",
  "minecraft:item": {
    "description": {
      "identifier": "wiki:ruby",
      "menu_category": {
        "category": "items"
      }
    },
    "components": {
      "minecraft:icon": {
        "texture": "wiki_ruby"
      },
      "minecraft:max_stack_size": 64
    }
  }
}

Notice that the minecraft:icon component in our behavior pack does not point to a file path like textures/items/ruby.png. Instead, it asks for a texture shortname: wiki_ruby. To make the game understand what wiki_ruby means, you must register it in the resource pack inside RP/textures/item_texture.json.

This file acts as a dictionary for all item icons in your pack. Under the texture_data object, you create a key matching the shortname you used in your behavior pack, and point its textures property to the path of your PNG file (leaving off the .png extension). Always prefix your shortnames with your namespace or project initials so you do not accidentally overwrite vanilla textures or clash with other add-ons.

{
  "resource_pack_name": "wiki_pack",
  "texture_name": "atlas.items",
  "texture_data": {
    "wiki_ruby": {
      "textures": "textures/items/ruby"
    }
  }
}

If you load into a world right now and run /give @s wiki:ruby, you will receive the item with its texture, but hovering over it will show the raw translation key: item.wiki:ruby. You have two ways to fix this.

The proper way for released add-ons is to add an entry to your resource pack's language files, such as RP/texts/en_US.lang. By default, an item without a display name component looks for the key item.<namespace>:<identifier>.name, though newer format versions without the .name suffix also resolve in some contexts. To avoid confusion and have full control over the translation key or literal string, you can explicitly add the minecraft:display_name component in your behavior pack, or translate the default key in your .lang file.

If you use the minecraft:display_name component, its value field can either be a raw string (like "Ruby") or a custom localization key (like "item.wiki.ruby") that you then define in your .lang file.

item.wiki:ruby=Ruby

Once your base item loads in-game, you turn it into a functional object by adding more components inside the components block of your behavior pack file. Bedrock items are purely component-driven: an item becomes a food when you give it minecraft:food, or a fuel source when you give it minecraft:fuel.

Here are the most reliable, stable components you will use when building your first set of items.

Static items like ingots, gems, and fuels only require the JSON components shown above. When you want an item to run custom logic—such as teleporting a player when right-clicked, applying potion effects on hit, or losing durability in custom ways—you pair your JSON item with the Script API.

In older versions of Bedrock, items used JSON event responses to trigger commands or animations directly inside the item file. Those JSON item events have been removed from modern format versions. Today, interactive items are built by registering a custom component in JavaScript using the @minecraft/server module, and then attaching that custom component's identifier inside the components block of your BP/items/ file.

Applies to format_version 1.20.50 and newer (including 1.21.x). No experimental toggles are required for standard data-driven items and the components listed on this page.

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