Vanilla Item Usage Components Reference

Making an item edible requires three components working together. While minecraft:food defines the nutrition and saturation restored to the player, the item cannot actually be eaten in-game unless you also give it a use animation and a use duration.

The minecraft:use_modifiers component controls how long the player must hold the use button before the item is consumed, as well as how much their movement speed is reduced while using it. The minecraft:use_animation component tells the client which animation and sound set to play—typically eat or drink.

{
  "format_version": "1.20.50",
  "minecraft:item": {
    "description": {
      "identifier": "my_pack:spiced_apple",
      "menu_category": {
        "category": "equipment",
        "group": "itemGroup.name.miscFood"
      }
    },
    "components": {
      "minecraft:icon": "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,
        "using_converts_to": "minecraft:stick"
      }
    }
  }
}

To create an item that launches an entity—such as a custom snowball, kunai, or splash potion—pair minecraft:throwable with minecraft:projectile. The throwable component handles the player input (either a quick right-click or a charge-and-release gesture), while the projectile component dictates which entity identifier is spawned into the world.

Note that the entity you reference in projectile_entity must already exist in your behavior pack (or be a vanilla projectile) and have its own minecraft:projectile entity component configured to actually fly and deal damage.

{
  "format_version": "1.20.50",
  "minecraft:item": {
    "description": {
      "identifier": "my_pack:pebble",
      "menu_category": {
        "category": "equipment"
      }
    },
    "components": {
      "minecraft:icon": "pebble",
      "minecraft:max_stack_size": 16,
      "minecraft:Cooldown": {
        "category": "pebble_throw",
        "duration": 0.5
      },
      "minecraft:throwable": {
        "do_swing_animation": true,
        "launch_power_scale": 1.0,
        "max_draw_duration": 0.0,
        "min_draw_duration": 0.0,
        "scale_power_by_draw_duration": false
      },
      "minecraft:projectile": {
        "minimum_critical_power": 1.0,
        "projectile_entity": "minecraft:snowball"
      }
    }
  }
}

When an item needs to place a block or spawn a mob when used against a block face, use minecraft:block_placer or minecraft:entity_placer. Both components allow you to restrict which surfaces the item will work on using the use_on array. This is how vanilla seeds restrict themselves to farmland.

If you use minecraft:block_placer on a custom item to place a custom block, it replaces the block's default auto-generated item when the identifiers match, or acts as a separate seed/placer item when the identifiers differ.

{
  "format_version": "1.20.50",
  "minecraft:item": {
    "description": {
      "identifier": "my_pack:tomato_seeds"
    },
    "components": {
      "minecraft:icon": "tomato_seeds",
      "minecraft:block_placer": {
        "block": "my_pack:tomato_crop",
        "use_on": [
          "minecraft:farmland"
        ]
      }
    }
  }
}

Items that take damage during use need minecraft:durability. By itself, this component only gives the item a durability bar and a maximum health pool; another mechanic (such as minecraft:digger, weapon combat, or a custom script) must actually apply the damage.

To let players maintain that durability at an anvil, add minecraft:repairable. You can define multiple repair entries, mixing raw materials (like ingots) with self-repair (combining two damaged copies of the same item). The repair_amount field accepts plain integers as well as Molang expressions.

{
  "format_version": "1.20.50",
  "minecraft:item": {
    "description": {
      "identifier": "my_pack:copper_chisel"
    },
    "components": {
      "minecraft:icon": "copper_chisel",
      "minecraft:max_stack_size": 1,
      "minecraft:durability": {
        "max_durability": 180,
        "damage_chance": {
          "min": 60,
          "max": 100
        }
      },
      "minecraft:repairable": {
        "repair_items": [
          {
            "items": [
              "minecraft:copper_ingot"
            ],
            "repair_amount": 45
          },
          {
            "items": [
              "my_pack:copper_chisel"
            ],
            "repair_amount": "context.other->query.remaining_durability + 0.05 * context.other->query.max_durability"
          }
        ]
      }
    }
  }
}

Two smaller utility components frequently accompany the usage components above: minecraft:cooldown and minecraft:fuel. The cooldown component prevents the player from activating the item again for a set duration (in seconds), rendering the familiar white sweeping overlay on the hotbar icon. Any items that share the same category string will enter cooldown simultaneously, just like vanilla Ender Pearls or Chorus Fruit.

The minecraft:fuel component has only one field, duration, measured in seconds. An item with a duration of 10.0 will smelt exactly one item in a standard furnace. You can safely combine fuel with food, block placers, or tools.

Applies to format_version 1.20.50 and newer (including 1.21.x). All components on this page are stable and do not require any experimental toggles.

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