Checked for versions: Java Edition 1.20 to 26.3.
What a custom item is made of
| Layer | Where it lives | Who reads it |
|---|---|---|
| Base item | The item ID, such as minecraft:paper | The game: stack size, use animation, durability |
| Name and lore | custom_name, lore | Players |
| Hidden ID | custom_data={item_id:"…"} | Your commands, quests, shops and villagers |
| Model hook | item_model, custom_model_data | The 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
- 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.
- 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.
- Hidden item ID. A stable, boring ID such as
rp.guild.pass. From 1.20.5 it goes intocustom_data; before that the builder writes it as a custom NBT tag. - 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. - Model. Before 1.21.4 it is one CustomModelData number that the pack's
overridesreact to. From 1.21.4item_modelnames an item definition,cubeinsquare:item/paper/guild_passreadsassets/cubeinsquare/items/item/paper/guild_pass.json, and the float, string, flag and color slots are values that definition can switch on. - 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
custom_nameandloreare text components written in SNBT, the form 1.21.5 introduced.item_modelpoints to the item definition in the pack.custom_datacarries the hidden ID the server can trust.custom_model_datacarries values the item definition can test: a float forrange_dispatch, a string forselect, a flag forcondition, a color for tints.
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
- Changing the hidden ID later. Every quest, shop and trade that checks it stops recognising old items. Rename the visible name instead.
- item_model pointing to a model. From 1.21.4 it names a file in
items/, which then names models inmodels/. Pointing it straight at a model path shows the missing-model texture. - One command for every version. The four branches exist because the syntax really differs; a 1.21.4 command names the item
{"text":…}on 1.21.5.
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.