In Minecraft, data components are structured key-value properties used to define and store behavior and attributes. They are attached to different things:

• Item components: properties that live on item stacks (e.g., enchantments, food, attribute_modifiers). They affect how items behave in inventories, commands, containers, etc.
• Entity variant components: properties exposed as components for certain entity variants when represented as items or spawn eggs (e.g., wolf/variant, cat/collar). These follow the same component mechanics but target entity-specific customization.

This page focuses on using item components with Kore. For the vanilla reference and exhaustive definitions, see the Minecraft Wiki - Data component format. The custom item example of the playground builds an item with components and runs in your browser.

The Kore library provides a comprehensive and user-friendly way to work with these components, enabling you to create custom items with ease. This article will guide you through the process of using components with Kore, showcasing examples and best practices.

Creating Custom Items with Components

Let's dive into creating custom items with various components using Kore. Below are examples of how to define and manipulate item properties such as attribute modifiers, enchantments, and more.

Attribute Modifiers

Attribute modifiers allow you to alter the attributes of an item, such as increasing damage or changing the scale. Here's how to define a stone sword with an attribute modifier using Kore:

import io.github.ayfri.kore.commands.AttributeModifierOperation
import io.github.ayfri.kore.generated.Items
import io.github.ayfri.kore.generated.Attributes

val attributeModifiersTest = Items.STONE_SWORD {
	attributeModifiers {
		modifier(
			type = Attributes.SCALE,
			amount = 1.0,
			name = "big",
			operation = AttributeModifierOperation.ADD_VALUE,
		)
	}
}

Enchantments

You can add enchantments to items to give them special abilities. Here’s an example of adding the Sharpness enchantment to a stone sword:

import io.github.ayfri.kore.generated.Enchantments

val enchantmentsTest = Items.STONE_SWORD {
	enchantments(mapOf(Enchantments.SHARPNESS to 5))
}

Check out the Enchantments article for more information on how to use enchantments with Kore.

Custom Names and Lore

Custom names and lore can be added to items to give them unique identifiers and background stories:

import io.github.ayfri.kore.arguments.chatcomponents.textComponent
import io.github.ayfri.kore.arguments.colors.Color

val customNameTest = Items.STONE_SWORD {
	customName(textComponent("Legendary Sword", Color.AQUA))
}

Fireworks

You can define the properties of fireworks, including the shape and colors of the explosions:

import io.github.ayfri.kore.arguments.components.item.FireworkExplosionShape
import io.github.ayfri.kore.arguments.colors.Color

val fireworksTest = Items.FIREWORK_ROCKET {
	fireworks(flightDuration = 1) {
		explosion(FireworkExplosionShape.BURST) {
			colors(Color.AQUA)
			fadeColors(Color.BLACK, Color.WHITE)
			hasTrail = true
			hasTwinkle = true
		}
	}
}

See how to set custom colors in the Colors article.

Custom Block Data

You can define custom properties for blocks using block entity data. Here's an example of adding custom data to a bee nest block:

import io.github.ayfri.kore.generated.Blocks
import io.github.ayfri.kore.generated.Items

val blockEntityDataTest = Items.BEE_NEST {
	blockEntityData(Blocks.BEE_NEST) {
		this["test"] = "test"
	}
}

Block Transformer

blockTransformer turns the block the item is used on into another one, like axes stripping logs or honeycombs waxing copper. It takes the ID of a block transformer file, either a vanilla one (axe, hoe, shovel) or one of your own. Inline rule lists aren't possible because the game only reads this component from a file.

val strip = blockTransformer("strip_oak") {
	rule(ruleBasedStateProvider {
		rule(copyPropertiesProvider(simpleStateProvider(Blocks.STRIPPED_OAK_LOG, mapOf("axis" to "y")))) {
			matchingBlocks(Blocks.OAK_LOG)
		}
	}) {
		sound = SoundEvents.Item.Axe.STRIP
	}
}

val axe = Items.IRON_AXE {
	blockTransformer(strip)
}

val vanillaAxe = Items.IRON_AXE {
	blockTransformer(BlockTransformers.AXE)
}

The rules, their options (sound, loot, itemDamagePerUse, ...) and their defaults are described on the Block Transformers page.

Compostable

compostable makes an item usable in a composter. It takes the number of layers added as an Int or as the ID of a context int provider file, either a vanilla one from ContextIntProviders.Compostable or one of your own. An inline provider object isn't possible because the game only reads a number or an ID there.

val seeds = Items.WHEAT_SEEDS {
	compostable(ContextIntProviders.Compostable.LOW)
}

val pumpkin = Items.PUMPKIN {
	compostable(1)  // compostable={layers:1}
}

val layers = contextIntProvider("my_layers", 1)
val sapling = Items.OAK_SAPLING {
	compostable(layers)
}

Cooking and brewing fuel

cookingFuel makes an item burn in furnaces, smokers and blast furnaces, brewingFuel makes it power a brewing stand. Their fields are a plain number or the ID of a context provider file, never an inline provider object: the whole-number fields (burnTime, uses) take an Int or a context int provider ID from ContextIntProviders.Cooking / ContextIntProviders.Brewing or your own, the speeds take a Float or a context float provider ID from ContextFloatProviders.Cooking / ContextFloatProviders.Brewing or your own. cookingFuel takes the burn time in ticks and a cooking speed (vanilla ContextFloatProviders.Cooking.SPEED_DEFAULT when omitted), brewingFuel takes both a speed and the number of brews, which have no default. resolvableInt(...) and resolvableFloat(...) wrap either form, to mix numbers and IDs in one component. There is no #brewing_fuel item tag: an item is a brewing fuel through this component.

val stick = Items.STICK {
	cookingFuel(ContextIntProviders.Cooking.TIME_COAL)
}

val burnTime = contextIntProvider("long_burn", 6400)
val speed = contextFloatProvider("fast_burn", 2f)
val charcoal = Items.CHARCOAL {
	cookingFuel(burnTime, speed)
}

val coal = Items.COAL {
	cookingFuel(burnTime = 200, speedMultiplier = 1.5f)  // cooking_fuel={burn_time:200,speed_multiplier:1.5f}
}

val mixed = Items.BLAZE_ROD {
	cookingFuel(resolvableInt(ContextIntProviders.Cooking.TIME_COAL), resolvableFloat(2f))
}

val dust = Items.BLAZE_POWDER {
	brewingFuel(ContextFloatProviders.Brewing.SPEED_DEFAULT, ContextIntProviders.Brewing.USES_DEFAULT)
}

val crystal = Items.AMETHYST_SHARD {
	brewingFuel(speedMultiplier = 2f, uses = 20)  // brewing_fuel={speed_multiplier:2.0f,uses:20}
}

Sign text

signTextFront and signTextBack store the text of one side of a sign on an item, so a placed sign keeps it. Both take exactly 4 lines, one component each (anything else throws), and share the same options in their block: color (a DyeColors), hasGlowingText and filteredMessages, the 4 lines shown to players with the profanity filter on.

val sign = Items.OAK_SIGN {
	signTextFront(text("Shop", Color.GOLD), text(), text("Open"), text()) {
		color = DyeColors.BLACK
		hasGlowingText = true
	}
	signTextBack(text("Closed"), text(), text(), text())
}

When a line is styled, every line is written as a compound, since a list holds a single type in NBT.

Mob visibility

mobVisibility scales the range at which mobs detect whoever carries the item, for the entity types and entity type tags it lists. 0.0 reduces the range to 2 blocks, 10.0 multiplies it by ten (values outside 0 to 10 throw), and stacked items never exceed 10.0.

val mask = Items.CARVED_PUMPKIN {
	mobVisibility(0f, EntityTypes.ENDERMAN, Tags.EntityType.SKELETONS)
}

Villager food

villagerFood makes villagers eat the item, restoring nutrition hunger (at least 1, otherwise it throws).

val bread = Items.BREAD {
	villagerFood(2)
}

Waxed

waxed is an empty marker keeping a sign item waxed, so the placed sign can't be edited.

val sign = Items.OAK_SIGN {
	signTextFront(text("Welcome"), text(), text(), text())
	waxed()
}

Profile

The profile component can be either a player profile or a texture-based profile.

Player Profile

A player profile uses a player's name or UUID:

Items.PLAYER_HEAD {
	playerProfile("Notch")
}

Texture Profile

A texture profile points at textures instead of a player. texture takes a PlayerSkinTextureArgument (the game's skins are in Textures.Entity.Player.Slim and Textures.Entity.Player.Wide), elytra an ElytraTextureArgument (Textures.Entity.Equipment.Wings.ELYTRA), cape a CapeTextureArgument and model the arm width:

Items.PLAYER_HEAD {
	textureProfile(texture = Textures.Entity.Player.Slim.ALEX, model = MannequinModel.SLIM)
}

A texture from a resource pack is given as a namespace:path string, a bare path stays in minecraft:

Items.PLAYER_HEAD {
	textureProfile(texture = "mypack:skins/bob", cape = "mypack:capes/guild")
}

Recipes result with components

You can define recipes with components as well. Here's an example of crafting a custom enchanted golden apple using a shaped recipe:

recipes {
	craftingShaped("enchanted_golden_apple") {
		pattern(
			"GGG",
			"GAG",
			"GGG"
		)

		key("G", Items.GOLD_BLOCK)
		key("A", Items.APPLE)

		result(Items.ENCHANTED_GOLDEN_APPLE {
			food(nutrition = 10, saturation = 5.0f)
			consumable(consumeSeconds = 1.6f, animation = ConsumeAnimation.EAT, sound = SoundEvents.Entity.Generic.EAT) {
				onConsumeEffects {
					applyEffects(
						probability = 1f,
						Effect(
							id = Effects.REGENERATION,
							duration = 40,
							amplifier = 1,
							ambient = true,
							showParticles = true,
							showIcon = true
						)
					)
				}
			}
		})
	}
}

onConsumeEffects also takes teleportRandomly(diameter, directionalParticles), where directionalParticles (true when omitted) sets whether the teleport particles follow the direction of the move:

consumable(consumeSeconds = 1.6f, animation = ConsumeAnimation.EAT, sound = SoundEvents.Entity.Generic.EAT) {
	onConsumeEffects {
		teleportRandomly(diameter = 8f, directionalParticles = false)
	}
}

Example Usage

To give yourself an item with custom components using the /give command, you can define the item and its components as shown in the following example:

import io.github.ayfri.kore.generated.Items
import io.github.ayfri.kore.utils.set

// Define the item with a custom name
val customStone = Items.STONE {
	damageResistant(Tags.DamageType.IS_FIRE)
	customName(textComponent("Special Stone", Color.AQUA))
	rarity(Rarities.EPIC)
	lore(
		textComponent("A stone with special properties.", Color.GRAY) +
			text("Use it wisely!", Color.GRAY)
	)
}

// Use the /give command to give the item to yourself
give(self(), customStone)

This example creates a custom stone item with a special name "Special Stone" in aqua color and gives it to the player using the /give command.

Full list of Item components

Below is an alphabetical list of all item component helpers available in Kore. The names match the DSL functions you call inside an Items.* { } builder.

Works great with Inventory Manager

If you build rich items with components and want to enforce them in player GUIs or chest slots, pair them with the Inventory Manager. It lets you keep specific items in slots, react to takes, and clean up other slots while preserving all component data.

Patch items

When you need to patch components on existing stacks (set name/lore, toggle tooltips, edit container contents, etc.) at runtime, use Item Modifiers. Kore maps the vanilla functions like set_components, set_contents, set_fireworks, and more.

Custom Component

For a component Kore has no helper for (a modded one, or a brand-new vanilla one), wrap its raw NBT in a CustomComponent and store it under the component name. An extension on ComponentsScope gives it the same call syntax as the built-in helpers:

package your.package

import io.github.ayfri.kore.arguments.components.ComponentsScope
import io.github.ayfri.kore.arguments.components.item.CustomComponent
import io.github.ayfri.kore.arguments.types.resources.FunctionArgument
import io.github.ayfri.kore.utils.nbt
import io.github.ayfri.kore.utils.set

fun ComponentsScope.use(function: FunctionArgument, damage: Int = 0, cooldown: Float = 0f) = apply {
	this["mymod:use"] = CustomComponent(nbt {
		this["function"] = function.asId()
		this["damage"] = damage
		this["cooldown"] = cooldown
	})
}

And here's how you can use this custom component in an item definition:

import io.github.ayfri.kore.generated.Items
import your.package.use

val myFunction = function("use_weapon") {
	// Your function code here.
}

val customItem = Items.DIAMOND_SWORD {
	use(myFunction, damage = 4, cooldown = 1.5f)
}
// Result:
// minecraft:diamond_sword[mymod:use={function:"datapack:use_weapon",damage:4,cooldown:1.5f}]

Entity Variant Components (25w04a+)

Introduced in snapshot 25w04a

Entity variants such as axolotl colours, cat collars or tropical-fish patterns are now exposed as data components and can be used on entities, spawn-egg items, mob buckets and paintings. This replaces the old type_specific NBT fields.

Kore ships dedicated helpers for each of these components. You can attach them to an Items.* builder the exact same way you attach any other component:

import io.github.ayfri.kore.arguments.enums.*
import io.github.ayfri.kore.generated.Items
import io.github.ayfri.kore.generated.PaintingVariants

// Axolotl bucket with the blue variant
val blueAxolotlBucket = Items.AXOLOTL_BUCKET {
	axolotlVariant(AxolotlVariants.BLUE)
}

// Cat spawn-egg with a red collar
val redCollarCat = Items.CAT_SPAWN_EGG {
	catCollar(DyeColors.RED)
}

// Painting item selecting the "kebab" variant (namespace implied)
val kebabPainting = Items.PAINTING {
	paintingVariant(PaintingVariants.KEBAB)
}

These components can also be queried inside predicates:

predicate("only_blue_axolotls") {
	entityProperties {
		components {
			axolotlVariant(AxolotlVariants.BLUE)
		}
	}
}

The full list of variant helpers currently included in Kore is:

• axolotlVariant(..)
• catCollar(..) / catVariant(..)
• chickenVariant(..)
• cowVariant(..)
• cushionColor(..)
• foxVariant(..)
• frogVariant(..)
• horseVariant(..)
• llamaVariant(..)
• mooshroomVariant(..)
• paintingVariant(..)
• parrotVariant(..)
• pigVariant(..)
• rabbitVariant(..)
• salmonSize(..)
• sheepColor(..)
• shulkerColor(..)
• tropicalFishBaseColor(..) / tropicalFishPattern(..) / tropicalFishPatternColor(..)
• villagerVariant(..)
• wolfCollar(..) / wolfSoundVariant(..) / wolfVariant(..)
• zombieNautilusVariant(..)

They follow the exact same naming and DSL pattern you already know:

fun ComponentsScope.wolfVariant(variant: WolfVariants) { /*…*/ }

Because the logic lives in regular data components, you automatically get:

• Compatibility with the itemStack / Items.* DSL
• Predicate support through components {}
• Correct serialization back to the vanilla command and NBT syntax

Feel free to mix several variant components on the same ComponentsScope:

Items.WOLF_SPAWN_EGG {
	wolfCollar(DyeColors.BLACK)
	wolfVariant(WolfVariants.SNOWY)
}

Component Matchers & Item Predicates

Kore provides powerful tools for matching and filtering items based on their components. This is useful in predicates, execute conditions, and loot tables. There are two distinct forms:

• Item predicates (.predicate { } / itemPredicate { }) produce the inline command syntax <item>[predicate], used anywhere an item argument is accepted - /give, /clear, the items selector, execute if items.
• Component matchers (predicates { } inside matchTool { }, or subPredicates { } inside .predicate { }) check the same components from within a predicate file - see Item Predicates and Item Sub-Predicates in the Predicates guide for how they plug into a full predicate.

Both forms share the same set of component checks - see Available Component Matchers below for the full list.

Item Predicates

Item predicates let you filter items by their components using the command syntax <item>[predicate]:

import io.github.ayfri.kore.arguments.components.*
import io.github.ayfri.kore.arguments.components.item.*
import io.github.ayfri.kore.generated.Items
import io.github.ayfri.kore.generated.ItemComponentTypes

// Match items with specific component values
val damagedSword = Items.DIAMOND_SWORD.predicate {
	damage(10)
}
// Result: minecraft:diamond_sword[damage=10]

// Match any item with a component present (existence check)
val hasInstrument = itemPredicate {
	isPresent(ItemComponentTypes.INSTRUMENT)
}
// Result: *[instrument]

// Partial matching with ~ syntax
val customDataMatch = Items.STONE.predicate {
	customData {
		this["myKey"] = "myValue"
	}
	partial(ItemComponentTypes.CUSTOM_DATA)
}
// Result: minecraft:stone[custom_data~{myKey:"myValue"}]

// Negated predicates (component must NOT have this value)
val notDamaged = Items.DIAMOND_SWORD.predicate {
	!damage(0)
}
// Result: minecraft:diamond_sword[!damage=0]

// Multiple alternatives with OR
val multipleValues = Items.STONE.predicate {
	damage(1) or damage(2) or damage(3)
}
// Result: minecraft:stone[damage=1|damage=2|damage=3]

// Count predicate
val stackOf10 = Items.DIAMOND.predicate {
	count(10)
}
// Result: minecraft:diamond[count=10]

Practical Example: Clearing Items by Name

A common vanilla pattern is clearing every item with a specific item_name, regardless of its item type - the raw command looks like clear @s *[minecraft:item_name="Blank"] 2. It breaks down into three pieces: @s is the target, *[minecraft:item_name="Blank"] is an item predicate matching any item (*) whose item_name component equals "Blank", and 2 is the max count to remove. Build the same thing with Kore's clear command and itemPredicate { }:

import io.github.ayfri.kore.commands.clear
import io.github.ayfri.kore.arguments.types.literals.self

function("clear_blank_items") {
	clear(self(), itemPredicate { itemName("Blank") }, 2)
}

This generates clear @s *[item_name="Blank"] 2. Because no ItemArgument is passed to itemPredicate { }, it defaults to * (any item) - pass an item to .predicate { } instead (e.g. Items.PAPER.predicate { itemName("Blank") }) if you want to restrict the match to a specific item type too.

Component Matchers (Sub-Predicates)

For matching logic beyond a plain item predicate, use the predicates { } builder inside matchTool { } (or subPredicates { } inside .predicate { }) with component matchers:

import io.github.ayfri.kore.arguments.components.matchers.*
import io.github.ayfri.kore.arguments.numbers.ranges.rangeOrInt

predicate("upgradeable_pickaxe") {
	matchTool {
		items(Items.DIAMOND_PICKAXE)
		predicates {
			// Match damage component with range
			damage {
				durability = rangeOrInt(1..100)
				damage = rangeOrInt(0..10)
			}

			// Match enchantments
			enchantments {
				enchantment(Enchantments.SHARPNESS, level = 3)
			}

			// Match potion contents
			potionContents(Potions.SWIFTNESS, Potions.STRENGTH)
		}
	}
}

potionContents matches the potions of the item, given as potions or a potion tag, and its active effects. The block form sets both potions and effects, effects taking the same contains, countElement and size checks as the other collection matchers. Each element is a map of mob effects to a mobEffectPredicate, like the entity effects predicate:

import io.github.ayfri.kore.features.predicates.sub.mobEffectPredicate

predicates {
	potionContents {
		potions(Potions.SWIFTNESS, Potions.STRONG_SWIFTNESS)
		effects {
			contains(mapOf(Effects.SPEED to mobEffectPredicate { amplifier = rangeOrInt(1) }))
		}
	}
}

Existence Checks

You can check if a component exists on an item without matching a specific value. In an item predicate (command form), use isPresent:

val hasInstrument = itemPredicate {
	isPresent(ItemComponentTypes.INSTRUMENT)
}
// Result: *[instrument]

Inside a predicates { } / subPredicates { } block, use exists:

predicate("has_instrument") {
	matchTool {
		predicates {
			exists(ItemComponentTypes.INSTRUMENT)
			exists(ItemComponentTypes.DAMAGE)
		}
	}
}

Available Component Matchers

Complete Example: Custom Tool Upgrade System

Here's a practical example showing how to use item predicates to create a tool upgrade system that detects enchanted, damaged tools and replaces them with upgraded versions:

dataPack("tool_upgrades") {
	// Predicate to find diamond swords that need upgrading
	predicate("upgradeable_sword") {
		matchTool {
			items(Items.DIAMOND_SWORD)
			predicates {
				// Must have Sharpness enchantment
				enchantments {
					enchantment(Enchantments.SHARPNESS, level = rangeOrInt(1..4))
				}
				// Must be damaged (durability used)
				damage {
					damage = rangeOrInt(1..1000)
				}
			}
		}
	}

	// Swaps the item id while keeping every component, enchantments included
	val upgradeToNetherite = itemModifier("upgrade_to_netherite") {
		setItem(Items.NETHERITE_SWORD)
	}

	// Function to check player's held item and upgrade it
	function("check_upgrade") {
		// Check if holding an upgradeable sword
		execute {
			ifCondition {
				items(
					self(),
					WEAPON.MAINHAND,
					Items.DIAMOND_SWORD.predicate {
						subPredicates {
							enchantments {
								enchantment(Enchantments.SHARPNESS, level = rangeOrInt(3..4))
							}
						}
					}
				)
			}
			run {
				// Replace with netherite sword keeping enchantments
				items.modify(self(), WEAPON.MAINHAND, upgradeToNetherite)
				tellraw(self(), textComponent("Your sword has been upgraded!", Color.GOLD))
			}
		}
	}

	// Clear specific items from inventory using predicates
	function("clear_broken_tools") {
		// Clear any tool with 1 durability left
		clear(allPlayers(), itemPredicate {
			subPredicates {
				damage {
					durability = rangeOrInt(1)
				}
			}
		})
	}

	// Give reward only if player has specific item combination
	function("check_collection") {
		execute {
			// Check for a goat horn (any variant)
			ifCondition {
				items(
					self(),
					INVENTORY,
					itemPredicate {
						isPresent(ItemComponentTypes.INSTRUMENT)
					}
				)
			}
			// Check for enchanted book with Mending
			ifCondition {
				items(
					self(),
					INVENTORY,
					Items.ENCHANTED_BOOK.predicate {
						subPredicates {
							storedEnchantments {
								enchantment(Enchantments.MENDING)
							}
						}
					}
				)
			}
			run {
				give(self(), Items.NETHER_STAR)
			}
		}
	}
}

Conclusion

Components are a powerful tool for customizing Minecraft objects, and the Kore library makes it easier than ever to work with these components programmatically. Whether you're adding custom attributes, enchantments, or creating complex items with multiple components, Kore provides a robust and intuitive API for enhancing your Minecraft experience.

By following the examples and practices outlined in this article, you can leverage the full potential of components in your Minecraft projects, creating richer and more engaging content for players.

Happy crafting!

See Also

• Predicates - Use components in predicate conditions; see Item Predicates and Item Sub-Predicates for how the matchers on this page plug into a full predicate { } file
• Item Modifiers - Patch components at runtime
• Recipes - Use components in recipe results
• Inventory Manager - Enforce component-rich items in slots

External Resources

• Minecraft Wiki: Data component format - Official component reference