Item components

This feature is exclusive to Bedrock Edition.

 

Item components are JSON formatted for items in add-ons used to change how your item looks and functions in the world, and also have NBT components that also work on vanilla items.

Applying components

They are applied within the components field within the minecraft:item field, components can also be applied to vanilla items, but unlike custom items they are limited to a few components.

Component types

minecraft:allow_off_hand

Allows the item to be placed in the offhand but does not allow use of the item.

It has no field, it must be a boolean value being either true or false.

Example:

"minecraft:allow_off_hand": true

minecraft:block_placer

Allows the item to place blocks when used, if used in survival the item is consumed.

The available fields are:

• block:
  • Defines the block that will be positioned.
• replace_block_item:
  • Defines whether the item will replace the block, it can be true or false if it is true the block and the item must have the same identifier and the minecraft:icon field can be omitted merging the two into one thing.
• use_on:
  • List of block descriptors that contain blocks this item can be used on. If left blank, all blocks will be allowed. This also applies to Creative mode.

Example:

"minecraft:block_placer": {
   "block": "wiki:custom_block",
   "replace_block_item": true,
   "use_on": [
       "minecraft:dirt",
       "wiki:custom_dirt"
   ]
}

minecraft:bundle_interaction

Enables the bundle interface and functionality on the item. The item must have the minecraft:storage_item component for this component to work.

The available fields are:

• num_viewable_slots:
  • Sets the maximum number of visible item stacks between 1 and 64 from the pack tooltip going from right to left.

Example:

"minecraft:bundle_interaction": {
    "num_viewable_slots": 12
}

minecraft:compostable

Allows an item to be used in a composter.

The available fields are:

• composting_chance:
  • Sets the chance to increase the level of the compost can be a value between 0 and 100.

Example:

"minecraft:compostable": {
    "composting_chance": 50 // 50% chance to increase compost bin level
}

minecraft:cooldown

Cooldown component. After use, all items in a specified "cooldown category" become unusable for a period of time specified in the component. The item must have the minecraft:use_modifiers component for this component to work.

The available fields are:

• category:
  • The item's cooldown category.
• duration:
  • The cooldown duration (in seconds) that items with a matching category will take to charge before becoming usable again, if this value is a negative number the item will become unusable.
• type​^{[upcoming BE 1.21.130]}:
  • Defines the action to which the cooldown applies, in a mutually exclusive manner. The cooldown of one type of action does not affect the other. This can be:
    • use — activates the cooldown only when using the item, allowing other actions.
    • attack — activates cooldown when attacking, preventing further attacks until time runs out.

Example:

"minecraft:cooldown": {
                "category": "spear",
                "duration": 1.0,
                "type": "attack"
            },

minecraft:damage

Defines how much extra damage the item deals in an attack, the value must be positive.

The available fields are:

• Any positive number, the actual damage is always the set value + 1, values above 32.767 are read as negative values so values between 0 and 255 are recommended.

Example:

"minecraft:damage": 10

minecraft:damage_absorption

Causes the item to absorb damage that would otherwise be dealt to the entity wearing it. For this to happen, the item must have the minecraft:durability component and be equipped in an armor slot.

The available fields are:

• absorbable_causes:
  • List of damage deals (such as entity_attack and magma) that can be absorbed by the item.

Example:

"minecraft:damage_absorption": {
    "absorbable_causes": ["all"]
}

minecraft:digger

Determine how quickly an item can break specific blocks.

The available fields are:

• destroy_speeds:
  • List of blocks to break, with correlated extraction speeds.
    • block — which block the item will break, and you can put the tags entry for a molang query.
    • speed — how fast the block will be broken, accepting negative values if it is negative the item will never break the block.
• use_efficiency:
  • Defines whether the item should be affected if the efficiency enchantment is applied to it. Can be true or false.

Example:

"minecraft:digger": {
    "use_efficiency": true,
    "destroy_speeds": [
        {
            "block": {
                "tags": "q.any_tag('stone', 'metal')" // Note that not all blocks have tags; you may need to list many blocks.
            },
            "speed": 6
        },
        {
                        "block": "minecraft:grass_block",
                        "speed": 7
                    }
    ]
}

minecraft:display_name

Sets the text displayed when an item's name is displayed.

The available fields are:

• value:
  • It can be any word for fixed text, or a translation key that must be specified in the language file.

Example:

"minecraft:display_name": {
    "value": "secret weapon"
}

Example with translation key:

"minecraft:display_name": {
    "value": "item.snowball.name"
}

minecraft:durability

It sets the item's durability and also allows the item to be repaired with the combination of the same item on the crafting table and on the grindstone and on the anvil. When breaking a block, durability is not spent, requiring the use of the Script API, however, it loses durability when attack any mob, losing 2 durability points. If you use the minercraft:wearable component, it loses 1 durability when attack mobs.

The available fields are:

• damage_chance:
  • An object that has min and max fields that define the probability of the item losing durability working in conjunction with the Unbreakable enchantment must be a value from 0 to 100.
• max_durability
  • Sets the total durability of the item with a minimum value of 0 and a maximum of 32767. Values greater than this are considered negative and do not work.

Example:

"minecraft:durability": {
    "damage_chance": {
        "min": 0,
        "max": 100
    },
    "max_durability": 100
}

minecraft:durability_sensor

Allows an item to emit sound effects and particles when reaching a specific level of durability.

The available fields are:

• durability_thresholds: Base object to place the sub fields.
  • durability: A value at which the effect will be emitted when it is less than or equal to the set value.
  • particle_type: The particle effect to be emitted.
  • sound_event: The sound effect to be emitted.

Example:

"minecraft:durability_sensor": {
    "durability_thresholds": [
        {
            "durability": 100,
            "particle_type": "minecraft:explosion_manual",
            "sound_event": "blast"
        },
        {
            "durability": 5,
            "sound_event": "raid.horn"
        }
    ]
}

minecraft:dyeable

Allows an item to be dyed in a cauldron with water like leather armor, when dyed it uses the dyed field of the minecraft:icon component.

The available fields are:

• default_color:
  • Optional color to use by default before player dyes item, needs to be a color in hexadecimal format.

Example:

"minecraft:dyeable": {
    "default_color": "#ffffff"
}

minecraft:enchantable

Determines whether the item can be enchanted and which enchantments can be applied to the item.

The available fields are:

• slot:
  • Which enchantments can be applied, the only non-existent category is for mace enchantments, for this you must use the all category (ex: Using bow would allow this item to be enchanted as if it were a bow).

• value:
  • The minimum enchantment value is 0 and the maximum is 256, it determines the enchantability of the item, influencing the quality and quantity of potential enchantments. Higher values increase the chance of granting more powerful enchantments. See Enchantability for vanilla values.

Example:

"minecraft:enchantable": {
    "slot": "sword",
    "value": 10
}

minecraft:entity_placer

Allows the item to place specific entitys into the world.

The available fields are:

• dispense_on:
  • List of block descriptors that contain blocks on which the dispenser can use this item. If left blank, all blocks will be allowed.
• entity:
  • The entity the item will place on.
• use_on:
  • List of block descriptors that contain blocks this item can be used on. If left blank, all blocks are allowed.

Example:

    "minecraft:entity_placer": {
        "entity": "minecraft:spider",
        "dispense_on": [
            "minecraft:dirt"
        ],
        "use_on": [
            "minecraft:dirt"
        ]
    }

minecraft:fire_resistant

Warning:This component is currently not synchronized with the player's side, meaning the item will visually disappear from the world upon contact with fire or lava, however the item can still be picked up.

Determines whether items should be able to resist fire and lava instead of being destroyed like any netherite item.

The available fields are:

• value​^{[upcoming BE 1.21.120]}:
  • It can be true or false to define whether or not the item resists fire and lava.

Example ‌^{[until BE 1.21.110]}:

"minecraft:fire_resistant": {}

Example ​^{[upcoming BE 1.21.120]}:

"minecraft:fire_resistant": {
    "value": true
}

minecraft:food

Allows the item to be edible as a food. It requires the minecraft:use_modifiers component to work properly. To display an eating/drinking animation, also apply the minecraft:use_animation component to the item.

The available fields are:

• can_always_eat:
  • If true you can always eat this item (even when you are not hungry).
• nutrition:
  • The value that is added to the player's nutrition when the item is used, which can be a negative value, with a maximum of 107374180 as it is the maximum 32-bit value.
• saturation_modifier:
  • A 32-bit integer value that defines the saturation modification value that uses the calculation (nutrition × saturation_modifier × 2) applying the saturation value.
• using_converts_to:
  • When used, converts to the item specified by the string in this field, as with stew.

Example:

"minecraft:food": {
    "can_always_eat": false,
    "nutrition": 3,
    "saturation_modifier": 0.6,
    "using_converts_to": "bowl"
}

minecraft:fuel

Allows the item to be used as fuel in a smelting block such as a furnace used to smelt other items.

The available fields are:

• duration:
  • How long, in seconds, this fuel will smelt items in a furnace, minimum value being 0.05 and maximum value being 107374180 being the 32-bit limit value.

Example:

"minecraft:fuel": {
    "duration": 3.0
}

minecraft:glint

Determines whether the item has the enchantment glint like an enchanted golden apple.

It has no field, it must be a boolean value being either true or false.

Example:

"minecraft:glint": false

minecraft:hand_equipped

Determines whether an item is rendered as a tool while in hand.

It has no field, it must be a boolean value being either true or false.

Example:

"minecraft:hand_equipped": true

minecraft:hover_text_color

Determines the color of the item name overriding the rarity.

It has no field, it needs to be a string value with the color name, you can see all possible values here.

Example:

"minecraft:hover_text_color": "minecoin_gold"

minecraft:icon

Determines the icon to represent the item in the UI and elsewhere, if replace_block_item is true of the minecraft:block_placer component this component can be omitted and it will use the block as the visual, this can be a string or an object.

The available fields if object are:

• textures: This object contains the different textures that can be used for the item's icon. Armor textures and finish palettes can also be specified here, all specified in the item_texture.json file.
  • default:
    • The default icon for the item.
  • dyed:
    • The icon displayed after a dyeable item is dyed in a cauldron.
  • icon_trim:
    • The icon overlay for when your item has a trim, by default it uses the icon corresponding to the slot defined in the minecraft:wearable component.
  • <material>_palette:
    • The color palette that the armor ornament will use for a certain material type must be a direct path to the texture.
  • bundle_open_back:
    • The texture displayed behind the item preview with the minecraft:bundle_interaction component used in the bundle.
  • bundle_open_front:
    • The texture displayed in front of the item preview with the minecraft:bundle_interaction component used in the bundle.

Example with string:

"minecraft:icon": "wiki:custom_item"

Example with object:

"minecraft:icon": {
    "textures": {
        "default": "wiki:custom_item",
    "icon_trim": "wiki:custom_item_trim",
    "emerald_palette": "textures/trims/color_palettes/redstone_palette",
"bundle_open_back": "bundle_blue_open_back",
          "bundle_open_front": "bundle_blue_open_front"
    }
}

minecraft:interact_button

This component determines whether the interaction button is displayed on touch controls and what text is displayed on the button. When set to true, the default text "Use Item" will be used.

It has no field, it must be a boolean value being either true or false or a string with a text or translation key.

Example with string:

"minecraft:interact_button": "Use this custom item"

Example as boolean:

"minecraft:interact_button": true

minecraft:liquid_clipped

Determines whether an item interacts with liquid blocks when used. When interacting with liquid, outline selection cannot highlight any blocks below it. The interaction occurs within the liquid block, not on its sides.

It has no field, it must be a boolean value being either true or false.

Example:

"minecraft:liquid_clipped": true

minecraft:max_stack_size

Determines how many of the same item can be stacked.

The available fields are:

• There are no fields, it must be a number with a minimum of 1 and a maximum of 64.

Example:

"minecraft:max_stack_size": 64

minecraft:projectile

Projectile item component. Projectile items are fired like an arrow.

The available fields are:

• minimum_critical_power:
  • Sets the time a projectile needs to charge to cause a critical hit.
• projectile_entity:
  • The entity to fire as a projectile. If no namespace is specified, it is assumed to be minecraft.

Example:

"minecraft:projectile": {
    "minimum_critical_power": 1.25,
    "projectile_entity": "arrow"
}

minecraft:rarity

Represents the item's difficulty to obtain by changing the color of its name text. This component has no effect if minecraft:hover_text_color is also applied. The item's rarity will be increased if it is enchanted. See rarity for vanilla values.

It has no field, it must be a string value being common for the white name, uncommon for the yellow name, rare for the aqua blue name and epic for the light purple name.

Example:

"minecraft:rarity": "rare"

minecraft:record

Allows the item to play a sound like a music disc when used in a jukebox, when used the item always turns its name color to aqua blue.

The available fields are:

• comparator_signal:
  • Redstone signal intensity for use in comparator blocks can be any value including negative values, but only values from 0-15 work.
• duration:
  • Duration of the sound event in seconds, can be any value.
• sound_event:
  • Sound event type, if it is a sound from a vanilla music album, the name of the album's author will be added, only vanilla sound events are allowed for use.

Example:

"minecraft:record": {
    "comparator_signal": 1,
    "duration": 5,
    "sound_event": "ambient.tame"
}

minecraft:repairable

Determines which items can be used to repair a specified item, as well as the amount of durability the specified items will repair. By default, any item that has durability can be repaired by itself; setting it to repair in this component will override the vanilla calculation.

The available fields are:

• repair_items: List of item entries to repair.
  • repair_amount:
    • How much durability is repaired, can be an integer value or a Molang expression, being able to use math.random and context.other to get the second slot.
  • items:
    • The item used to repair the item that has the component.

Example:

"minecraft:repairable":{
    "repair_items": [
        {
            "items":[
                "minecraft:diamond"
            ],
            "repair_amount": 10
        },
      {
            "items":[
                "minecraft:stick"
            ],
            "repair_amount": "math.random(1,10)"
        },
       {
            "items":[
                "minecraft:apple"
            ],
            "repair_amount": "math.min(q.remaining_durability + c.other->q.remaining_durability + math.floor(q.max_durability /20), c.other->q.max_durability)"
        }
    ]
}

minecraft:shooter

Used to shoot projectiles like a bow. Must have the minecraft:use_modifiers component to work properly.

The available fields are:

• ammunition: Input list used to set ammunition and priority.
  • item:
    • Indicates the item identifier. The item must have the component minecraft:projectile.
  • use_offhand:
    • Can be true or false, allows the ammunition to be used in the offhand.
  • search_inventory:
    • Can be true or false, determines whether it is possible to search for ammunition in the inventory, mandatory to be true in survival and in creative if use_in_creative is true.
  • use_in_creative:
    • Can be true or false, allows the ammo to be used in creative.
• charge_on_draw:
  • Can be true or false, defines whether the item is carried when drawn, if the item uses minecraft:use_modifiers it must have use_duration greater than or equal to max_draw_duration.
• max_draw_duration:
  • Determines how long the weapon can be drawn before it is automatically released.
• scale_power_by_draw_duration:
  • It can be true or false, when true the longer the weapon is drawn, the more power it will have when released.

Example:

"minecraft:shooter": {
    "ammunition": [
        {
            "item": "custom_projectile",
            "use_offhand": true,
            "search_inventory": true,
            "use_in_creative": true
        }
    ],
    "max_draw_duration": 1.0,
    "scale_power_by_draw_duration": true,
    "charge_on_draw": false
}

minecraft:should_despawn

Determines whether an item should eventually despawn while floating in the world.

It has no field, it must be a boolean value being either true or false.

Example:

"minecraft:should_despawn": true

minecraft:stacked_by_data

Determines whether the same item with different auxiliary values can be stacked. Additionally, it determines whether the item's actors can be merged while floating in the world.

It has no field, it must be a boolean value being either true or false.

Example:

"minecraft:stacked_by_data": true

minecraft:storage_item

Allows the item to act as a container and store other items as a bundle. The item must not stack for this component to work.

The available fields are:

• allow_nested_storage_items:
  • Determines whether other storage items can be placed in the container can be true or false.
• allowed_items:
  • Defines the items that are allowed exclusively in the container. If empty or omitted, all items are allowed in the container.
• banned_items:
  • Defines items that are not allowed exclusively in the container.
• max_slots:
  • Sets the number of slots in the container to a minimum of 1 and a maximum of 64.
• max_weight_limit:
  • An integer.

Example:

"minecraft:storage_item": {
    "max_slots": 64,
    "allow_nested_storage_items": true,
    "banned_items": [
        "minecraft:shulker_box",
        "minecraft:undyed_shulker_box"
    ]
}

minecraft:storage_weight_limit

Sets the maximum allowed total weight of all items in the storage item container. The item must have the minecraft:storage_item component for this component to work.

• To calculate the weight of an item, divide 64 by the maximum number of stacked items. If there are 64, each item weighs 1. If there are 16, each item weighs 4. If there are 1, each item weighs 64.

The available fields are:

• max_weight_limit:
  • An integer.

Example:

"minecraft:storage_weight_limit": {
    "max_weight_limit": 64
}

minecraft:storage_weight_modifier

Sets the additional weight the item adds when it is inside another storage item.

The available fields are:

• weight_in_storage_item:
  • An integer between 0 and 64 a value of 0 does not allow the item to be used in a storage item.

Example:

"minecraft:storage_weight_modifier": {
    "weight_in_storage_item": 4
}

minecraft:tags

Sets the tag for an item, which can be vanilla or custom, for the list of vanilla tags see tag.

The available fields are:

• tags:
  • List of tags that the item has.

Example:

"minecraft:tags": {
    "tags": [
        "custom_tag"
    ]
}

minecraft:throwable

Defines throwable items, such as a snowball. The item must have the minecraft:projectile component otherwise it will not work.

The available fields are:

• do_swing_animation:
  • Whether the item should use the arm swing animation when thrown can be either true or false.
• launch_power_scale:
  • The scale at which the throwing power increases, which can be negative, ending up throwing the item in the opposite direction.
• max_draw_duration:
  • The maximum time to throw the throwable item, it can be negative if it is negative it throws instantly.
• max_launch_power:
  • The maximum power to throw the throwable item, which can be negative.
• min_draw_duration:
  • The minimum time to throw the throwable item, can be negative if it is negative it throws instantly.
• scale_power_by_draw_duration:
  • Whether or not the power of the throw increases with the duration of the charge. It can be true or false, if it is true it will take the time into consideration, that is, the longer you hold it, the more power it will have when thrown.

Example:

"minecraft:throwable": {
    "do_swing_animation": false,
    "launch_power_scale": 1.0,
    "max_draw_duration": 0.0,
    "max_launch_power": 1.0,
    "min_draw_duration": 0.0,
    "scale_power_by_draw_duration": false
}

minecraft:use_animation

Defines which animation will happen when using the item.

The available fields are:

• There are no fields, it must be a string value and can be eat, drink, bow, block, camera, crossbow, none, brush, spear and spyglass.

Example:

"minecraft:use_animation": "eat"

minecraft:use_modifiers

Modifies usage effects, including the time it takes for an item to be used and the player's speed when used in combination with components such as Shooter, Throwable, or Food.

The available fields are:

• movement_modifier:
  • Modifier value to scale players' movement speed when the item is in use, sensing a value between 0 and 1.
• use_duration:
  • How long in seconds it takes to use the item.

Example:

"minecraft:use_modifiers": {
    "movement_modifier": 0.5,
    "use_duration": 1.0
}

minecraft:wearable

Determines where the item can be used. If any slot other than the hand slot is selected, the maximum item stack value is set to 1.

The available fields are:

• slot:
  • Defines the slot in which the item can be used, which can be slot.weapon.offhand, slot.armor.head, slot.armor.chest, slot.armor.legs and slot.armor.feet i.e. offhand, head, chestplate, leggings and feet.
• protection:
  • How much protection the item will provide the player when used.
• hides_player_location:
  • Determines whether or not to hide the player's location on locator maps and in the locator bar when used. Can be either true or false.

Example:

"minecraft:wearable": {
    "slot": "slot.armor.chest",
    "protection": 10,
    "hides_player_location": false
}

NBT Components

Item NBT components are a little different from regular components, they are stored internally by the game and can only be modified by commands like /give or /replaceitem much like Java Edition data components.

The available NBT components are minecraft:can_place_on, minecraft:can_destroy, minecraft:item_lock and minecraft:keep_on_death.

minecraft:can_place_on

Controls what types of blocks this block can be placed on. This allows blocks to be placed in adventure mode without the use of allow blocks.

Example: /give @s cobblestone 64 0 {"minecraft:can_place_on":{"blocks":["stained_glass:2"]}}

minecraft:can_destroy

Controls what types of blocks this item can destroy.

Example: /give @a wooden_axe 16 0 {"minecraft:can_destroy":{"blocks":["wool:5"]}}

minecraft:item_lock

Locks the item in the player's inventory depending on the chosen mode. Having the mode parameter that specifies the lock type. Which can be lock_in_inventory or lock_in_slot.^[1]

lock_in_inventory

Prevents the item from being dropped, removed from inventory, used as a crafting ingredient, placed in a bundle, or renamed on an anvil it displays a yellow triangle in the top corner of the item.

Example: /give @p diamond_axe 1 0 {"minecraft:item_lock":{"mode":"lock_in_inventory"}}

lock_in_slot

Prevents the item from being moved or removed from its slot in the player's inventory, dropped, placed stacked, and used as a crafting ingredient. It displays a red triangle in the top corner of the item.

Example: /give @p wooden_pickaxe 1 0 {"minecraft:item_lock":{"mode":"lock_in_slot"}}

keep_on_death

Prevents the item from being dropped when the entity dies.

Example: /give @s cooked_beef 1 0 {"minecraft:keep_on_death":{}}

History

This section of the article is empty.

 

You can help by expanding it.

References

External links

More information about components

• Bedrock Wiki

Navigation