Tag (Java Edition)

Tags (also called registry tags) in 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 #minecraft:logs 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 mods.

Usage

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

• / <data pack name>
  •  pack.mcmeta
  •  data
    •  <namespace>
      •  tags
        •  function
          •  <name>.json: A function tag.
        •  <registry name>
          •  <name>.json: A tag for the corresponding registry.
      • More directories…

Minecraft defines many tags in the vanilla data pack in the minecraft 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 advancement files and vanilla recipe files, and vanilla entity type tags are used for various mob behaviors. See § List of tag types section for their usages.

Identifier

The identifier of a tag is also in the format of <namespace>:<path>, where namespace is the name of the folder that the tags folder is in, and path is the JSON file's path under the respective tag folder.

For example, JSON file 'data/wiki/tags/block/foo/example.json' defines a block tag with the identifier of wiki:foo/example.

To distinguish normal contents from tags, a # is usually required before tag's identifiers.

JSON format

• [NBT Compound / JSON Object] The root object.
  • [Boolean] replace: Optional. Whether or not the contents of this tag should completely replace tag contents from different lower priority data packs with the same identifier. When false the tag's content is appended to the contents of the higher priority data packs, instead. Defaults to false.
  • [NBT List / JSON Array] values: 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.
    • [String]: An object's identifier.
    • [String]: ID of another tag of the same type, prefixed with a #.
    • [NBT Compound / JSON Object]: An entry with additional options.
      • [String] id: A string in one of the string formats above.
      • [Boolean] required: 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 cherry_log to the vanilla logs tag without overwriting its contents.

Using the replace field

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

Setting replace to true 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

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

Used in vanilla

The list below contains 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.

•  data
  •  minecraft
    •  tags
      •  banner_pattern
      •  block
      •  block_sound_set​^{[upcoming: JE 26.4]}
      •  damage_type
      •  dialog
      •  enchantment
      •  entity_type
      •  fluid
      •  function
      •  game_event
      •  instrument
      •  item
      •  painting_variant
      •  point_of_interest_type
      •  potion
      •  timeline
      •  villager_trade
      •  worldgen
        •  biome
        •  feature
        •  flat_level_generator_preset
        •  structure
        •  world_preset

Formerly used

The list below contains tags that were previously used in the game but are no longer present in it. It is still possible to create tags of this type for commands and data packs.

•  data
  •  minecraft
    •  tags
      •  cat_variant

Usable in the game

The list below contains tags that do not have any registration in vanilla, but can be created and used in some NBT compound or JSON object field:

•  data
  •  minecraft
    •  tags
      •  item_modifier: Used in the functions field and in the inline format for sequence item modifiers.
      •  loot_table: Used in rewards.loot and criteria.[].loot_tables in advancement definition and in pools.entries.[].value in loot table.
      •  number_provider: Used in the summands field of the number provider of type sum.
      •  predicate: Used in the terms field of predicates of types all_of and any_of.
      •  recipe: Used in recipes in advancement definition, additional field of triggers crafter_recipe_crafted, recipe_crafted and recipe_unlocked
      •  slot_source: Used in the terms field and in the inline format for grup slot source.

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 replace value is false, the tag’s contents are appended to lower-priority versions.
• If replace is true, 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 #minecraft:planks or #minecraft:mineable/pickaxe, 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 loom menu (#no_item_required).
• Enchantments in an item tooltip (#tooltip_order).
• Goat horn variants in the creative inventory (#goat_horns).
• Superflat presets available in the create world menu (#visible).
• World present available during world creation (world preset tag).
• Execution order of functions in a function tag.
• Recipe previews that show which items may be used in recipes that use item tags.

History

Java Edition
1.13			17w49a				Added tags type for blocks and items.
			17w49b				Functions can now be tagged.
			17w50a				Can now include other tags (of the same type), for example #foo:bar.
							When overriding a tag, the player can now choose to replace instead of append by "replace": true.
			18w19a				Added fluids tag type.
1.14			18w43a				Added entitys tag type.
1.16.2			20w30a				Entries in a tag can now be optional with the required property.
1.16.5			20w49a				Added game events tag type.
1.18.2			22w06a				Tags can now be defined for any type in the registry, rather than only blocks, items, fluids, entity types, game events and functions previously.
1.18.2			22w07a				Added biome tags.
			pre1				Added configured structure feature tags.
1.19			22w11a				Added world preset and flat level generator preset tags.
							Configured structure feature tags are now called structure tags.
			22w14a				Added cat variant and point of interest tags.
			22w16a				Added painting variant tags.
			22w18a				Added banner pattern and instrument tags.
1.19.4			23w06a				Added damage type tags.
1.20.5			pre1				Added enchantment tags.
1.21			24w19a				Renamed several directories: items -> item blocks -> block entity_types -> entity_type fluids -> fluid game_events -> game_event
			24w21a				Renamed directory functions to function.
1.21.6			25w20a				Added dialog tags.
1.21.11			25w45a				Added timeline tags.
26.1			snap1				Added potion tags.
							Added villager trade tags.
							Added block sound set tags.
			pre1				Added configured feature tags.
26.3			snap1				Renamed directory configured_feature to feature.
Upcoming Java Edition
26.4			snap5				Added #immune_to_wither for mobs that are immune to the wither effect.
							Added #immune_to_weakness for mobs that are immune to the weakness effect.

Issues

Issues relating to "Tag" are maintained on the bug tracker. Issues should be reported and viewed there.

Related pages

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

See also

• Tag (Bedrock Edition)