Custom Item Enchantments (`minecraft:enchantable`)

The `minecraft:enchantable` component defines two things for your item: which group of vanilla enchantments it is allowed to receive, and how generous the enchanting table should be when rolling enchantments for it. You place this component directly inside the `components` object of your behavior pack item JSON.

For an item to behave properly with durability-based enchantments like Unbreaking or Mending, it must also include the `minecraft:max_damage` and `minecraft:durability` components, and have its `minecraft:max_stack_size` set to `1`. Enchanting stackable items causes unexpected behavior in survival inventories.

{
  "format_version": "1.20.80",
  "minecraft:item": {
    "description": {
      "identifier": "my_pack:ruby_sword",
      "menu_category": {
        "category": "equipment",
        "group": "itemGroup.name.sword"
      }
    },
    "components": {
      "minecraft:max_stack_size": 1,
      "minecraft:hand_equipped": true,
      "minecraft:durability": {
        "max_durability": 850
      },
      "minecraft:damage": {
        "value": 7
      },
      "minecraft:enchantable": {
        "slot": "sword",
        "value": 14
      },
      "minecraft:icon": "ruby_sword"
    }
  }
}

The `slot` property restricts which enchantments the game considers valid for your item. When a player places the item on an enchanting table or combines it with a book on an anvil, Bedrock checks the enchantment's internal target against the string you provide here.

Regardless of which specific slot you pick, any item with a valid `minecraft:enchantable` component and durability can also receive universal anvil enchantments such as Unbreaking, Mending, and Curse of Vanishing. If you set `value` to `0`, the item cannot be enchanted at an enchanting table, though it will still accept valid books on an anvil and work with the `/enchant` command.

The `value` integer controls the weight modifier used when the enchanting table calculates modified enchantment levels. If you want your custom tier to feel consistent with vanilla equipment, match your `value` to the closest vanilla material tier.

A low number like `5` (Stone) means even a level 30 enchanting setup will frequently yield modest enchantments. A high number like `22` (Gold) or `15` (Netherite) makes it much easier for players to roll top-tier combinations like Sharpness IV and Looting III on a single table roll.

When an item receives at least one enchantment, Bedrock automatically renders the scrolling purple foil texture over its icon. You can also force an unenchanted item to display this shimmer—or control it separately—using the `minecraft:glint` component.

In format versions 1.20.60 and later, `minecraft:glint` accepts either a simple boolean or an object containing a `value` boolean. Setting it to `true` makes the item always glow like an enchanted golden apple, even when no enchantments are present on the item stack.

{
  "format_version": "1.20.80",
  "minecraft:item": {
    "description": {
      "identifier": "my_pack:blessed_amulet"
    },
    "components": {
      "minecraft:max_stack_size": 1,
      "minecraft:glint": true,
      "minecraft:icon": "blessed_amulet"
    }
  }
}

To inspect or modify enchantments on an item stack at runtime, use the `minecraft:enchantable` item component from `@minecraft/server`. This is the standard way to award pre-enchanted custom gear from quests, or to check if a player's custom tool has a specific enchantment before running custom gameplay logic.

Note that the Script API can only apply enchantments that are legal for the item's `slot` as defined in its JSON file, and the enchantment level must stay within the vanilla minimum and maximum bounds (for example, `1` to `5` for Sharpness). Always write the modified `ItemStack` back to the container slot after changing its enchantments, because `getItem()` returns a copy rather than a live reference.

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

export function applyFireAspectToMainhand(player) {
  const equippable = player.getComponent("minecraft:equippable");
  if (!equippable) return;

  const itemStack = equippable.getEquipment(EquipmentSlot.Mainhand);
  if (!itemStack) return;

  const enchantable = itemStack.getComponent("minecraft:enchantable");
  if (!enchantable) return;

  const fireAspect = new EnchantmentType("fire_aspect");
  const enchantment = { type: fireAspect, level: 2 };

  if (enchantable.canAddEnchantment(enchantment)) {
    enchantable.addEnchantment(enchantment);
    equippable.setEquipment(EquipmentSlot.Mainhand, itemStack);
  }
}

Bedrock Edition does not currently support defining brand-new enchantment identifiers in behavior pack JSON. If your add-on requires custom enchantments—such as "Vampirism I" or "Auto-Smelt"—the standard approach is to store custom data on the `ItemStack` using dynamic properties and display the enchantment name using item lore.

When you attach lore and a dynamic property via script, you can also keep a dummy `minecraft:enchantable` component on the item so players can still apply Unbreaking or Mending at an anvil alongside your scripted effect.

Applies to format_version 1.20.50 and higher (including 1.21.x). Both the `minecraft:enchantable` JSON component and the `@minecraft/server` `ItemEnchantableComponent` API 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.