Custom Item Events and the Migration to Custom Components

Between format versions 1.16.100 and 1.20.40, creators defined an events object at the bottom of their item JSON files, right alongside the components block. Components like minecraft:on_use or minecraft:weapon would point to a named event inside that file, which could then run slash commands, play sounds, damage the item, or teleport the holder.

Starting in format version 1.20.50 and finalized around 1.21.0, Mojang removed the events block and all event-triggering item components from the current item schema. If you set your item's format_version to a modern release like 1.21.10 and include an events section, the Content Log will throw a schema error and your item will either fail to load or lose its functionality. All event-driven logic for items now lives in JavaScript via the @minecraft/server module.

If you are maintaining an older add-on or reading legacy code, you will frequently encounter the 1.16.100 event pattern. Under the old Holiday Creator Features experimental toggle, an item used trigger components to call an event string when an action occurred.

Inside the event definition, responses were scoped to a target—usually holder for the player holding the item, or target for an entity that was hit. The most common responses were run_command to execute a list of slash commands, and damage to reduce the durability of the item. Because Holiday Creator Features has been completely removed from the game, files written this way will no longer function in current versions of Bedrock.

To make an item do something when used, hit, or mined with in modern Bedrock, you attach the minecraft:custom_components component in your item JSON. Instead of writing the logic in JSON, you only provide a list of custom namespace identifiers inside an array.

This keeps the JSON file purely declarative. You combine minecraft:custom_components with standard passive components like minecraft:cooldown, minecraft:durability, and minecraft:icon. When the world loads, the game links those string identifiers to event listeners that you register inside your Behavior Pack's script files.

{
  "format_version": "1.21.10",
  "minecraft:item": {
    "description": {
      "identifier": "example:wind_staff",
      "menu_category": {
        "category": "equipment"
      }
    },
    "components": {
      "minecraft:icon": "wind_staff",
      "minecraft:max_stack_size": 1,
      "minecraft:cooldown": {
        "category": "wind_staff",
        "duration": 2.5
      },
      "minecraft:custom_components": [
        "example:staff_behavior"
      ]
    }
  }
}

In your script entry file, you subscribe to the worldInitialize event to access the itemComponentRegistry. Calling registerCustomComponent lets you bind your custom identifier (such as example:staff_behavior) to an object containing the actual event handlers.

This registration must happen during the world initialization phase, before any items are ticked or loaded into inventories. Inside the callback, you receive an event data object that gives you direct access to the source entity (usually the player), the itemStack being used, and context like the block or entity that was targeted. From there, you can apply knockback, spawn particles, or run commands using the Script API.

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

world.beforeEvents.worldInitialize.subscribe((initEvent) => {
  initEvent.itemComponentRegistry.registerCustomComponent("example:staff_behavior", {
    onUse(event) {
      const player = event.source;
      const viewDir = player.getViewDirection();

      player.applyKnockback(viewDir.x, viewDir.z, 3.0, 0.6);
      player.playSound("mob.breeze.shoot");

      const cooldown = event.itemStack.getComponent("minecraft:cooldown");
      if (cooldown) {
        cooldown.startCooldown(player);
      }
    },
    onHitEntity(event) {
      const target = event.hitEntity;
      target.setOnFire(5, true);
    }
  });
});

When you register an item custom component in JavaScript, you can implement several built-in lifecycle methods on the configuration object. Each method corresponds to one of the old JSON trigger components that existed in earlier format versions.

You only need to include the methods your item actually uses. For example, a custom sword might only implement onHitEntity, while a magical food item would only implement onConsume.

Applies to Bedrock Edition 1.21.10 and newer. JSON item events were deprecated in 1.20.40 and removed alongside the Holiday Creator Features toggle in 1.21.20. The replacement minecraft:custom_components system is stable and requires no experimental toggles, though your manifest.json must include a script module dependency on @minecraft/server.

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