← All articles

How to use the custom item builder: custom items without writing the command by hand

A custom item in Minecraft is a vanilla item with a few components added: a name and lore for players, a hidden ID for your logic, and a model hook for the resource pack. The builder writes that /give command from a form, in the syntax of the version you pick, so the quoting and bracket rules stop being your problem.

Checked for versions: Java Edition 1.20 to 26.3.

What a custom item is made of

LayerWhere it livesWho reads it
Base itemThe item ID, such as minecraft:paperThe game: stack size, use animation, durability
Name and lorecustom_name, lorePlayers
Hidden IDcustom_data={item_id:"…"}Your commands, quests, shops and villagers
Model hookitem_model, custom_model_dataThe resource pack

Keeping the layers apart is what makes an item maintainable: you can rename it for a new season without breaking the quest that checks its hidden ID, and change its art without touching either.

Step by step

  1. Command version. Pick 1.21.5 – 26.x, 1.21.4, 1.20.5 – 1.21.3 or before 1.20.5. The form shows only the fields that version can use.
  2. Base item and count. Choose the base for how the item should behave, not only for its default look: paper stacks to 64, a book does not open like a written book, a carrot on a stick can be used.
  3. Hidden item ID. A stable, boring ID such as rp.guild.pass. From 1.20.5 it goes into custom_data; before that the builder writes it as a custom NBT tag.
  4. Name and lore. One lore line per line of the field. The builder adds italic:false, so the name does not look like an anvil rename.
  5. Model. Before 1.21.4 it is one CustomModelData number that the pack's overrides react to. From 1.21.4 item_model names an item definition, cubeinsquare:item/paper/guild_pass reads assets/cubeinsquare/items/item/paper/guild_pass.json, and the float, string, flag and color slots are values that definition can switch on.
  6. Copy and test. The summary shows the length: over 256 characters the command needs a command block instead of chat.

The example, explained

"Load example" fills the form with a guild pass. In the 1.21.5 – 26.x branch it produces:

/give @p minecraft:paper[minecraft:custom_name={text:"Guild archive pass",italic:false},minecraft:lore=[{text:"Stamped for the old city archive.",italic:false}],minecraft:item_model="cubeinsquare:item/paper/guild_pass",minecraft:custom_data={item_id:"rp.guild.pass"},minecraft:custom_model_data={floats:[2047.0f],strings:["guild_pass"],flags:[true],colors:[6138367]}] 1

The same pass before 1.20.5 is a single NBT block:

/give @p minecraft:paper{CustomModelData:2047,display:{Name:'{"text":"Guild archive pass","italic":false}',Lore:['{"text":"Stamped for the old city archive.","italic":false}']},cube_item_id:"rp.guild.pass"} 1

Checking the hidden ID in game

From 1.20.5 item predicates can test custom_data directly. The first line reacts to every player holding the pass in the main hand; the second takes one pass from a player, which is how a door or a shop can "spend" it:

execute as @a if items entity @s weapon.mainhand *[custom_data~{item_id:"rp.guild.pass"}] run say I carry the guild pass
clear @s *[custom_data~{item_id:"rp.guild.pass"}] 1

A renamed vanilla paper fails both checks, because the name is not what is tested.

Common mistakes

FAQ

Do I need a resource pack?

Only for a custom look. Name, lore and the hidden ID work in vanilla without any pack.

What is the color slot for?

An item definition can tint a model layer with custom_model_data colors, so one model can serve several faction colors.

Can villagers accept only the real item?

Yes: put the same custom_data in the trade's price. The villager trade builder and the economy article show how.