Minecraft:Tag (Java Edition)

Tags (also called registry tags) in Minecraft:data packs allow players to group different game elements together.

Tags act as references to groups of registry entries, letting Minecraft treat multiple items, blocks, or entities as a single category. For example, the tag Template:Cd represents all log blocks, so commands or recipes using that tag automatically apply to oak logs, birch logs, and any other block included in it. Tags are one of the most powerful data pack features for organizing and modifying game behavior without editing core files.

While some tags are only used in certain data pack files, others are used in hardcoded properties of a specifics features, where modifying such tags is the only way to include or exclude a certain property from a given features without Minecraft:mods.

Usage

Tags are part of the data pack directory structure, highlighted below:

• Template:File/Template:File
  • Template:File
  • Template:File
    • Template:File
      • Template:File
        • Template:File
          • Template:File: A function tag.
        • Template:File
          • Template:File: A tag for the corresponding registry.
      • More directories…

Minecraft defines many tags in the vanilla data pack in the Template:Cd namespace. These tags are often referenced by the code or other vanilla data pack files. Modifying those tags through a data pack therefore has a direct effect. For example, vanilla block tags are used for various block behaviors, vanilla item tags are used for various item behaviors, vanilla Minecraft:advancement files and vanilla Minecraft:recipe files, and vanilla entity type tags are used for various mob behaviors. See Template:Slink section for their usages.

Resource location

The resource location of a tag is also in the format of Template:Cd, where namespace is the name of the folder that the Template:Mono folder is in, and path is the JSON file's path under the respective tag folder.

For example, JSON file 'Template:Mono' defines a block tag with the resource location of Template:Cd.

To distinguish normal contents from tags, a Template:Cd is usually required before tag's resource location.

JSON format

• Template:Nbt The root object.
  • Template:Nbt: Optional. Whether or not the contents of this tag should completely replace tag contents from different lower priority data packs with the same resource location. When Template:Cd the tag's content is appended to the contents of the higher priority data packs, instead. Defaults to Template:Cd.
  • Template:Nbt: A list of mix and match of object names and tag names. For tags, recursive reference is possible, but a circular reference causes a loading failure.
    • Template:Nbt: An object's Minecraft:resource location.
    • Template:Nbt: ID of another tag of the same type, prefixed with a Template:Cd.
    • Template:Nbt: An entry with additional options.
      • Template:Nbt: A string in one of the string formats above.
      • Template:Nbt: Whether or not loading this tag should fail if this entry is not found, true by default (also for the string entries). A tag that fails to load can still be referenced in any data pack and be (re)defined in other data packs. In other words, only the entries in this JSON file are ignored if this entry cannot be found.

Examples

Basic block tag

{
  "replace": false,
  "values": [
    "minecraft:oak_log",
    "minecraft:birch_log",
    "minecraft:spruce_log"
  ]
}

This tag could be saved at data/example/tags/block/my_logs.json and used in commands or loot tables as #example:my_logs.

Referencing another tag

{
  "replace": false,
  "values": [
    "#minecraft:logs",
    "minecraft:cherry_log"
  ]
}

This adds Template:Cd to the vanilla logs tag without overwriting its contents.

Using the replace field

{
  "replace": true,
  "values": [
    "minecraft:diamond_block"
  ]
}

Setting Template:Cd to Template:Cd completely overrides any lower-priority tags with the same name, replacing their contents entirely.

Optional entries

{
  "values": [
    { "id": "example:custom_item", "required": false }
  ]
}

Optional entries prevent load errors when a referenced object is missing (for example, in a different modded setup).

List of tag types

This section lists the tag types that are used by the game to affect its behavior in various ways, as well as those that are populated by default, even if the game does not use them to control some behavior.

It is possible to define tags for any Minecraft:registry and also functions. The list below show only the ones used by the game.

• Block
• Item
• Function
• Fluid
• Entity type
• Game event
• Biome
• Flat level generator preset
• World preset
• Structure
• Cat variant
• Point of interest type
• Painting variant
• Banner pattern
• Instrument
• Damage type
• Enchantment
• Dialog
• Timeline
• Potion
• Villager trade
• Configured feature

Behavior and priority

When multiple data packs define the same tag:

• The highest-priority pack (top of the list in the data packs screen) takes precedence.
• If its Template:Cd value is Template:Cd, the tag’s contents are appended to lower-priority versions.
• If Template:Cd is Template:Cd, the tag fully replaces all lower versions.

Because tags merge across data packs, they are commonly used by mods and servers to extend vanilla behavior without overwriting files. Many vanilla tags, such as Template:Cd or Template:Cd, are referenced by block properties and determine what tools or interactions are valid.

When tags are merged across data packs, their values are appended at the end of the resulting in-memory tag, in the order that the data packs load.

When reading a tag, Minecraft follows the order of the values as written in the file, proceeding recursively for each sub-tag encountered. Since the vast majority of tags are used for simple boolean checks (whether a value is or is not in a tag), the order within a tag usually doesn't matter.

However, order does matter for:

• Patterns in the Minecraft:loom menu (Template:Tag link).
• Enchantments in an item Minecraft:tooltip (Template:Tag link).
• Goat horn variants in the Minecraft:creative inventory (Template:Tag link).
• Execution order of Minecraft:functions in a function tag.
• Recipe previews that show which items may be used in recipes that use tags.

Related pages

• Minecraft:Predicate – often references tags to match grouped items or blocks
• Minecraft:Loot table – uses tag conditions for item drops
• Minecraft:Data pack – framework where tags are defined

See also

• Minecraft:Tag (Bedrock Edition)