Components

ItemsAdderAdditions applies Minecraft data components to custom items at pack-generation time via the ItemsAdder item modifier hook. Add a components section under your item definition and run /iazip.

items:
  my_item:
    components:
      rarity: RARE
      use_cooldown:
        cooldown: 1.5
      tool:
        default_mining_speed: 2.0
        rules:
          - blocks: "#minecraft:logs"
            speed: 4.0
            correct_for_drops: true

Components are applied when ItemsAdder rebuilds the pack/item data. Run /iazip after changing component YAML. /iareload reloads other ItemsAdderAdditions content, but not components.

Status legend

Generic NMS components

For component keys that have no specialized IAA handler, IAA falls back to a generic NMS pipeline. The key is normalized (custom_data becomes minecraft:custom_data), the value tree is parsed from YAML, and the result is applied through Minecraft's Mojang codec system via NMS.

Minimum server version for generic components: 1.21.3.

On 1.20.6 and 1.21.1, the generic NMS pipeline is not available. Specialized handlers still work on those versions.

Usage

Use the full namespaced key or the short form (the minecraft: prefix is added automatically):

items:
  my_item:
    components:
      minecraft:custom_data:
        my_plugin:
          id: my_item
          tier: 3
          enabled: true

Short form (equivalent):

items:
  my_item:
    components:
      custom_data:
        my_plugin:
          id: my_item

The YAML structure must match the vanilla codec for that component. IAA does not reinterpret the shape. If the codec rejects the value, IAA logs a warning and skips that component.

Note: minecraft:custom_data is a real vanilla NBT compound component. Do not confuse it with Bukkit's PersistentDataContainer (PDC). The two systems are independent. PDC data is stored internally by Bukkit and is not custom_data.

Components reference

attack_range

Status: Specialized | Minimum version: 1.21.11

Overrides the attack range of the item for melee and projectile attacks.

components:
  attack_range:
    max_reach: 5.0
    max_creative_reach: 7.0
    hitbox_margin: 0.5

banner_patterns

Status: Specialized

Sets the banner pattern layers on a banner item.

components:
  banner_patterns:
    - type: stripe_top
      color: RED
    - type: square_bottom_left
      color: BLUE

Valid dye colors: WHITE, ORANGE, MAGENTA, LIGHT_BLUE, YELLOW, LIME, PINK, GRAY, LIGHT_GRAY, CYAN, PURPLE, BLUE, BROWN, GREEN, RED, BLACK.

Pattern type keys are Minecraft registry keys. The minecraft: prefix is optional (e.g. stripe_top and minecraft:stripe_top are equivalent).

base_color

Status: Specialized

Sets the base color of a shield item.

components:
  base_color: RED

blocks_attacks

Status: Specialized

Makes the item block incoming attacks like a shield.

damage_reductions entry:

item_damage section:

components:
  blocks_attacks:
    block_delay_seconds: 0.25
    disable_cooldown_scale: 1.0
    bypassed_by: "#minecraft:bypasses_shield"
    block_sound: minecraft:item.shield.block
    disable_sound: minecraft:item.shield.break
    damage_reductions:
      - type: "#minecraft:is_projectile"
        horizontal_blocking_angle: 90.0
        base: 0.0
        factor: 0.5
      - type: minecraft:player_attack
        base: 1.0
        factor: 1.0
    item_damage:
      threshold: 3.0
      base: 1.0
      factor: 1.0

The type field in damage_reductions accepts a tag string (#minecraft:is_fire), a single damage type key (minecraft:fire), or a list of damage type keys.

bundle_contents

Status: Specialized

Sets the initial contents of a bundle item. Accepts vanilla IDs, ItemsAdder IDs, and mmoitems:TYPE:ID format. See ID reference for full format details.

components:
  bundle_contents:
    - minecraft:arrow
    - my_pack:special_arrow

can_break

Status: Specialized

Restricts what blocks this item can break in Adventure mode.

components:
  can_break:
    - minecraft:stone
    - "#minecraft:logs"

Accepts block IDs (minecraft:stone) and block tags (#minecraft:logs). The minecraft: prefix is optional.

can_place_on

Status: Specialized

Restricts what blocks this item can be placed on in Adventure mode.

components:
  can_place_on:
    - minecraft:grass_block
    - "#minecraft:dirt"

Same format as can_break.

charged_projectiles

Status: Specialized

Sets the projectiles pre-loaded in a crossbow. Accepts vanilla IDs, ItemsAdder IDs, and mmoitems:TYPE:ID format. See IDs.

components:
  charged_projectiles:
    - minecraft:arrow
    - my_pack:special_bolt

damage_resistant

Status: Specialized

Makes the item entity immune to a category of damage (like netherite ignoring fire).

components:
  damage_resistant: minecraft:is_fire

Accepts a damage type tag key. The # prefix and minecraft: prefix are both optional (is_fire, #is_fire, minecraft:is_fire, #minecraft:is_fire are all equivalent).

damage_type

Status: Specialized

Sets the damage type used when the item entity deals damage.

components:
  damage_type: minecraft:magic

Must be a valid damage type registry key.

death_protection

Status: Specialized

Prevents death and optionally applies effects when triggered (like a totem of undying).

Effect types in death_effects:

Potion effect entry (used in apply_effects):

components:
  death_protection:
    death_effects:
      - type: apply_effects
        probability: 1.0
        effects:
          - type: regeneration
            duration: 900
            amplifier: 1
          - type: absorption
            duration: 100
            amplifier: 1
      - type: remove_effects
        effects:
          - wither
          - poison
      - type: play_sound
        sound: minecraft:item.totem.use

Omit death_effects entirely for a bare totem effect (prevents death, no extra effects):

components:
  death_protection: {}

dyed_color

Status: Specialized

Sets the dye color of leather armor or other dyeable items.

components:
  dyed_color: "#FF4400"

Accepts #RRGGBB hex color strings.

enchantable

Status: Specialized

Sets the enchantability value of the item (affects enchantment quality in the enchanting table).

components:
  enchantable: 15

Range: 1 - 255. Higher values improve enchantment quality.

firework_explosion

Status: Specialized

Sets the firework explosion effect on a firework star item.

Valid types: BALL, BALL_LARGE, STAR, BURST, CREEPER.

components:
  firework_explosion:
    type: STAR
    colors:
      - "#FF0000"
      - "#0000FF"
    fade_colors:
      - "#FFFFFF"
    trail: true
    flicker: false

fireworks

Status: Specialized

Sets the firework properties on a firework rocket item.

Each entry in explosions uses the same schema as firework_explosion.

components:
  fireworks:
    flight_duration: 2
    explosions:
      - type: BURST
        colors:
          - "#FFAA00"
        trail: true

intangible_projectile

Status: Specialized

Marks this item as an intangible projectile (cannot be picked up after being shot).

components:
  intangible_projectile: true

Set to true or any non-null value to enable. This is a marker component with no properties.

kinetic_weapon

Status: Specialized | Minimum version: 1.21.5

Makes the item deal damage based on player movement speed (like a mace).

Condition sections (dismount_conditions, knockback_conditions, damage_conditions):

components:
  kinetic_weapon:
    damage_multiplier: 2.0
    forward_movement: 1.5
    sound: minecraft:entity.player.attack.sweep
    damage_conditions:
      min_speed: 0.1

lodestone_tracker

Status: Specialized

Makes a compass point toward a lodestone location.

components:
  lodestone_tracker:
    world: world
    x: 100
    y: 64
    z: -200
    tracked: true

If world is omitted, the compass is unlinked (shows a spinning needle). If world is set but the world is not loaded at reload time, IAA logs a warning and applies the component without a location.

map_color

Status: Specialized

Sets the border color of a filled map item.

components:
  map_color: "#2A6DB5"

Accepts #RRGGBB hex color strings.

map_decorations

Status: Specialized

Sets fixed decorations (markers) on a filled map.

components:
  map_decorations:
    my_marker:
      type: RED_MARKER
      x: 100.0
      z: 200.0
      rotation: 0.0
    another_marker:
      type: player
      x: -50.0
      z: 75.0
      rotation: 90.0

Each key under map_decorations is a unique decoration ID. type is a MapCursor.Type key (case-insensitive; minecraft: prefix optional). x and z are world coordinates. rotation is in degrees.

map_id

Status: Specialized

Links the item to a specific map by its integer ID.

components:
  map_id: 42

minimum_attack_charge

Status: Specialized | Minimum version: 1.21.1

Sets the minimum attack charge fraction required to trigger full-charge effects.

components:
  minimum_attack_charge: 0.9

Range: 0.0 - 1.0.

ominous_bottle_amplifier

Status: Specialized

Sets the amplifier level of an ominous bottle (affects Bad Omen strength when consumed).

components:
  ominous_bottle_amplifier: 3

Range: 0 - 4.

piercing_weapon

Status: Specialized | Minimum version: 1.21.5

Makes the item pierce through entities (like an arrow with Piercing).

components:
  piercing_weapon:
    deals_knockback: true
    dismounts: false
    hit_sound: minecraft:entity.arrow.hit

pot_decorations

Status: Specialized

Sets the pottery sherd decorations on a decorated pot.

components:
  pot_decorations:
    back: arms_up_pottery_sherd
    left: archer_pottery_sherd
    right: blade_pottery_sherd
    front: burn_pottery_sherd

Accepts vanilla item IDs. The minecraft: prefix is optional.

potion_contents

Status: Specialized

Sets the potion effects of a potion, splash potion, or lingering potion item.

At least one of potion, color, custom_name, or effects must be present.

components:
  potion_contents:
    potion: minecraft:strength
    color: "#FF0000"
    custom_name: "Super Strength"
    effects:
      - type: strength
        duration: 600
        amplifier: 2

potion_duration_scale

Status: Specialized

Multiplies the duration of all potion effects applied by this item.

components:
  potion_duration_scale: 2.0

Range: 0.0 - 255.0.

profile

Status: Specialized

Sets the player skin profile on a player head item. Accepts a player name (resolved by the client) or a section with explicit profile data.

Simple form (player name):

components:
  profile: Notch

Section form (explicit UUID, name, or texture):

components:
  profile:
    name: Notch
    uuid: 069a79f4-44e9-4726-a5be-fca90e38aaf5
    texture: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvLi4uIn19fQ==

At least one of name, uuid, or texture is required in the section form.

provides_banner_patterns

Status: Specialized

Marks the item as an ingredient that unlocks banner patterns when placed in a loom.

components:
  provides_banner_patterns: minecraft:no_item_required

Accepts a banner pattern tag key. The # prefix is optional.

provides_trim_material

Status: Specialized

Marks the item as a smithing trim material.

components:
  provides_trim_material: gold

Accepts a trim material registry key. The minecraft: prefix is optional.

rarity

Status: Specialized

Sets the rarity of the item, which affects the item name color in the default resource pack.

components:
  rarity: RARE

Valid values: COMMON, UNCOMMON, RARE, EPIC.

repairable

Status: Specialized

Sets what items can repair this item in an anvil.

Accepts a tag string or a list of item IDs:

# Using a tag
components:
  repairable: "#minecraft:planks"

# Using a list of items
components:
  repairable:
    - minecraft:diamond
    - minecraft:netherite_ingot

stored_enchantments

Status: Specialized

Sets the enchantments stored in an enchanted book. Uses a section of enchantment_key: level pairs.

components:
  stored_enchantments:
    sharpness: 5
    looting: 3
    minecraft:mending: 1

Level range: 1 - 255. The minecraft: prefix is optional.

suspicious_stew_effects

Status: Specialized

Sets the effects given by a suspicious stew item.

components:
  suspicious_stew_effects:
    - type: speed
      duration: 200
    - type: minecraft:night_vision
      duration: 400

duration is in ticks. Default is 160. The minecraft: prefix on effect types is optional.

swing_animation

Status: Specialized | Minimum version: 1.21.5

Sets the swing animation type and duration for melee attacks.

components:
  swing_animation:
    type: WHACK
    duration: 6

tool

Status: Specialized

Configures the item as a tool with mining speed rules.

Rule section:

components:
  tool:
    default_mining_speed: 1.0
    damage_per_block: 1
    can_destroy_in_creative: true
    rules:
      - blocks: "#minecraft:mineable/pickaxe"
        speed: 6.0
        correct_for_drops: true
      - blocks:
          - minecraft:obsidian
          - minecraft:crying_obsidian
        speed: 12.0
        correct_for_drops: true

blocks accepts a tag string (#minecraft:logs), a single block ID (minecraft:stone), or a list of block IDs.

correct_for_drops: true means this tool produces correct drops; false means it does not; omitting the key means NOT_SET (inherits vanilla defaults).

tooltip_display

Status: Specialized

Controls which components are shown in the item tooltip.

components:
  tooltip_display:
    hide_tooltip: false
    hidden_components:
      - enchantments
      - attribute_modifiers
      - stored_enchantments

hidden_components accepts DataComponentTypes field names (case-insensitive). Use the Minecraft component key without the minecraft: prefix and in UPPER_SNAKE_CASE (e.g. ATTRIBUTE_MODIFIERS). The lookup is case-insensitive.

use_cooldown

Status: Specialized

Sets a use cooldown on the item.

components:
  use_cooldown:
    cooldown: 2.0

If group is omitted, the cooldown group defaults to itemsadder:<item_id>, making the cooldown item-specific. Set group to share a cooldown with other items:

components:
  use_cooldown:
    cooldown: 5.0
    group: my_pack:special_items

use_remainder

Status: Specialized

Sets what item remains in the slot after this item is fully consumed.

components:
  use_remainder: minecraft:glass_bottle

Accepts vanilla IDs, ItemsAdder IDs, and mmoitems:TYPE:ID format. See IDs.

weapon

Status: Specialized | Minimum version: 1.21.5

Configures the item as a weapon with custom damage and blocking interaction.

components:
  weapon:
    item_damage_per_attack: 2
    disable_blocking_for_seconds: 0.6

disable_blocking_for_seconds: when this weapon hits a blocking entity, blocking is disabled for this duration.

writable_book_content

Status: Specialized

Sets the pages of a writable book (book and quill).

components:
  writable_book_content:
    - "Page 1 content here."
    - "Page 2 content here."

Version summary

Components that require a newer version than the running server are silently skipped with a warning in the console.