Item Components

FORMAT & MIN ENGINE VERSION 1.20.50

Using the latest format version when creating custom items provides access to fresh features and improvements. The wiki aims to share up-to-date information about custom items, and currently targets format version 1.20.50.

Applying Components

Item components are used to change how your item appears and functions in the world. They are applied in the components child of minecraft:item.

BP/items/custom_item.jsonCopy
json
{
    "format_version": "1.20.50",
    "minecraft:item": {
        "description": {
            "identifier": "wiki:custom_item",
            "menu_category": {
                "category": "items"
            }
        },
        "components": {
            "minecraft:icon": {
                "texture": "custom_item"
            }
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Allow Off Hand

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

minecraft:item > componentsCopy
json
"minecraft:allow_off_hand": {
    "value": true
}
1
2
3

Block Placer

Sets the item as a Planter item component for blocks. Items with this component will place a block when used.

minecraft:item > componentsCopy
json
"minecraft:block_placer":{ 
    "block": "seeds",
    "use_on": [
        "dirt",
        "grass"
    ]
}
1
2
3
4
5
6
7

Can Destroy In Creative

Determines if an item will break blocks in Creative Mode while swinging.

minecraft:item > componentsCopy
json
"minecraft:can_destroy_in_creative": {
    "value": true
}
1
2
3

Cooldown

Sets an items "Cool down" time. After using an item, it becomes unusable for the duration specified by the 'duration' setting of this component.

minecraft:item > componentsCopy
json
"minecraft:cooldown":{
    "category" : "attack",
    "duration" : 0.2
}
1
2
3
4

Damage

Determines how much extra damage an item does on attack.

minecraft:item > componentsCopy
json
"minecraft:damage": {
    "value": 10
}
1
2
3

Digger

Allows a creator to determine how quickly an item can dig specific blocks.

minecraft:item > componentsCopy
json
"minecraft:digger": {
	"use_efficiency": true,
	"destroy_speeds": [
		{
			"block": {
				"tags": "q.any_tag('stone', 'metal')" // Note that not all blocks have tags; listing many blocks may be necessary
			},
			"speed": 6
		}
	]
}
1
2
3
4
5
6
7
8
9
10
11

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.

Example

minecraft:item > componentsCopy
json
"minecraft:display_name":{
    "value": "secret_weapon"
}
1
2
3

Example Using Localization Key

minecraft:item > componentsCopy
json
"minecraft:display_name":{
    "value": "item.snowball.name"
}
1
2
3

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.

minecraft:item > componentsCopy
json
"minecraft:durability":{
    "damage_chance": {
        "min": 10,
        "max": 50
    },
    "max_durability": 36
}
1
2
3
4
5
6
7

Enchantable

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

minecraft:item > componentsCopy
json
"minecraft:enchantable": {
	"slot": "bow",
	"value": 10
}
1
2
3
4

Enchantable Slots

Note: The "all" enchantable slot allows you to apply any enchantment that you want to the item, just like an enchanted book.

Slot Name
armor_feet
armor_torso
armor_head
armor_legs
axe
bow
cosmetic_head
crossbow
elytra
fishing_rod
flintsteel
hoe
pickaxe
shears
shield
shovel
sword
all

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.

minecraft:item > componentsCopy
json
"minecraft:entity_placer":{
    "entity": "minecraft:spider",
    "dispense_on": ["minecraft:web"],
    "use_on": ["minecraft:web"]
}
1
2
3
4
5

Food

Sets the item as a food component, allowing it to be edible to the player.

TIP

The minecraft:food must have the minecraft:use_modifiers component in order to function properly.

minecraft:item > componentsCopy
json
"minecraft:food":{
    "can_always_eat": false,
    "nutrition" : 3,
    "effects" : [
        {
            "name": "poison",
            "chance": 1.0,
            "duration": 5,
            "amplifier": 0
        }
    ],
    "saturation_modifier": "normal",
    "using_converts_to": "bowl"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

Fuel

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

minecraft:item > componentsCopy
json
"minecraft:fuel":{
    "duration": 3.0
}
1
2
3

Glint

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

minecraft:item > componentsCopy
json
"minecraft:glint": false
1

Hand Equipped

Determines if an item is rendered like a tool while in-hand.

minecraft:item > componentsCopy
json
"minecraft:hand_equipped": {
    "value": true
}
1
2
3

Hover Text Color

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

minecraft:item > componentsCopy
json
"minecraft:hover_text_color": "green"
1

Icon

Sets the icon item component. Determines the icon to represent the item in the UI and elsewhere.

minecraft:item > componentsCopy
json
"minecraft:icon":{
    "texture": "oak_slab"
}
1
2
3

Interact Button

Is 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.

minecraft:item > componentsCopy
json
"minecraft:interact_button": "Use This Custom Item" // Can be a string or a boolean value. 
1

Liquid Clipped

Determines whether an item interacts with liquid blocks on use.

minecraft:item > componentsCopy
json
"minecraft:liquid_clipped": {
    "value": true
}
1
2
3

Max Stack Size

Determines how many of an item can be stacked together.

minecraft:item > componentsCopy
json
"minecraft:max_stack_size": {
    "value": 64
}
1
2
3

Projectile

Compels the item to shoot, similarly to an arrow. Items with minecraft:projectile can be shot from dispensers or used as ammunition for items with the minecraft:shooter item component. Additionally, this component sets the entity that is spawned for items that also contain the minecraft:throwable component.

minecraft:item > componentsCopy
json
"minecraft:projectile":{
    "minimum_critical_power": 1.25,
    "projectile_entity": "arrow"
}
1
2
3
4

Record

Used by record items to play music.

minecraft:item > componentsCopy
json
"minecraft:record": {
    "comparator_signal": 1,
    "duration": 5,
    "sound_event": "ambient.tame"
}
1
2
3
4
5

Sound Event

Listed here are the available sounds

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.

minecraft:item > componentsCopy
json
"minecraft:repairable":{
    "on_repaired": "minecraft:celebrate",
    "repair_items": ["anvil"]
}
1
2
3
4

Shooter

Compels an item to shoot projectiles, similarly to a bow or crossbow. Must have the minecraft:use_modifiers component in order to function properly.

TIP

Ammunition used by minecraft:shooter must have the minecraft:projectile component in order to function properly.

minecraft:item > componentsCopy
json
"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
}
1
2
3
4
5
6
7
8
9
10
11
12
13

Should Despawn

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

minecraft:item > componentsCopy
json
"minecraft:should_despawn": {
    "value": true
}
1
2
3

Stacked By Data

Determines if the same item with different aux values can stack. Additionally, this component defines whether the item actors can merge while floating in the world.

minecraft:item > componentsCopy
json
"minecraft:stacked_by_data": {
    "value": true
}
1
2
3

Tags

Determines which tags are included on a given item.

minecraft:item > componentsCopy
json
"minecraft:tags": {
    "tags": [
        "custom_tag"
    ]
}
1
2
3
4
5

Throwable

Sets the throwable item component.

minecraft:item > componentsCopy
json
"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
}
1
2
3
4
5
6
7
8

Use Animation

Determines which animation plays when using an item.

minecraft:item > componentsCopy
json
"minecraft:use_animation": "eat"
1

Use Modifiers

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

minecraft:item > componentsCopy
json
"minecraft:use_modifiers": {
    "use_duration": 1.6,
    "movement_modifier": 0.35
}
1
2
3
4

Wearable

Sets the wearable item component.

minecraft:item > componentsCopy
json
"minecraft:wearable":{
    "dispensable" : true,
    "slot": "slot.chest"
}
1
2
3
4

Slots

Slot Name
slot.weapon.mainhand
slot.weapon.offhand
slot.armor.head
slot.armor.chest
slot.armor.legs
slot.armor.feet
slot.hotbar
slot.inventory
slot.enderchest
slot.saddle
slot.armor
slot.chest
slot.equippable

Contributors