Vanilla Item Tags Reference

Every tag on an item is declared inside the `minecraft:tags` component in your behavior pack item JSON. This component takes a single `tags` array containing string identifiers. You can mix official `minecraft:` tags with your own namespace tags in the same array.

In modern Bedrock format versions (1.20.50 and later), `minecraft:tags` is a stable component that replaces the legacy `tag:` empty object syntax used in older format versions. Adding a tag does not automatically give an item all the components of that item class; for example, tagging an item as `minecraft:is_pickaxe` lets it mine pickaxe-gated blocks, but you still need to define `minecraft:durability` and `minecraft:digger` if you want it to take damage and mine quickly.

{
  "format_version": "1.20.80",
  "minecraft:item": {
    "description": {
      "identifier": "my_pack:ruby_pickaxe",
      "menu_category": {
        "category": "equipment",
        "group": "itemGroup.name.pickaxe"
      }
    },
    "components": {
      "minecraft:max_stack_size": 1,
      "minecraft:hand_equipped": true,
      "minecraft:durability": {
        "max_durability": 850
      },
      "minecraft:tags": {
        "tags": [
          "minecraft:is_tool",
          "minecraft:is_pickaxe",
          "minecraft:diamond_tier"
        ]
      }
    }
  }
}

The most common reason to reach for vanilla item tags is building custom tools and weapons. Vanilla blocks and custom blocks alike check the held item's tags inside their `minecraft:destructible_by_mining` component or loot tables to decide if the block should drop its item and how fast it should break.

A custom tool typically needs two tags: one declaring the tool shape (such as `minecraft:is_pickaxe`) and one declaring its harvesting tier (such as `minecraft:iron_tier`). Note that higher tier tags do not always imply lower tier tags in every custom block query, though vanilla block definitions check for any valid tier at or above the required level. If you want your custom tool to work seamlessly across both vanilla blocks and third-party add-on blocks that might check for a specific tier, you can include multiple tier tags on the same item.

Vanilla crafting and smelting recipes frequently accept an item tag instead of a hard-coded item identifier. By attaching these material tags to your custom items, players can use your custom wood, stone, or fuel in standard vanilla recipes—like crafting chests, sticks, beds, or stone tools—without you having to duplicate a single vanilla recipe file.

When creating custom trees or stone variants, place the appropriate tags on the block's item representation or on your custom item definitions so they blend naturally into survival progression.

Beyond tools and crafting, several mob behaviors, wearable interactions, and block mechanics check the tags on an item before allowing an action. For example, Piglins in the Nether check for specific gold-related tags to decide whether to attack a player, barter with them, or run toward a dropped item.

Similarly, utility blocks like bookshelves, jukeboxes, and campfires look for tags on the item in the player's hand to determine whether the item can be inserted or cooked.

You are not limited to putting vanilla tags on your items; you can also check for vanilla tags in your own recipes, Molang queries, and Script API code. In a shaped or shapeless recipe file, replace the `"item"` key inside an ingredient object with `"tag"` to accept any vanilla or custom item carrying that tag.

In Molang (used in entity behaviors, animations, and block permutations while they remain supported), you can test held items with `query.equipped_item_any_tag('slot.weapon.mainhand', 'minecraft:is_pickaxe')`. In the `@minecraft/server` Script API, you can inspect an `ItemStack` using its `.hasTag("minecraft:is_pickaxe")` or `.getTags()` methods.

{
  "format_version": "1.20.10",
  "minecraft:recipe_shaped": {
    "description": {
      "identifier": "my_pack:reinforced_stick"
    },
    "tags": ["crafting_table"],
    "pattern": [
      "#",
      "I",
      "#"
    ],
    "key": {
      "#": {
        "tag": "minecraft:planks"
      },
      "I": {
        "item": "minecraft:iron_ingot"
      }
    },
    "result": {
      "item": "minecraft:blaze_rod",
      "count": 1
    }
  }
}

The `minecraft:tags` item component is stable and requires format_version 1.20.50 or higher with no experimental toggles needed. On older format versions (1.16.100 through 1.20.40), tags were applied as empty objects prefixed with `tag:` directly inside the `components` block.

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