Item Components Reference

Every custom item in a behavior pack is defined by a JSON file inside the BP/items/ folder. Inside this file, the minecraft:item object holds a description block (for the identifier and creative menu placement) and a components block. The components block is a dictionary of component identifiers, each prefixed with minecraft:, that grant specific traits to your item.

In modern Bedrock versions, an item's visual representation is also controlled directly from the behavior pack using components like minecraft:icon and minecraft:display_name. You no longer create a separate item definition file in the resource pack for standard items; the resource pack only needs to hold the actual PNG textures, language strings, and a terrain_texture.json or item_texture.json mapping.

The format_version at the top of your JSON file dictates which components are valid and what syntax they expect. Always use a modern stable version such as 1.20.50 or 1.21.0. Older tutorials often show 1.16.100, which relied on the Holiday Creator Features toggle that has since been removed from the game.

{
  "format_version": "1.20.50",
  "minecraft:item": {
    "description": {
      "identifier": "my_pack:ruby",
      "menu_category": {
        "category": "items"
      }
    },
    "components": {
      "minecraft:icon": {
        "texture": "ruby"
      },
      "minecraft:display_name": {
        "value": "item.my_pack:ruby.name"
      },
      "minecraft:max_stack_size": 64,
      "minecraft:glint": true
    }
  }
}

Almost every custom item uses a small set of baseline components to feel like a native part of the game. Without them, your item may show up with a missing texture checkerboard, display a raw code string as its name, or stack in ways that break your intended balance.

Note that several of these components support shorthand syntax in modern format versions. For example, minecraft:max_stack_size and minecraft:glint can accept a single number or boolean directly rather than requiring a nested object with a value key, though the object form is still widely supported.

To make an item edible, you must combine three different components. The minecraft:food component defines how much hunger and saturation the item restores,, how it interacts with the hunger bar, and whether it leaves behind a bowl or bottle when eaten.

However, minecraft:food alone does not play an eating animation or let the player hold right-click to chew. You must pair it with minecraft:use_modifiers to set how long it takes to eat, and minecraft:use_animation set to eat or drink so the game plays the right sound and hand movement.

{
  "format_version": "1.20.50",
  "minecraft:item": {
    "description": {
      "identifier": "my_pack:spiced_apple",
      "menu_category": {
        "category": "nature",
        "group": "itemGroup.name.crop"
      }
    },
    "components": {
      "minecraft:icon": {
        "texture": "spiced_apple"
      },
      "minecraft:use_animation": "eat",
      "minecraft:use_modifiers": {
        "use_duration": 1.6,
        "movement_modifier": 0.35
      },
      "minecraft:food": {
        "nutrition": 6,
        "saturation_modifier": 0.6,
        "can_always_eat": false
      }
    }
  }
}

Tools and weapons are built by combining durability, damage, and block-breaking components. Any item with minecraft:durability must have its minecraft:max_stack_size set to 1, otherwise the game will reject the file on load. To let players fix the tool in an anvil, add minecraft:repairable and list the items that can restore its health.

For weapons, minecraft:damage sets the base attack damage dealt when hitting an entity. For mining tools, minecraft:digger lets you list specific blocks or block tags alongside a speed multiplier. To make the item capable of receiving enchantments at an enchanting table or anvil, include minecraft:enchantable with a valid slot type (such as sword, pickaxe, bow, or armor_head) and an enchantability value.

{
  "format_version": "1.20.50",
  "minecraft:item": {
    "description": {
      "identifier": "my_pack:ruby_pickaxe",
      "menu_category": {
        "category": "equipment",
        "group": "itemGroup.name.pickaxe"
      }
    },
    "components": {
      "minecraft:icon": {
        "texture": "ruby_pickaxe"
      },
      "minecraft:max_stack_size": 1,
      "minecraft:hand_equipped": true,
      "minecraft:durability": {
        "max_durability": 850
      },
      "minecraft:repairable": {
        "repair_items": [
          {
            "items": ["my_pack:ruby"],
            "repair_amount": 200
          }
        ]
      },
      "minecraft:damage": {
        "value": 4
      },
      "minecraft:enchantable": {
        "value": 14,
        "slot": "pickaxe"
      },
      "minecraft:digger": {
        "use_efficiency": true,
        "destroy_speeds": [
          {
            "block": {
              "tags": "q.any_tag('stone', 'metal', 'diamond_pick_diggable')"
            },
            "speed": 8
          }
        ]
      }
    }
  }
}

Beyond tools and food, components let items interact with equipment slots and the world. The minecraft:wearable component turns an item into armor or headgear. You specify the slot (such as slot.armor.head, slot.armor.chest, slot.armor.legs, or slot.armor.feet) and a protection integer for how many armor points it grants.

If an item should be thrown like a snowball or shot from a bow, minecraft:projectile identifies which entity identifier to spawn, while minecraft:throwable lets the player toss it directly by holding right-click. For items that place blocks or entities into the world—such as custom seeds, doors, or spawn eggs—use minecraft:block_placer or minecraft:entity_placer to link the item to the target block or entity identifier.

If you have read older tutorials, you may have seen event responses like on_use, on_hit_entity, or damage_item inside item JSON files. Those Holiday Creator Features events were removed from Bedrock in version 1.20.40 and will cause errors in current versions.

Today, custom item logic (such as shooting a fireball on right-click, applying potion effects when hitting a mob, or reducing durability when mining with a custom tool) is handled through the Script API paired with the minecraft:custom_components component. In your item JSON, you list the string identifiers of your custom components inside minecraft:custom_components, and in your TypeScript or JavaScript file, you register their behavior during world initialization using the itemComponentRegistry.

Applies to Bedrock Edition 1.20.50 through 1.21+. All components covered on this page are stable and do not require any experimental toggles. Note that minecraft:custom_components requires format_version 1.21.0 or higher (or the Beta APIs toggle in 1.20.80).

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