Item Components Reference

minecraft:display_name

Sets the item display name within Minecraft: Bedrock Edition. This component may also be used to pull from the localization file by referencing a key from it.

const item = new Item('Secret Weapon', 'myaddon:secret_weapon');
item.addComponent('minecraft:display_name', { value: 'Secret Weapon' });

// Using a localization key
item.addComponent('minecraft:display_name', { value: 'item.secret_weapon.name' });

minecraft:icon

Determines the icon to represent the item in the UI and elsewhere. References texture short names defined in resource_pack/textures/item_texture.json.

Tip: This component can also be represented as a simple string shorthand.

const item = new Item('My Gem', 'myaddon:my_gem');
// Object form with textures map
item.addComponent('minecraft:icon', { textures: { default: 'my_gem' } });

// Simple string shorthand
item.addComponent('minecraft:icon', 'my_gem');

minecraft:max_stack_size

Determines how many of an item can be stacked together.

Tip: This component supports a simple integer shorthand.

const item = new Item('Super Soup', 'myaddon:super_soup');
// Object form
item.addComponent('minecraft:max_stack_size', { value: 1 });

// Simple integer shorthand
item.addComponent('minecraft:max_stack_size', 16);

minecraft:rarity

Specifies the base rarity and subsequently color of the item name when the player hovers the cursor over the item. The rarity of an item automatically increases when enchanted, either to Rare when the base rarity is Common or Uncommon, or Epic when the base rarity is Rare. Requires format_version 1.21.30+.

Tip: This component supports a simple string shorthand.

const item = new Item('Legendary Blade', 'myaddon:legendary_blade');
// Object form
item.addComponent('minecraft:rarity', { value: 'epic' });

// Simple string shorthand
item.addComponent('minecraft:rarity', 'rare');

minecraft:glint

Determines whether the item has the enchanted glint render effect on it.

Tip: This component supports a simple boolean shorthand.

const item = new Item('Shiny Shard', 'myaddon:shiny_shard');
// Simple boolean shorthand
item.addComponent('minecraft:glint', true);

minecraft:hover_text_color

Determines the color of the item name when hovering over it.

Tip: This component supports a simple string shorthand.

const item = new Item('Fire Orb', 'myaddon:fire_orb');
item.addComponent('minecraft:hover_text_color', 'gold');

minecraft:tags

Determines which tags are included on a given item. Tags can be used to filter items in recipes, loot tables, and trade tables.

const item = new Item('Custom Apple', 'myaddon:custom_apple');
item.addComponent('minecraft:tags', {
    tags: ['minecraft:is_food', 'myaddon:custom_food']
});

minecraft:stacked_by_data

Determines whether the same items with different aux values can stack. Also defines whether the item entities can merge while floating in the world.

Tip: This component supports a simple boolean shorthand.

const item = new Item('Dye Item', 'myaddon:dye_item');
item.addComponent('minecraft:stacked_by_data', true);

minecraft:durability

Sets how much damage the item can take before breaking, and allows the item to be combined at an anvil, grindstone, or crafting table.

See also: minecraft:repairable, minecraft:durability_sensor

const sword = new Item('Diamond Blade', 'myaddon:diamond_blade');
sword.addComponent('minecraft:durability', {
    max_durability: 500,
    damage_chance: { min: 60, max: 100 }
});

minecraft:durability_sensor

Enables an item to emit effects when it receives damage. The item also needs a minecraft:durability component. When multiple thresholds are met, only the threshold with the lowest durability after applying the damage is considered.

Requires: minecraft:durability

const pick = new Item('Fragile Pick', 'myaddon:fragile_pick');
pick.addComponent('minecraft:durability', { max_durability: 100 });
pick.addComponent('minecraft:durability_sensor', {
    durability_thresholds: [
        { durability: 20, particle_type: 'flame', sound_event: 'break' },
        { durability: 5, particle_type: 'crit', sound_event: 'hurt' }
    ]
});

minecraft:repairable

Defines the items that can be used to repair a defined item, and the amount of durability each item restores upon repair. Each entry needs to define a list of strings for items that can be used for the repair and an optional repair_amount for how much durability is repaired.

Requires: minecraft:durability

const armor = new Item('Custom Chestplate', 'myaddon:custom_chestplate');
armor.addComponent('minecraft:durability', { max_durability: 200 });
armor.addComponent('minecraft:repairable', {
    repair_items: [
        {
            items: ['minecraft:diamond'],
            repair_amount: 'query.max_durability * 0.25'
        }
    ]
});

minecraft:damage

Determines how much extra damage the item does on attack. This value is added to the base attack damage.

Tip: This component supports a simple integer shorthand.

const sword = new Item('Iron Mace', 'myaddon:iron_mace');
// Object form
sword.addComponent('minecraft:damage', { value: 7 });

// Simple integer shorthand
sword.addComponent('minecraft:damage', 5);

minecraft:damage_absorption

Allows an item to absorb damage that would otherwise be dealt to its wearer. The item needs to be equipped in an armor slot. The absorbed damage reduces the item's durability, with any excess damage being ignored. Requires a minecraft:durability component.

Requires: minecraft:durability and minecraft:wearable

const helm = new Item('Shield Helm', 'myaddon:shield_helm');
helm.addComponent('minecraft:durability', { max_durability: 150 });
helm.addComponent('minecraft:wearable', { slot: 'slot.armor.head' });
helm.addComponent('minecraft:damage_absorption', {
    absorbable_causes: ['attack', 'projectile']
});

minecraft:enchantable

Determines what enchantments can be applied to the item. Not all enchantments will have an effect on all item components.

const pick = new Item('Custom Pickaxe', 'myaddon:custom_pickaxe');
pick.addComponent('minecraft:enchantable', {
    slot: 'pickaxe',
    value: 14
});

minecraft:food

Sets the item as a food component, allowing it to be edible to the player. Requires minecraft:use_modifiers to function properly.

See also: minecraft:use_modifiers, minecraft:use_animation

const stew = new Item('Magic Stew', 'myaddon:magic_stew');
stew.addComponent('minecraft:food', {
    nutrition: 8,
    saturation_modifier: 'good',
    can_always_eat: true,
    using_converts_to: 'bowl',
    effects: [
        { name: 'regeneration', chance: 1.0, duration: 10, amplifier: 1 }
    ]
});
stew.addComponent('minecraft:use_modifiers', { use_duration: 1.6 });
stew.addComponent('minecraft:use_animation', 'eat');

minecraft:use_animation

Specifies which animation is played when the player uses the item.

Tip: This component supports a simple string shorthand. Common values: "eat", "drink", "bow", "crossbow", "spear", "block", "spyglass", "brush".

const item = new Item('Custom Potion', 'myaddon:custom_potion');
// Simple string shorthand
item.addComponent('minecraft:use_animation', 'drink');

minecraft:use_modifiers

Determines how long an item takes to use in combination with components such as Shooter, Throwable, or Food.

See also: minecraft:food, minecraft:shooter, minecraft:throwable

const item = new Item('Custom Apple', 'myaddon:custom_apple');
item.addComponent('minecraft:use_modifiers', {
    use_duration: 1.6,
    movement_modifier: 0.35
});

minecraft:cooldown

Adds a cooldown to an item, preventing it from being used again for a specified duration. Items sharing the same category will enter cooldown together when any one of them is used.

const charge = new Item('Wind Charge', 'myaddon:wind_charge');
charge.addComponent('minecraft:cooldown', {
    category: 'wind_charge',
    duration: 0.5
});

minecraft:compostable

Specifies that an item is compostable and provides the chance of creating a composting layer in the composter. Requires format_version 1.21.60+.

const leaf = new Item('Custom Leaf', 'myaddon:custom_leaf');
leaf.addComponent('minecraft:compostable', { composting_chance: 30 });

minecraft:projectile

Defines an item as a projectile that can be shot from dispensers or used as ammunition with minecraft:shooter. When combined with minecraft:throwable, this component specifies which entity is spawned when the item is thrown.

See also: minecraft:throwable, minecraft:shooter

const bomb = new Item('Snowball Launcher', 'myaddon:snowball_launcher');
bomb.addComponent('minecraft:projectile', {
    projectile_entity: 'minecraft:snowball',
    minimum_critical_power: 1.25
});

minecraft:shooter

Compels an item to shoot projectiles, similarly to a bow or crossbow. Requires minecraft:use_modifiers to function properly. Ammunition used by this component must have the minecraft:projectile component.

See also: minecraft:projectile, minecraft:use_modifiers

const bow = new Item('Snowball Bow', 'myaddon:snowball_bow');
bow.addComponent('minecraft:shooter', {
    ammunition: [{
        item: 'minecraft:snowball',
        use_offhand: true,
        search_inventory: true,
        use_in_creative: true
    }],
    max_draw_duration: 1,
    scale_power_by_draw_duration: true
});
bow.addComponent('minecraft:use_modifiers', { use_duration: 3.0 });

minecraft:throwable

Makes an item throwable by the player, similar to a snowball or ender pearl. Use with minecraft:projectile to specify which entity is spawned when thrown.

See also: minecraft:projectile

const charge = new Item('Wind Charge', 'myaddon:wind_charge');
charge.addComponent('minecraft:projectile', {
    projectile_entity: 'wind_charge_projectile'
});
charge.addComponent('minecraft:throwable', {
    do_swing_animation: true,
    launch_power_scale: 1.5,
    max_launch_power: 1.5
});

minecraft:block_placer

Sets the item as a placer item component for blocks. Items with this component will place a block when used. This component can also render the block as the item's icon. Requires format_version 1.21.50+.

const placer = new Item('Dirt Placer', 'myaddon:dirt_placer');
placer.addComponent('minecraft:block_placer', {
    block: 'minecraft:dirt',
    use_on: ['dirt', 'grass'],
    replace_block_item: true
});

minecraft:entity_placer

Allows an item to place entities into the world. Additionally, in version 1.19.80 and above, the component allows the item to set the spawn type of a monster spawner.

const egg = new Item('Turtle Egg', 'myaddon:turtle_egg');
egg.addComponent('minecraft:entity_placer', {
    entity: 'minecraft:turtle',
    use_on: ['minecraft:sand']
});

minecraft:seed

Sets the item as a seed that can be planted to grow crops. When used on valid ground, the seed will place the specified crop block. Requires format_version 1.10.0+.

const seed = new Item('Magic Seeds', 'myaddon:magic_seeds');
seed.addComponent('minecraft:seed', {
    crop_result: 'myaddon:magic_crop',
    plant_at: ['minecraft:farmland']
});

minecraft:interact_button

A boolean or string that determines if the interact button is shown in touch controls, and what text is displayed on the button. When set to true, the default "Use Item" text will be used.

const item = new Item('Magic Wand', 'myaddon:magic_wand');
// Show default "Use Item" button
item.addComponent('minecraft:interact_button', true);

// Show custom button text
item.addComponent('minecraft:interact_button', 'Cast Spell');

minecraft:record

Used by record items to play music. When placed in a jukebox, the item will play the specified sound event.

const disc = new Item('Custom Disc', 'myaddon:custom_disc');
disc.addComponent('minecraft:record', {
    sound_event: 'record.pigstep',
    duration: 149,
    comparator_signal: 13
});

minecraft:wearable

Sets the wearable item component, which allows an item to be worn by a player in a specified equipment slot. When a non-hand armor slot is used, the max stack size is automatically set to 1.

const chest = new Item('Custom Chestplate', 'myaddon:custom_chestplate');
chest.addComponent('minecraft:wearable', {
    slot: 'slot.armor.chest',
    protection: 8,
    dispensable: true
});

minecraft:hand_equipped

Determines if an item is rendered like a tool while it is in a player's hand (tilted and raised, like a sword or pickaxe).

Tip: This component supports a simple boolean shorthand.

const sword = new Item('Custom Sword', 'myaddon:custom_sword');
// Simple boolean shorthand
sword.addComponent('minecraft:hand_equipped', true);

minecraft:allow_off_hand

Determines whether the item can be placed in the off hand slot of the inventory.

Tip: This component supports a simple boolean shorthand.

const shield = new Item('Custom Shield', 'myaddon:custom_shield');
item.addComponent('minecraft:allow_off_hand', true);

minecraft:dyeable

Enables custom items to be dyed in cauldrons. Both the item and its attachable need format_version 1.21.30 or greater.

const tunic = new Item('Leather Tunic', 'myaddon:leather_tunic');
tunic.addComponent('minecraft:dyeable', { default_color: '#175882' });

minecraft:storage_item

Enables an item to store data of a dynamic container associated with it. A dynamic container is a container for storing items that is linked to an item instead of a block or entity. To interact with the storage container, the item must also have minecraft:bundle_interaction. Requires format_version 1.21.40+.

See also: minecraft:bundle_interaction

const bundle = new Item('Custom Bundle', 'myaddon:custom_bundle');
bundle.addComponent('minecraft:max_stack_size', 1);
bundle.addComponent('minecraft:storage_item', {
    max_slots: 64,
    max_weight_limit: 64,
    weight_in_storage_item: 4,
    allow_nested_storage_items: true,
    banned_items: ['minecraft:shulker_box']
});

minecraft:storage_weight_limit

Specifies the maximum weight limit that a storage item can hold.

const bag = new Item('Small Bag', 'myaddon:small_bag');
bag.addComponent('minecraft:storage_weight_limit', { max_weight_limit: 32 });

minecraft:storage_weight_modifier

Specifies the weight of this item when inside another Storage Item.

const item = new Item('Light Item', 'myaddon:light_item');
item.addComponent('minecraft:storage_weight_modifier', { weight_in_storage_item: 1 });

minecraft:bundle_interaction

Enables the bundle-specific interaction scheme and tooltip for an item. Requires minecraft:storage_item to be defined. Requires format_version 1.21.40+.

Note: Custom bundle items need three textures registered in textures/textures_list.json: the base icon, _open_front, and _open_back variants.

Requires: minecraft:storage_item

const bundle = new Item('Custom Bundle', 'myaddon:custom_bundle');
bundle.addComponent('minecraft:storage_item', { max_slots: 64 });
bundle.addComponent('minecraft:bundle_interaction', {
    num_viewable_slots: 8
});

minecraft:fuel

Allows this item to be used as fuel in a furnace to cook other items.

Tip: This component supports a simple number shorthand.

const fuel = new Item('Compact Coal', 'myaddon:compact_coal');
// Object form
fuel.addComponent('minecraft:fuel', { duration: 80 });

// Simple number shorthand
fuel.addComponent('minecraft:fuel', 20);

minecraft:fire_resistant

Determines whether the item is immune to burning when dropped in fire or lava.

const ingot = new Item('Netherite Scrap', 'myaddon:netherite_scrap');
ingot.addComponent('minecraft:fire_resistant', { value: true });

minecraft:should_despawn

Determines if the item should eventually despawn while floating in the world.

Tip: This component supports a simple boolean shorthand.

const item = new Item('Persistent Gem', 'myaddon:persistent_gem');
// Prevent the item from despawning
item.addComponent('minecraft:should_despawn', false);

minecraft:can_destroy_in_creative

Determines if the item can be used by a player to break blocks when in creative mode.

Tip: This component supports a simple boolean shorthand.

const sword = new Item('Creative Sword', 'myaddon:creative_sword');
item.addComponent('minecraft:can_destroy_in_creative', true);

minecraft:liquid_clipped

Determines whether the item interacts with liquid blocks on use.

Tip: This component supports a simple boolean shorthand.

const item = new Item('Water Wand', 'myaddon:water_wand');
item.addComponent('minecraft:liquid_clipped', true);

minecraft:swing_duration

Duration, in seconds, of the item's swing animation played when mining or attacking. Affects visuals only and does not impact attack frequency or other gameplay mechanics.

const hammer = new Item('Slow Hammer', 'myaddon:slow_hammer');
hammer.addComponent('minecraft:swing_duration', { value: 0.6 });

minecraft:swing_sounds

Overrides the swing sounds emitted by the user when attacking.

const spear = new Item('Custom Spear', 'myaddon:custom_spear');
spear.addComponent('minecraft:swing_sounds', {
    attack_hit: 'item.spear.attack_hit',
    attack_miss: 'item.spear.attack_miss',
    attack_critical_hit: 'attack.critical'
});

minecraft:digger

Configures an item as a digging tool, allowing it to break specific blocks faster than normal. Define which blocks are affected and the speed multiplier for each.

const axe = new Item('Custom Axe', 'myaddon:custom_axe');
axe.addComponent('minecraft:digger', {
    use_efficiency: true,
    destroy_speeds: [
        { block: { tags: "query.any_tag('wood')" }, speed: 6 },
        { block: 'minecraft:coal_ore', speed: 2 }
    ]
});

minecraft:kinetic_weapon

Allows an item to deal kinetic damage and its effects. Damage is computed every tick while in use, based on both the user's and the target's velocity projected onto the view vector via a dot product. After damage_multiplier and damage_modifier are applied, the resulting damage is floored to the nearest lower integer.

const lance = new Item('Jousting Lance', 'myaddon:jousting_lance');
lance.addComponent('minecraft:kinetic_weapon', {
    reach: { min: 0, max: 5 },
    damage_multiplier: 2,
    damage_modifier: 1,
    delay: 5,
    damage_conditions: {
        min_speed: 0.5,
        min_relative_speed: 0.2,
        max_duration: -1
    }
});

Kinetic Effect Conditions

Conditions that need to be satisfied for a specific effect of a kinetic weapon to be applied. Used as sub-objects in damage_conditions, knockback_conditions, and dismount_conditions within minecraft:kinetic_weapon.

minecraft:piercing_weapon

Allows an item to deal damage to all entities detected in a straight line along the user's view vector. Items with this component cannot destroy blocks, as the attack action always takes priority regardless of what the user is looking at.

const spear = new Item('Piercing Spear', 'myaddon:piercing_spear');
spear.addComponent('minecraft:piercing_weapon', {
    reach: { min: 0, max: 5 },
    hitbox_margin: 0.3
});