Item Components

Starting from Minecraft 1.20.5, items use a new component system. zMenu provides full support for this system through the components configuration section.

info

Components require Minecraft 1.20.5 or higher. Some components are only available in newer versions, indicated by a badge next to each component name.

Basic Structure

item:
  material: DIAMOND_SWORD
  components:
    custom-name: "&6&lLegendary Sword"
    lore:
      - "&7A powerful weapon"
    enchantments:
      sharpness: 5

attack-range 1.21.11+

Defines the attack range of an item in blocks.

Minecraft Wiki: attack_range

Key	Type	Default	Range	Description
`min-reach`	Float	`0`	0-64	Minimum reach distance in survival mode
`max-reach`	Float	`3`	0-64	Maximum reach distance in survival mode
`min-creative-reach`	Float	`0`	0-64	Minimum reach distance in creative mode
`max-creative-reach`	Float	`5`	0-64	Maximum reach distance in creative mode
`hitbox-margin`	Float	`0.3`	0-1	Additional margin for hitbox detection
`mob-factor`	Float	`1`	0-2	Multiplier applied to mob hitboxes

components:
  attack-range:
    min-reach: 0
    max-reach: 5
    min-creative-reach: 0
    max-creative-reach: 6
    hitbox-margin: 0.3
    mob-factor: 1.0

attribute-modifiers

Adds attribute modifiers to the item.

Minecraft Wiki: attribute_modifiers

Key	Type	Required	Description
`type`	String	Yes	Attribute type (e.g., `generic.attack_damage`)
`amount`	Double	Yes	Value of the modifier
`operation`	String	Yes	Operation type: `ADD_NUMBER`, `ADD_SCALAR`, `MULTIPLY_SCALAR_1`
`slot`	String	No	Equipment slot: `any`, `mainhand`, `offhand`, `head`, `chest`, `legs`, `feet`
`key`	String	No	Unique identifier for the modifier

components:
  attribute-modifiers:
    - type: generic.attack_damage
      amount: 10
      operation: add_value
      slot: mainhand
      key: "my_plugin:attack_bonus"
    - type: generic.movement_speed
      amount: 0.1
      operation: add_multiplied_base
      slot: feet

Available Attributes: can be found here, support custom attributes if registered in the registry.

Defines patterns on a banner item.

Minecraft Wiki: banner_patterns

components:
  banner-patterns:
    - pattern: stripe_top
      color: red
    - pattern: cross
      color: blue

base-color

Sets the base color for shields and banners.

Minecraft Wiki: base_color

components:
  base-color: RED

Available Colors: can be found here.

block-state

Sets block state properties for block items when placed.

Minecraft Wiki: block_state

components:
  block-state:
    facing: north
    powered: true
    waterlogged: false

blocks-attacks 1.21.5+

Configures shield-like blocking behavior for items.

Minecraft Wiki: blocks_attacks

Key	Type	Default	Description
`block-delay-seconds`	Float	`0`	Delay before blocking becomes active
`disable-cooldown-scale`	Float	`1`	Cooldown scale when shield is disabled
`block-sound`	String	-	Sound played when blocking
`disabled-sound`	String	-	Sound played when shield is disabled
`item-damage.threshold`	Float	`0`	Damage threshold before item takes damage
`item-damage.base`	Float	`0`	Base item damage
`item-damage.factor`	Float	`1.5`	Damage multiplier factor
`damage-reductions`	List	`[]`	List of damage reduction rules

Damage Reduction Properties:

Key	Type	Description
`type`	String/List	Damage type(s) to reduce
`base`	Float	Base damage reduction
`factor`	Float	Damage reduction factor
`horizontal-blocking-angle`	Float	Blocking angle in degrees (default: 90)

components:
  blocks-attacks:
    block-delay-seconds: 0.25
    disable-cooldown-scale: 1.0
    block-sound: item.shield.block
    disabled-sound: item.shield.break
    item-damage:
      threshold: 3.0
      base: 0
      factor: 1.5
    damage-reductions:
      - type: player_attack
        base: 5.0
        factor: 0.5
        horizontal-blocking-angle: 90

break-sound 1.21.5+

Sets the sound played when the item breaks.

Minecraft Wiki: break_sound

components:
  break-sound: "entity.item.break"

bundle-contents

Stores items inside a bundle. Use zMenu item syntax inside each entry.

Minecraft Wiki: bundle_contents

components:
  bundle-contents:
    - material: DIAMOND
      amount: 10
    - material: EMERALD
      amount: 5
    - material: GOLD_INGOT
      amount: 20

charged-projectiles

Stores projectiles in crossbows.

Minecraft Wiki: charged_projectiles

components:
  charged-projectiles:
    - material: ARROW
      amount: 1
    - material: SPECTRAL_ARROW
      amount: 1

consumable 1.21.2+

Configures how an item is consumed.

Minecraft Wiki: consumable

Key	Type	Default	Description
`consume-seconds`	Float	`1.6`	Time to consume the item in seconds
`animation`	String	`EAT`	Animation type
`consume-sound`	String	`entity.generic.eat`	Sound played when consuming
`has-consume-particles`	Boolean	`true`	Whether to show particles when consuming
`on-consume-effects`	List	`[]`	Effects to apply when consumed

components:
  consumable:
    consume-seconds: 1.6
    animation: EAT
    consume-sound: entity.generic.eat
    has-consume-particles: true
    on-consume-effects:
      - type: APPLY_EFFECTS
        probability: 1.0
        effects:
          - type: speed
            amplifier: 1
            duration: 600
      - type: PLAY_SOUND
        sound: entity.player.burp
      - type: TELEPORT_RANDOMLY
        diameter: 16.0
      - type: CLEAR_ALL_EFFECTS
      - type: REMOVE_EFFECTS
        effects:
          - poison
          - wither

Animation Types: EAT, DRINK, BLOCK, BOW, SPEAR, CROSSBOW, SPYGLASS, TOOT_HORN, BRUSH, BUNDLE

Effect Types:

APPLY_EFFECTS - Apply potion effects with probability
PLAY_SOUND - Play a sound
TELEPORT_RANDOMLY - Teleport randomly within diameter
CLEAR_ALL_EFFECTS - Clear all potion effects
REMOVE_EFFECTS - Remove specific effects

container

Stores items inside the item (like shulker boxes).

Minecraft Wiki: container

Key	Type	Description
`slot`	Integer	Slot index (0-26 for shulker boxes)

Use zMenu item syntax inside each entry.

components:
  container:
    - slot: 0
      material: DIAMOND
      amount: 64
    - slot: 1
      material: EMERALD
      amount: 32

container-loot

Sets the loot table for container items.

Minecraft Wiki: container_loot

Key	Type	Default	Description
`loot-table`	String	-	Loot table name (e.g., `DESERT_PYRAMID`)
`seed`	Long	`0`	Random seed for loot generation

components:
  container-loot:
    loot-table: DESERT_PYRAMID
    seed: 12345

Available Loot Tables: can be found here.

custom-data

Stores custom persistent data (NBT) on the item.

Minecraft Wiki: custom_data

Supports multiple data types with automatic type detection:

String
Boolean
Integer
Long
Double
Float
Byte
Short
byte[], int[], long[] arrays

components:
  custom-data:
    "my_plugin:item_id": "legendary_sword"
    "my_plugin:level": 10
    "my_plugin:enchanted": true
    "my_plugin:damage_bonus": 5.5

custom-model-data

Custom model data for resource pack integration.

Minecraft Wiki: custom_model_data

Key	Type	Description
`floats`	List<Float>	Float values for predicates
`flags`	List<Boolean>	Boolean flags for predicates
`strings`	List<String>	String values for predicates
`colors`	List<Color>	Color values. Each entry can be a hex string (e.g., `"#FFAA00"` or `"#80FFAA00"`), an integer (RGB or ARGB), a list of floats (RGB[A], 0.0–1.0), or a list of ints (RGB[A], 0–255).

components:
  custom-model-data:
    floats:
      - 1.0
      - 2.5
    flags:
      - true
      - false
    strings:
      - "variant_a"
    colors:
      - "#FFAA00"         # Hex string (RRGGBB)
      - "#80FFAA00"       # Hex string (AARRGGBB)
      - 16755200          # Integer RGB (decimal)
      - [1.0, 0.5, 0.0]   # List of floats (RGB, 0.0–1.0)
      - [1.0, 0.5, 0.0, 0.5] # List of floats (RGBA, 0.0–1.0)
      - [255, 128, 0]     # List of ints (RGB, 0–255)
      - [128, 255, 128, 0]# List of ints (RGBA, 0–255)

damage

Sets the current damage value of the item.

Minecraft Wiki: damage

components:
  damage: 100

damage-resistant

Makes the item resistant to specific damage types.

Minecraft Wiki: damage_resistant

Key	Type	Description
`types`	String	Damage type tag to resist

components:
  damage-resistant:
    types: "minecraft:is_fire"

Available Damage Type Tags: can be found here.

damage-type 1.21.11+

Sets the damage type dealt by the item when used as a weapon.

Minecraft Wiki: damage_type

components:
  damage-type: 
    types: "minecraft:player_attack"

Common Damage Types: player_attack, mob_attack, arrow, fireball, magic, wither, dragon_breath, freeze, sonic_boom

dyed-color

Sets the dye color for leather armor and other dyeable items.

Minecraft Wiki: dyed_color

Type	Description
String	Hex string (e.g., `"#FFAA00"` or `"#80FFAA00"`)
Integer	Integer RGB or ARGB (decimal)
List<Float>	List of floats (RGB[A], 0.0–1.0)
List<Integer>	List of ints (RGB[A], 0–255)

components:
  # Only use one of the following formats for dyed-color:
  dyed-color: "#FFAA00"         # Hex string (RRGGBB)
  # dyed-color: "#80FFAA00"       # Hex string (AARRGGBB)
  # dyed-color: 16755200          # Integer RGB (decimal)
  # dyed-color: [1.0, 0.5, 0.0]   # List of floats (RGB, 0.0–1.0)
  # dyed-color: [1.0, 0.5, 0.0, 0.5] # List of floats (RGBA, 0.0–1.0)
  # dyed-color: [255, 128, 0]     # List of ints (RGB, 0–255)
  # dyed-color: [128, 255, 128, 0]# List of ints (RGBA, 0–255)

enchantable 1.21.2+

Sets the enchantability value for the item.

Minecraft Wiki: enchantable

components:
  enchantable: 
    value: 15

enchantment-glint-override

Force or remove the enchantment glint effect.

Minecraft Wiki: enchantment_glint_override

components:
  enchantment-glint-override: true   # Force glint

components:
  enchantment-glint-override: false  # Remove glint

enchantments

Adds enchantments to the item. Supports custom enchantments if they were registered inside the registry.

Minecraft Wiki: enchantments

components:
  enchantments:
    sharpness: 5
    unbreaking: 3
    fire_aspect: 2
    mending: 1

custom_name Paper only

Sets the custom name of the item.

Minecraft Wiki: custom_name

components:
  custom-name: "&6&lLegendary Sword"

intangible_projectile Paper only

Makes projectiles fired from this item intangible (pass through blocks).

Minecraft Wiki: intangible_projectile

components:
  intangible_projectile: true

map_decorations Paper only

Adds map decorations to filled maps.

Minecraft Wiki: map_decorations

Key	Type	Description
`type`	String	Decoration type (e.g., `red_marker`) full list
`x`	Integer	X coordinate on the map
`z`	Integer	Z coordinate on the map
`rotation`	Integer	Rotation

components:
  map_decorations:
    - type: red_marker
      x: 100
      z: -50
      rotation: 0
    - type: blue_marker
      x: -30
      z: 75
      rotation: 4

note_block_sound Paper only

Sets the sound played when a note block item is placed.

Minecraft Wiki: note_block_sound

components:
  note_block_sound: "minecraft:block.note_block.bell"

pot_decorations Paper only

Adds decorations to decorated pots. Requires the item to be a pottery shard or brick. Each decoration is represented by a string ID corresponding to a specific pattern or design.

Minecraft Wiki: pot_decorations

components:
  pot_decorations:
    - "skull_pottery_sherd"
    - "heart_pottery_sherd"
    - "blade_pottery_sherd"
    - "brick"

equippable 1.21.2+

Configures equipment properties for any item.

Minecraft Wiki: equippable

Key	Type	Default	Description
`slot`	String	-	Equipment slot: `HEAD`, `CHEST`, `LEGS`, `FEET`, `MAINHAND`, `OFFHAND`, `BODY`
`equip-sound`	String	-	Sound when equipping
`asset-id`	String	-	Resource location for the equipment model
`dispensable`	Boolean	`true`	Can be equipped by dispensers
`swappable`	Boolean	`true`	Can be swapped with other equipment
`damage-on-hurt`	Boolean	`true`	Takes damage when the entity is hurt
`equip-on-interact`	Boolean	`false`	Equip on right-click interaction
`camera-overlay`	String	-	Resource location for camera overlay
`can-be-sheared`	Boolean	`false`	Can be sheared off the entity
`shearing-sound`	String	-	Sound when shearing
`allowed-entities`	List	-	Entities that can wear this item

components:
  equippable:
    slot: HEAD
    equip-sound: item.armor.equip_leather
    asset-id: "minecraft:leather"
    dispensable: true
    swappable: true
    damage-on-hurt: true
    equip-on-interact: false
    can-be-sheared: false
    allowed-entities:
      - minecraft:player
      - minecraft:armor_stand

firework-explosion

Configures a single firework star explosion effect.

Minecraft Wiki: firework_explosion

Key	Type	Description
`shape`	String	Shape: `BALL`, `LARGE_BALL`, `BURST`, `CREEPER`, `STAR`
`colors`	Color/List	Primary color(s). Each entry can be a hex string (e.g., `"#FFAA00"` or `"#80FFAA00"`), an integer (RGB or ARGB), a list of floats (RGB[A], 0.0–1.0), or a list of ints (RGB[A], 0–255).
`fade_colors`	Color/List	Fade color(s). Same formats as `colors`.
`has_trail`	Boolean	Has trail effect
`has_twinkle`	Boolean	Has twinkle/flicker effect

Accepted Color Formats for colors and fade_colors:

Type	Description
String	Hex string (e.g., `"#FFAA00"` or `"#80FFAA00"`)
Integer	Integer RGB or ARGB (decimal)
List<Float>	List of floats (RGB[A], 0.0–1.0)
List<Integer>	List of ints (RGB[A], 0–255)

components:
  firework-explosion:
    shape: STAR
    # Only use one of the following formats for colors:
    colors: "#FFAA00"         # Hex string (RRGGBB)
    # colors: "#80FFAA00"       # Hex string (AARRGGBB)
    # colors: 16755200          # Integer RGB (decimal)
    # colors: [1.0, 0.5, 0.0]   # List of floats (RGB, 0.0–1.0)
    # colors: [1.0, 0.5, 0.0, 0.5] # List of floats (RGBA, 0.0–1.0)
    # colors: [255, 128, 0]     # List of ints (RGB, 0–255)
    # colors: [128, 255, 128, 0]# List of ints (RGBA, 0–255)
    # Only use one of the following formats for fade_colors:
    fade_colors: "#FFFF00"         # Hex string (RRGGBB)
    # fade_colors: "#80FFFF00"       # Hex string (AARRGGBB)
    # fade_colors: 16776960          # Integer RGB (decimal)
    # fade_colors: [1.0, 1.0, 0.0]   # List of floats (RGB, 0.0–1.0)
    # fade_colors: [1.0, 1.0, 0.0, 0.5] # List of floats (RGBA, 0.0–1.0)
    # fade_colors: [255, 255, 0]     # List of ints (RGB, 0–255)
    # fade_colors: [128, 255, 255, 0]# List of ints (RGBA, 0–255)
    has_trail: true
    has_twinkle: true

fireworks

Configures firework rockets.

Minecraft Wiki: fireworks

Key	Type	Default	Description
`flight-duration`	Integer	`1`	Flight duration (1-3)
`explosions`	List	`[]`	List of explosion effects

Each entry in explosions follows the same properties as firework-explosion.

components:
  fireworks:
    flight-duration: 2
    explosions:
      - shape: LARGE_BALL
        colors:
          - "#FF0000"
          - "#00FF00"
        fade-colors:
          - "#FFFF00"
        has-trail: true
        has-twinkle: true

food

Makes any item edible.

Minecraft Wiki: food

Key	Type	Default	Required	Description
`nutrition`	Integer	-	Yes	Food points restored (hunger bars)
`saturation`	Float	-	Yes	Saturation modifier
`can-always-eat`	Boolean	`false`	No	Can eat even when not hungry

components:
  food:
    nutrition: 6
    saturation: 0.8
    can-always-eat: true

glider 1.21.2+

Makes the item function as an elytra when equipped in the chest slot.

Minecraft Wiki: glider

components:
  glider: true

instrument

Configures goat horn instrument properties.

Minecraft Wiki: instrument

Simple (by instrument name):

components:
  instrument: "minecraft:ponder_goat_horn"

Advanced configuration:

Key	Type	Description
`sound-event`	String	Sound to play
`use-duration`	Float	Duration of use in seconds
`range`	Float	Hearing range in blocks
`description`	String	Instrument description

components:
  instrument:
    sound-event: "minecraft:ponder_goat_horn"
    use-duration: 7.0
    range: 256.0
    description: "A mysterious goat horn"

Available Instruments: ponder_goat_horn, sing_goat_horn, seek_goat_horn, feel_goat_horn, admire_goat_horn, call_goat_horn, yearn_goat_horn, dream_goat_horn

item-model 1.21.2+

Sets the item model directly.

Minecraft Wiki: item_model

components:
  item-model: "minecraft:custom/my_model"

item-name

Sets the item's base name (cannot be changed in anvil, shown in italic).

Minecraft Wiki: item_name

components:
  item-name: "&6Special Item"

jukebox-playable 1.21+

Makes the item playable in a jukebox.

Minecraft Wiki: jukebox_playable

components:
  jukebox-playable: "minecraft:music_disc.cat"

kinetic-weapon 1.21.11+

Configures lance-like weapon behavior for mounted combat.

Minecraft Wiki: kinetic_weapon

Key	Type	Default	Description
`delay-ticks`	Integer	`0`	Delay before attack in ticks
`forward-movement`	Float	`0`	Forward movement on hit
`damage-multiplier`	Float	`1`	Damage multiplier
`sound`	String	-	Sound when charging
`hit-sound`	String	-	Sound when hitting
`damage-conditions`	Object	-	Conditions for dealing damage
`dismount-conditions`	Object	-	Conditions for dismounting target
`knockback-conditions`	Object	-	Conditions for knockback

Condition Properties:

Key	Type	Description
`max-duration-ticks`	Integer	Maximum duration for condition
`min-speed`	Float	Minimum player speed
`min-relative-speed`	Float	Minimum speed relative to target

components:
  kinetic-weapon:
    delay-ticks: 0
    forward-movement: 0.5
    damage-multiplier: 2.0
    sound: "entity.player.attack.sweep"
    hit-sound: "entity.player.attack.strong"
    damage-conditions:
      max-duration-ticks: 100
      min-speed: 0.5
      min-relative-speed: 0.3
    dismount-conditions:
      max-duration-ticks: 50
      min-speed: 0.8
      min-relative-speed: 0.5

lodestone-tracker

Configures compass lodestone tracking.

Minecraft Wiki: lodestone_tracker

Key	Type	Default	Description
`tracked`	Boolean	`true`	Whether the lodestone is tracked
`target.post`	List<Integer>	-	Target coordinates [x, y, z]
`target.dimension`	String	-	World name

components:
  lodestone-tracker:
    tracked: true
    target:
      post: [100, 64, -200]
      dimension: world

lore

Sets the item's description lines.

Minecraft Wiki: lore

components:
  lore:
    - "&7Line 1"
    - "&7Line 2"
    - ""
    - "&eClick to use!"

Or as a single line:

components:
  lore: "&7A simple description"

map-color

Sets the map marker color for filled maps.

Minecraft Wiki: map_color

[!NOTE] The map-color field uses the same color parsing method as firework-explosion colors and fade_colors. All supported formats (hex string, integer, float/int arrays/lists) are accepted.

components:
  map-color: "#FF5555"
  # map-color: 16737717
  # map-color: [1.0, 0.33, 0.33]
  # map-color: [255, 85, 85]

map-id

Sets the map ID for filled maps.

Minecraft Wiki: map_id

components:
  map-id: 1234

max-damage

Sets the maximum durability of the item.

Minecraft Wiki: max_damage

components:
  max-damage: 2000

max-stack-size

Override the maximum stack size (1-99).

Minecraft Wiki: max_stack_size

components:
  max-stack-size: 16

minimum-attack-charge 1.21.11+

Sets the minimum attack charge required to deal damage.

Minecraft Wiki: minimum_attack_charge

components:
  minimum-attack-charge: 0.5

ominous-bottle-amplifier

Sets the Bad Omen amplifier for ominous bottles.

Minecraft Wiki: ominous_bottle_amplifier

components:
  ominous-bottle-amplifier: 4

piercing-weapon 1.21.11+

Configures trident-like weapon behavior.

Minecraft Wiki: piercing_weapon

Key	Type	Default	Description
`deals-knockback`	Boolean	`true`	Whether hits deal knockback
`dismounts`	Boolean	`false`	Whether hits dismount riders
`sound`	String	-	Sound when thrown
`hit-sound`	String	-	Sound when hitting

components:
  piercing-weapon:
    deals-knockback: true
    dismounts: true
    sound: "item.trident.throw"
    hit-sound: "item.trident.hit"

potion-contents

Configures potion effects and appearance.

Minecraft Wiki: potion_contents

Key	Type	Description
`potion`	String	Base potion type (e.g., `speed`, `healing`)
`custom-color`	String/Number/List	Custom potion color. Uses the same color parsing method as `firework-explosion` `colors` and `fade_colors`.
`custom-name`	String	Custom potion name
`custom-effects`	List	List of custom potion effects

[!NOTE] The custom-color field accepts all formats supported by firework-explosion colors: hex string, integer, list of floats, or list of ints. Refer to that section for a full table and YAML examples.

Custom Effect Properties:

Key	Type	Description
`type`	String	Effect type (e.g., `speed`, `jump_boost`)
`amplifier`	Integer	Effect level (0 = level 1)
`duration`	Integer	Duration in ticks (20 ticks = 1 second)
`ambient`	Boolean	Ambient particles (like beacon)
`show-particles`	Boolean	Show effect particles
`show-icon`	Boolean	Show effect icon

components:
  potion-contents:
    potion: speed
    # Only use one of the following formats for custom-color:
    custom-color: "#FF0000"         # Hex string (RRGGBB)
    # custom-color: "#80FF0000"       # Hex string (AARRGGBB)
    # custom-color: 16711680          # Integer RGB (decimal)
    # custom-color: [1.0, 0.0, 0.0]   # List of floats (RGB, 0.0–1.0)
    # custom-color: [1.0, 0.0, 0.0, 0.5] # List of floats (RGBA, 0.0–1.0)
    # custom-color: [255, 0, 0]     # List of ints (RGB, 0–255)
    # custom-color: [128, 255, 0, 0]# List of ints (RGBA, 0–255)
    custom-name: "&cSuper Speed Potion"
    custom-effects:
      - type: speed
        amplifier: 1
        duration: 600
        ambient: false
        show-particles: true
        show-icon: true
      - type: jump_boost
        amplifier: 2
        duration: 600

Hides the tooltip when hovering over the item.

Minecraft Wiki: hide_tooltip

Key	Type	Description
`hide_tooltip`	Boolean	Whether to hide the tooltip

components:
  hide_tooltip: true

Paper only

One more setting to hide specific tooltip lines:

Key	Type	Description
`hidden_components`	List	List of component types to hide from tooltip (e.g., `ATTACK_RANGE`, `ATTRIBUTE_MODIFIERS`) full list

components:
  hide_tooltip: true
  hidden_components:
    - ATTACK_RANGE
    - ATTRIBUTE_MODIFIERS

potion-duration-scale 1.21.5+

Scales the duration of potion effects.

Minecraft Wiki: potion_duration_scale

components:
  potion-duration-scale: 1.5

profile 1.21.9+

Configures player head appearance.

Minecraft Wiki: profile

Simple (by player name or UUID):

components:
  profile: "Notch"

components:
  profile: "069a79f4-44e9-4726-a5be-fca90e38aaf5"

By texture URL:

components:
  profile: "http://textures.minecraft.net/texture/abc123..."

Advanced configuration:

components:
  profile:
    id: "069a79f4-44e9-4726-a5be-fca90e38aaf5"
    name: "Notch"
    texture: "http://textures.minecraft.net/texture/..."
    model: classic  # or "slim"
    cape: "http://textures.minecraft.net/texture/..."

rarity

Sets the item rarity, which affects the name color.

Minecraft Wiki: rarity

components:
  rarity: EPIC

Available Values:

COMMON - White name
UNCOMMON - Yellow name
RARE - Aqua name
EPIC - Light purple name

recipes

Unlocks recipes when item is obtained (knowledge book).

Minecraft Wiki: recipes

components:
  recipes:
    - "minecraft:diamond_sword"
    - "minecraft:diamond_pickaxe"
    - "minecraft:enchanting_table"

repair-cost

Sets the anvil repair cost.

Minecraft Wiki: repair_cost

components:
  repair-cost: 5

stored-enchantments

Enchantments stored in enchanted books. Supported enchantments are the same as the enchantments component, but these enchantments are only stored in the book and do not apply any effects until transferred to an item using an anvil.

Minecraft Wiki: stored_enchantments

components:
  stored-enchantments:
    mending: 1
    unbreaking: 3

suspicious-stew-effects

Sets potion effects for suspicious stew.

Minecraft Wiki: suspicious_stew_effects

Key	Type	Description
id	String	Potion effect type (e.g., `blindness`, `saturation`)
duration	Integer	Effect duration in ticks (20 ticks = 1 second)
amplifier	Boolean	Effect level (0 = level 1)
ambient	Boolean	Ambient particles (like beacon)
show_particles	Boolean	Show effect particles
show_icon	Boolean	Show effect icon

components:
  suspicious-stew-effects:
    - type: blindness
      amplifier: 0
      duration: 100
    - type: saturation
      amplifier: 0
      duration: 200

swing-animation 1.21.11+

Configures the swing animation when using the item.

Minecraft Wiki: swing_animation

Key	Type	Default	Description
`duration`	Integer	`6`	Animation duration in ticks
`type`	String	`WHACK`	Animation type

components:
  swing-animation:
    duration: 6
    type: WHACK

Animation Types: WHACK, BRUSH

tool

Turn any item into a tool with mining capabilities.

Minecraft Wiki: tool

Key	Type	Default	Description
`default-mining-speed`	Float	`1.0`	Default speed for blocks not in rules
`damage-per-block`	Integer	`1`	Durability lost per block mined
`can-destroy-blocks-in-creative`	Boolean	`true`	Can break blocks in creative mode
`rules`	List	`[]`	Block-specific mining rules

Rule Properties:

Key	Type	Default	Description
`blocks`	List/String	-	Block(s) or block tag
`speed`	Float	`1.0`	Mining speed for these blocks
`correct-for-drops`	Boolean	`false`	Whether blocks drop items when mined

components:
  tool:
    default-mining-speed: 1.0
    damage-per-block: 1
    can-destroy-blocks-in-creative: true
    rules:
      - blocks:
          - minecraft:stone
          - minecraft:granite
          - minecraft:diorite
        speed: 8.0
        correct-for-drops: true
      - blocks: "#minecraft:mineable/pickaxe"
        speed: 4.0
        correct-for-drops: true

Controls tooltip visibility.

Minecraft Wiki: tooltip_display

Key	Type	Default	Description
`hide-tooltip`	Boolean	`false`	Hide the entire tooltip

components:
  tooltip-display:
    hide-tooltip: true

Sets a custom tooltip style from resource packs.

Minecraft Wiki: tooltip_style

components:
  tooltip-style: "minecraft:custom_tooltip"

trim

Applies armor trim patterns.

Minecraft Wiki: trim

Key	Type	Required	Description
`material`	String	Yes	Trim material
`pattern`	String	Yes	Trim pattern

components:
  trim:
    material: gold
    pattern: sentry

Materials: amethyst, copper, diamond, emerald, gold, iron, lapis, netherite, quartz, redstone

Patterns: coast, dune, eye, host, raiser, rib, sentry, shaper, silence, snout, spire, tide, vex, ward, wayfinder, wild

unbreakable

Makes the item unbreakable.

Minecraft Wiki: unbreakable

components:
  unbreakable: true

use-cooldown 1.21.2+

Adds a cooldown after using the item.

Minecraft Wiki: use_cooldown

Key	Type	Default	Description
`seconds`	Float	`0`	Cooldown duration in seconds
`cooldown-group`	String	-	Cooldown group identifier (items in the same group share cooldown)

components:
  use-cooldown:
    seconds: 1.0
    cooldown-group: "my_plugin:special_items"

use-effects 1.21.11+

Configures effects when using the item (like spyglass).

Minecraft Wiki: use_effects

Key	Type	Default	Description
`can-sprint`	Boolean	`false`	Can sprint while using
`speed-multiplier`	Float	`0.2`	Movement speed multiplier while using
`interact-vibrations`	Boolean	`true`	Emit sculk vibrations when interacting

components:
  use-effects:
    can-sprint: false
    speed-multiplier: 0.2
    interact-vibrations: true

use-remainder 1.21.2+

Item left after using (like bowls from stew). Use zMenu item syntax here.

Minecraft Wiki: use_remainder

components:
  use-remainder:
    material: BOWL
    amount: 1

death_protection Paper only 1.21.2+

Configures death protection for items (similar to a Totem of Undying).

Minecraft Wiki: death_protection

Key	Type	Description
`death_effects`	List	List of effects to apply when death is prevented

components:
  death_protection:
    death_effects:
      - type: APPLY_EFFECTS
        probability: 1.0
        effects:
          - id: regeneration
            amplified: true
            duration: 900
          - id: fire_resistance
            duration: 800
          - id: absorption
            amplified: true
            duration: 100
      - type: PLAY_SOUND
        sound: item.totem.use
      - type: TELEPORT_RANDOMLY
        diameter: 16.0
      - type: CLEAR_ALL_EFFECTS
      - type: REMOVE_EFFECTS
        effects:
          - poison
          - wither

Effect Types:

APPLY_EFFECTS - Apply potion effects with probability
PLAY_SOUND - Play a sound
TELEPORT_RANDOMLY - Teleport randomly within diameter
CLEAR_ALL_EFFECTS - Clear all potion effects
REMOVE_EFFECTS - Remove specific effects

repairable Paper only 1.21.2+

Configures item repair behavior.

Minecraft Wiki: repairable

components:
  repairable:
    items:
      - minecraft:diamond
      - minecraft:netherite_ingot

weapon 1.21.5+

Configures weapon damage properties.

Minecraft Wiki: weapon

Key	Type	Default	Description
`item-damage-per-attack`	Integer	`1`	Durability lost per attack
`disable-blocking-for-seconds`	Float	`0`	Duration to disable shield blocking

components:
  weapon:
    item-damage-per-attack: 1
    disable-blocking-for-seconds: 5.0

provides_banner_patterns Paper only 1.21.5+

Configures banner pattern providing behavior for items.

Minecraft Wiki: provides_banner_patterns

components:
  provides_banner_patterns: "minecraft:flower_banner_pattern"

provides_trim_material Paper only 1.21.5+

Configures trim material providing behavior for items.

Minecraft Wiki: provides_trim_material

components:
  provides_trim_material: "minecraft:gold"

writable-book-content

Content for book and quill (writable book).

Minecraft Wiki: writable_book_content

Key	Type	Description
`pages`	List	List of pages with raw text content

components:
  writable-book-content:
    pages:
      - title: "My Journal"
        raw: "Day 1: Started my adventure..."
      - raw: "Day 2: Found a village..."
      - raw: "Day 3: Discovered a stronghold!"

written-book-content

Content for signed written books.

Minecraft Wiki: written_book_content

Key	Type	Description
`title`	String	Book title
`author`	String	Book author name
`generation`	String	Book generation: `ORIGINAL`, `COPY_OF_ORIGINAL`, `COPY_OF_COPY`, `TATTERED`
`pages`	List	List of pages with raw text content

components:
  written-book-content:
    title: "The Legend of Herobrine"
    author: "Notch"
    generation: ORIGINAL
    pages:
      - raw: "Chapter 1\n\nIt was a dark and stormy night..."
      - raw: "Chapter 2\n\nThe mysterious figure appeared..."
      - raw: "The End"

axolotl/variant

Configures axolotl variant for axolotl.

components:
  axolotl/variant: "lucy"

Available Variants: can be found here

cat/collar

Configures cat collar color for cat.

components:
  cat/collar: "red"

cat/variant

Configures cat variant for cat.

components:
  cat/variant: "siamese"

*Available Variants: can be found here

chicken/variant 1.21.5+

Configures chicken variant for chicken.

components:
  chicken/variant: "COLD"

Available Variants: can be found here

cow/variant 1.21.5+

Configures cow variant for cow.

components:
  cow/variant: "COLD"

Available Variants: can be found here

fox/variant

Configures fox variant for fox.

components:
  fox/variant: "RED"

Available Variants: can be found here

frog/variant

Configures frog variant for frog.

components:
  frog/variant: "TEMPERATE"

Available Variants: can be found here

horse/variant

Configures horse variant for horse.

components:
  horse/variant: "BLACK"

Available Variants: can be found here

llama/variant

Configures llama variant for llama.

components:
  llama/variant: "CREAMY"

Available Variants: can be found here

mooshroom/variant

Configures mooshroom variant for mooshroom.

  mooshroom/variant: "BROWN"

Available Variants: can be found here

painting/variant 1.20.5+

Configures painting variant for painting.

components:
  painting/variant: "WITHER"

Available Variants: can be found here

parrot/variant

Configures parrot variant for parrot.

components:
  parrot/variant: "BLUE"

Available Variants: can be found here

pig/variant 1.21.5+

Configures pig variant for pig.

components:
  pig/variant: "COLD"

Available Variants: can be found here

rabbit/variant

Configures rabbit variant for rabbit.

components:
  rabbit/variant: "BLACK"

Available Variants: can be found here

salmon/size 1.21.5+

Configures salmon size for salmon.

components:
  salmon/size: "SMALL"

Available Sizes: can be found here

sheep/color

Configures sheep color for sheep.

components:
  sheep/color: "BLACK"

Available Colors: can be found here

shulker/color

Configures shulker color for shulker.

components:
  shulker/color: "PURPLE"

Available Colors: can be found here

tropical_fish/base_color

Configures tropical fish base color.

components:
  tropical_fish/base_color: "ORANGE"

Available Colors: can be found here

tropical_fish/pattern_color

Configures tropical fish pattern color.

components:
  tropical_fish/pattern_color: "BLUE"

Available Colors: can be found here

villager/variant

Configures villager variant for villager.

components:
  villager/variant: "PLAINS"

Available Variants: can be found here

wolf/variant 1.20.5+

Configures wolf variant for wolf.

components:
  wolf/variant: "RED"

Available Variants: can be found here

wolf/collar 1.20.5+

Configures wolf collar color for wolf.

components:
  wolf/collar: "BLUE"

Available Colors: can be found here

Complete Example

Here's a complete example of a custom legendary sword using components:

item:
  material: DIAMOND_SWORD
  components:
    item-name: "&6&l✦ Excalibur ✦"
    lore:
      - "&7The legendary sword of kings"
      - ""
      - "&7Damage: &c+15"
      - "&7Attack Speed: &a+1.6"
      - ""
      - "&5&oForged in dragon fire"
      - ""
      - "&eRight-click for special ability!"
    rarity: EPIC
    enchantments:
      sharpness: 10
      fire_aspect: 2
      unbreaking: 5
      mending: 1
    enchantment-glint-override: true
    attribute-modifiers:
      - type: generic.attack_damage
        amount: 15
        operation: add_value
        slot: mainhand
      - type: generic.attack_speed
        amount: 1.6
        operation: add_value
        slot: mainhand
    unbreakable: true
    max-damage: 5000
    attack-range:
      max-reach: 4
      max-creative-reach: 6

Version Compatibility

Component	Minimum Version
Most components	1.20.5
`food`, `tool`, `container-loot`, `custom-data`, `damage-resistant`, `ominous-bottle-amplifier`, `painting/variant`, `wolf/variant`, `wolf/collar`	1.20.5
`jukebox-playable`	1.21
`consumable`, `enchantable`, `equippable`, `glider`, `item-model`, `tooltip-style`, `use-cooldown`, `use-remainder`, `death_protection`, `repairable`	1.21.2
`blocks-attacks`, `break-sound`, `potion-duration-scale`, `tooltip-display`, `weapon`, `provides_banner_patterns`, `provides_trim_material`, `chicken/variant`, `cow/variant`, `pig/variant`, `salmon/size`	1.21.5
`profile`	1.21.9
`attack-range`, `damage-type`, `kinetic-weapon`, `minimum-attack-charge`, `piercing-weapon`, `swing-animation`, `use-effects`	1.21.11

Next Steps

Learn how to use components in Item Configuration
Add items to Buttons
Create Patterns for reusable templates

Basic Structure​

attack-range 1.21.11+​

attribute-modifiers​

banner-patterns​

base-color​

block-state​

blocks-attacks 1.21.5+​

break-sound 1.21.5+​

bundle-contents​

charged-projectiles​

consumable 1.21.2+​

container​

container-loot​

custom-data​

custom-model-data​

damage​

damage-resistant​

damage-type 1.21.11+​

dyed-color​

enchantable 1.21.2+​

enchantment-glint-override​

enchantments​

custom_name Paper only​

intangible_projectile Paper only​

map_decorations Paper only​

note_block_sound Paper only​

pot_decorations Paper only​

equippable 1.21.2+​

firework-explosion​

fireworks​

food​

glider 1.21.2+​

instrument​

item-model 1.21.2+​

item-name​

jukebox-playable 1.21+​

kinetic-weapon 1.21.11+​

lodestone-tracker​

lore​

map-color​

map-id​

max-damage​

max-stack-size​

minimum-attack-charge 1.21.11+​

ominous-bottle-amplifier​

piercing-weapon 1.21.11+​

potion-contents​

hide_tooltip​

Paper only​

potion-duration-scale 1.21.5+​

profile 1.21.9+​

rarity​

recipes​

repair-cost​

stored-enchantments​

suspicious-stew-effects​

swing-animation 1.21.11+​

tool​

tooltip-display 1.21.5+​

tooltip-style 1.21.2+​

trim​

unbreakable​

use-cooldown 1.21.2+​

use-effects 1.21.11+​

use-remainder 1.21.2+​

death_protection Paper only 1.21.2+​

repairable Paper only 1.21.2+​

weapon 1.21.5+​

provides_banner_patterns Paper only 1.21.5+​

provides_trim_material Paper only 1.21.5+​

writable-book-content​

written-book-content​

axolotl/variant​

cat/collar​

cat/variant​

chicken/variant 1.21.5+​

cow/variant 1.21.5+​

fox/variant​

frog/variant​

horse/variant​

Basic Structure

attack-range 1.21.11+

attribute-modifiers

banner-patterns

base-color

block-state

blocks-attacks 1.21.5+

break-sound 1.21.5+

bundle-contents

charged-projectiles

consumable 1.21.2+

container

container-loot

custom-data

custom-model-data

damage

damage-resistant

damage-type 1.21.11+

dyed-color

enchantable 1.21.2+

enchantment-glint-override

enchantments

custom_name Paper only

intangible_projectile Paper only

map_decorations Paper only

note_block_sound Paper only

pot_decorations Paper only

equippable 1.21.2+

firework-explosion

fireworks

food

glider 1.21.2+

instrument

item-model 1.21.2+

item-name

jukebox-playable 1.21+

kinetic-weapon 1.21.11+

lodestone-tracker

lore

map-color

map-id

max-damage

max-stack-size

minimum-attack-charge 1.21.11+

ominous-bottle-amplifier

piercing-weapon 1.21.11+

potion-contents

hide_tooltip

Paper only

potion-duration-scale 1.21.5+

profile 1.21.9+

rarity

recipes

repair-cost

stored-enchantments

suspicious-stew-effects

swing-animation 1.21.11+

tool

tooltip-display 1.21.5+

tooltip-style 1.21.2+

trim

unbreakable

use-cooldown 1.21.2+

use-effects 1.21.11+

use-remainder 1.21.2+

death_protection Paper only 1.21.2+

repairable Paper only 1.21.2+

weapon 1.21.5+

provides_banner_patterns Paper only 1.21.5+

provides_trim_material Paper only 1.21.5+

writable-book-content

written-book-content

axolotl/variant

cat/collar

cat/variant

chicken/variant 1.21.5+

cow/variant 1.21.5+

fox/variant

frog/variant

horse/variant