Item Tags (minecraft:tags)

Tags are applied inside the `components` object of your behavior pack item file using the `minecraft:tags` component. This component accepts a single property, `tags`, which is an array of strings.

Every tag you write should follow the `namespace:tag_name` convention. When creating your own tags for pack-specific mechanics, always use your own namespace (such as `wiki:is_copper_tool`). When you want your custom item to integrate into vanilla systems—like letting a custom pickaxe mine stone properly or sit on a decorated pot shelf—you must use the `minecraft:` namespace.

{
  "format_version": "1.20.50",
  "minecraft:item": {
    "description": {
      "identifier": "wiki:emerald_pickaxe",
      "menu_category": {
        "category": "equipment",
        "group": "itemGroup.name.pickaxe"
      }
    },
    "components": {
      "minecraft:max_stack_size": 1,
      "minecraft:durability": {
        "max_durability": 850
      },
      "minecraft:tags": {
        "tags": [
          "minecraft:is_tool",
          "minecraft:is_pickaxe",
          "minecraft:diamond_tier",
          "wiki:emerald_gear"
        ]
      }
    }
  }
}

Bedrock Edition assigns dozens of built-in tags to vanilla items and checks for them inside block definitions, entity behaviors, and crafting recipes. By adding these exact strings to your custom item's `minecraft:tags` array, you can piggyback on vanilla mechanics without rewriting vanilla files.

Tool and tier tags are the most important to know. Vanilla blocks check for tags like `minecraft:is_pickaxe` and tier tags like `minecraft:iron_tier` inside their `minecraft:destructible_by_mining` component (or hardcode the equivalent check) to decide whether a block drops its loot and how fast it breaks. Keep in mind that adding `minecraft:is_pickaxe` to your item does not automatically give it vanilla mining speeds against all blocks; you usually still need to configure the `minecraft:digger` component on your item, or ensure your custom blocks check for the tag.

One of the cleanest ways to use item tags is inside shaped and shapeless crafting recipes. Instead of writing a separate recipe file for every single custom wood type or ingot variant in your add-on, you can replace the `item` field in a recipe key or ingredient list with a `tag` field.

When the player opens a crafting table, the recipe book will automatically cycle through every loaded item—both vanilla and custom—that carries that tag in its `minecraft:tags` component.

{
  "format_version": "1.20.10",
  "minecraft:recipe_shaped": {
    "description": {
      "identifier": "wiki:emerald_rod"
    },
    "tags": ["crafting_table"],
    "pattern": [
      "#",
      "#"
    ],
    "key": {
      "#": {
        "tag": "wiki:emerald_gear"
      }
    },
    "unlock": [
      {
        "tag": "wiki:emerald_gear"
      }
    ],
    "result": {
      "item": "minecraft:stick",
      "count": 4
    }
  }
}

If you create custom blocks with `minecraft:destructible_by_mining`, you can use `item_specific_speeds` to make tools mine the block faster. Rather than listing every vanilla and custom pickaxe by identifier, use a Molang query inside the `tags` condition to match any item carrying your target tags.

The `query.any_tag` and `query.all_tags` expressions inside the `item` object let you combine tool type and tier requirements in a single line.

{
  "format_version": "1.20.60",
  "minecraft:block": {
    "description": {
      "identifier": "wiki:hardened_stone"
    },
    "components": {
      "minecraft:destructible_by_mining": {
        "seconds_to_destroy": 10.0,
        "item_specific_speeds": [
          {
            "item": {
              "tags": "query.all_tags('minecraft:is_pickaxe', 'minecraft:diamond_tier')"
            },
            "destroy_speed": 1.5
          }
        ]
      }
    }
  }
}

Outside of blocks and recipes, you can inspect item tags dynamically on entities and players. In Molang—such as inside animation controllers, render controllers, or entity filters—use `query.equipped_item_any_tag('slot.weapon.mainhand', 'wiki:emerald_gear')` to test if an entity is holding an item with at least one of the listed tags, or `query.equipped_item_all_tags` to require every tag listed.

If you are using the `@minecraft/server` Script API, the `ItemStack` class provides two built-in methods: `hasTag(tag: string)` which returns a boolean, and `getTags()` which returns an array of all tag strings currently on that item stack. This is much cleaner than maintaining large arrays of item IDs in your TypeScript or JavaScript files.

import { world, EquipmentSlot } from "@minecraft/server";

world.afterEvents.entityHitEntity.subscribe((event) => {
  const attacker = event.damagingEntity;
  const equippable = attacker.getComponent("minecraft:equippable");
  if (!equippable) return;

  const mainhandItem = equippable.getEquipment(EquipmentSlot.Mainhand);
  if (mainhandItem && mainhandItem.hasTag("wiki:emerald_gear")) {
    event.hitEntity.setOnFire(5, true);
  }
});

Stable in format_version 1.20.50 and above without any experimental toggles. Prior to 1.20.50, tags were sometimes defined as empty `tag:name` keys inside the components list, which is now deprecated.

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