Chapter 22 — Display Components

What You’ll Build

In this chapter you’ll make a single item look legendary. By the end you’ll have one command that hands you a sword with a glowing purple name, two lines of golden description text underneath it, an “epic” rarity color, and a shimmering enchantment glint, even though the sword isn’t actually enchanted. You’ll write that command into a function in the mypack pack you’ve been building, run it in your test world, and be able to read every piece of it. None of these changes touch what the sword does, only how it looks and reads. That’s the whole idea of this chapter.

Figure (to be captured). the finished “legendary” sword held in hand, tooltip showing the purple name, two gold lore lines, and the enchantment glint

Concepts

Display components vs. functional components

In Chapter 21 you learned that every item carries data components: labelled pieces of data you write inside square brackets after the item’s id, like item_id[component=value]. Some components change what an item does: how much food it restores, what it can break, whether it can be eaten. Others change only how the item looks and reads: its name, the description lines in its tooltip, its color, whether it sparkles. This chapter is about that second group. We’ll call them display components: components whose job is appearance, not behavior. (That’s our grouping name for them; each one is a normal data component from the same list you met in Chapter 21.)

Data components are structured data used to store information and define behavior, and not all characteristics of an item are covered by them. The display components decorate an item without redefining it.

Two names: `custom_name` and `item_name`

Here’s a wrinkle that confuses a lot of people: an item can have two different names, and they are separate components.

minecraft:item_name is the item’s default base name, written as a text component, present on all items by default. It cannot be erased using an anvil, and it is not italicized. Think of it as the name the item ships with, the one a custom item type would use so it reads as “Ruby” instead of “Diamond” everywhere.
minecraft:custom_name is the player-assigned name of this item, block, or entity, typically assigned with an anvil or a name tag. It has the highest priority to display as the item’s name, and appears italic unless overridden by the text component format.

So if an item has both, the custom_name wins on screen. The everyday way to picture it: item_name is the printed label on the box, and custom_name is the sticker you slapped on top.

Modern Minecraft. In older versions, an item’s name was a single NBT field (display.Name). Now there are two separate components with two different jobs. If a tutorial tells you to edit display.Name, it’s out of date. You want custom_name (or item_name) as a component, exactly like the recipes and loot you’ve already been writing.

A tooltip is the little box that pops up when you hover over an item in your inventory. From top to bottom it can show: the item’s name, then any lore lines you’ve added, then automatic lines the game adds for components that have something to say (enchantments, durability, and so on). The display components in this chapter let you write the name and lore, color the name, and even hide parts of the tooltip you don’t want shown.

Walkthrough: building the legendary sword

We’ll add the components one at a time, see what each does, then combine them into the final command. Every command below goes inside a function file (no leading /), just like every command since Chapter 9. We’ll collect them into one function at the end.

Step 1 — Name it with `custom_name`

A custom_name value is a text component, the same {text:..., color:..., ...} object you learned in Chapter 5. Here’s an example (it gives a stick, but the shape is what matters):

give @s stick[custom_name={text:"Magic Wand",color:"light_purple",italic:false}]

That gives “a stick named ‘Magic Wand’ in light purple non-italicized text.” Two things to notice. First, the value is a text-component object, so all your Chapter 5 styling fields work here: color, bold, italic, and the rest. Second (and this catches everyone), the example sets italic:false on purpose. A custom_name appears italic unless overridden by the text component format: Minecraft italicizes custom names by default, so adding italic:false turns that off and the name reads upright. We’ll do the same on our sword.

Step 2 — Describe it with `lore`

Lore is the description text shown below the name in the tooltip. The minecraft:lore component is a list, and each entry in the list is a text component representing one line. The list has a maximum of 256 lines, far more than you’ll ever need.

A one-line example:

give @p stick[lore=[{text:"This Stick is very sticky."}]]

And a two-line example, which is what we want for the sword:

give @p emerald[lore=[{text:"A shiny Emerald!",italic:false,color:"gold"}, {text:"Maybe share it with a friend?",italic:false,color:"yellow"}]]

This gives an emerald that has 2 lines of lore in its tooltip. The first line has a golden color, and the second has a yellow color, and both lines have had their italics removed. Notice the pattern: lore is an array [ ... ], and each element {text:"..."} is one line. To add a line, add another text component to the list.

Try It! Lore lines are full text components, so a line can be obfuscated, colored with a #hex value, or even split into pieces with an extra list (Chapter 5). Try a line that’s {text:"???",obfuscated:true,color:"dark_gray"} for a “cursed, unreadable” effect.

Step 3 — Tier it with `rarity`

The minecraft:rarity component sets how special the game treats the item, which shows up as the default color of its name. Its value is one of four strings: rarity can be common, uncommon, rare, or epic. If this component does not exist on the item, then common is used.

give @p iron_sword[rarity=epic]

That “gives an iron sword with a light purple name.” So epic paints the name light purple, which is the color we want for something legendary.

Under the Hood (skippable). Rarity sets the default name color, but custom_name carries its own color field, and that wins. On our sword we set both rarity=epic and a purple custom_name color, so they agree. If you ever set rarity=epic but gave the custom_name a different color, the custom_name color would be what you actually see. The rarity color only shows through when the name itself doesn’t specify one.

Step 4 — Make it shine with `enchantment_glint_override`

The shimmering “enchanted” sparkle on an item is called the glint. Normally only enchanted items have it. The minecraft:enchantment_glint_override component lets you force that decision either way. Its value is a simple boolean (true or false). When true, the item displays a glint, even without enchantments; when false, the item does not display a glint, even with enchantments.

This example removes a glint:

give @s experience_bottle[enchantment_glint_override=false]

That “gives an experience bottle without the visual enchantment glint, which is otherwise applied by default.” For our legendary sword we want the opposite, a glint with no real enchantment, so we’ll use enchantment_glint_override=true.

Step 5 — Assemble the legendary `/give`

Now we stack all four components into one command, separated by commas inside a single pair of square brackets. Put this in a new function file:

mypack/data/mypack/function/legendary_blade.mcfunction

give @s diamond_sword[custom_name={text:"Stormcaller",color:"light_purple",italic:false},lore=[{text:"Forged in the first storm.",italic:false,color:"gold"}, {text:"Wielded by none who returned.",italic:false,color:"yellow"}],rarity=epic,enchantment_glint_override=true]

Reading it left to right: it gives you a diamond_sword whose custom_name is “Stormcaller” in upright light-purple text; whose lore is two lines, gold then yellow, both upright; whose rarity is epic; and whose glint is forced on. Four display components, one item, no change to how the sword fights.

Wire it into the pack the same way as every function, but this one you’ll trigger by hand rather than on load, so it doesn’t need a tag. In your test world, after /reload, run it from chat:

/function mypack:legendary_blade

You should be holding Stormcaller, glinting and purple, with its two gold-and-yellow lore lines.

Figure (to be captured). chat showing /function mypack:legendary_blade run, and the resulting tooltip

Under the Hood (skippable). You could have typed this whole give straight into chat with a leading /. Putting it in a function instead means you can hand out the exact same legendary blade again and again (from an advancement reward, a loot table, or another function) without retyping a long bracket string. That’s the “think in data packs” habit: build the thing once, call it by name.

The pointer components

The remaining display components don’t carry their own appearance. They point at something else. Three of them point at assets you’ll build later in a resource pack (Chapter 29), so here we’ll learn what they are and the exact value they take, and leave the asset-building for Part VIII.

`item_model` — swap the item’s whole model

minecraft:item_model replaces what the item looks like by pointing at a model definition. Its value is a string, a resource location. It’s the resource location of the item, which references the item model definition file in a resource pack. This example reuses a vanilla model:

give @s netherite_sword[item_model="minecraft:diamond_sword"]

That “gives a netherite sword that looks like a diamond sword.” When you make your own models in Chapter 29, you’ll point item_model at one of yours (like item_model="mypack:ruby") and the item will render as that model. Be aware that referencing nonexistent models will cause the missing model to be used, so the pointer only works once the asset exists.

`custom_model_data` — data for a model to read

minecraft:custom_model_data is the classic hook for custom models. Unlike item_model, it doesn’t name a model; it carries data that a model definition reads to decide which variant to show or how to tint it. Its value is a compound holding up to four lists:

floats: a list of floats, for the range_dispatch model type.
flags: a byte-array of booleans, for the condition model type.
strings: a list of strings, for the select model type.
colors: a list of RGB values, for the model model type’s tints.

For example:

give @s bone[custom_model_data={floats:[4.0, 5.6, 99.1],strings:["foo:bar"],colors:[8323327, [0.5,0,1], 0x7F00FF]}]

Modern Minecraft. This is a real trap for old tutorials. custom_model_data used to be a single number (custom_model_data:3). It is now a compound with floats, flags, strings, and colors lists, as shown above. If a video tells you to set custom_model_data to one integer, it’s from before the change — use the compound shape shown above. We’ll actually wire it up to a model in Chapter 29; for now, know what its data looks like.

minecraft:tooltip_style changes the background and frame of the tooltip box itself. Its value is a string resource location pointing at custom sprite textures in a resource pack. It references textures for a _background and a _frame sprite, and invalid specifications will use the missing texture. Like item_model, the pointer is written here but the artwork is a Chapter 29 job.

minecraft:tooltip_display lets you suppress tooltip lines. It allows the tooltips provided specifically by any given item component to be suppressed. Its value is a compound with two fields:

hide_tooltip: a boolean. If true, the item has no tooltip when hovered at all.
hidden_components: a list of component resource locations; each one’s tooltip line is hidden.

To hide one component’s line while keeping the rest:

give @p diamond_sword[tooltip_display={hidden_components:["minecraft:enchantments"]},enchantments={sharpness:1}]

That “gives a diamond sword that is enchanted with Sharpness I, but doesn’t show the enchantments in the tooltip.” And to hide the whole tooltip:

give @p diamond_sword[tooltip_display={hide_tooltip:1b}]

That gives a sword “that when hovered, it shows no tooltip at all.” (The 1b is the SNBT way of writing the boolean true, from Chapter 12: a b-suffixed 1.)

`item_name` in practice

We met item_name in the concepts section as the default base name. You set it the same way as custom_name, with a text component. This example uses the plain-string form of a text component:

give @s diamond[minecraft:item_name="Dirt"]

That “gives a diamond that is named ‘Dirt’.” Because a bare string "Dirt" is itself a valid text component (Chapter 5), you can write the name with or without the full {text:...} object. Reach for item_name when you want a base name that isn’t italic and that a player can’t rename away in an anvil, and reach for custom_name (as we did on the sword) for the top-priority, player-style name.

Practice

These extend the legendary blade and the components above. Put each in a function or run it from chat in your test world.

Arm the whole team. Change the give in legendary_blade.mcfunction to target every player instead of just yourself, by swapping @s for @a (Chapter 3). Reload and run it, and everyone online gets a Stormcaller.
A quiet enchantment. Give yourself an enchanted item whose enchantment is hidden from the tooltip and whose glint is turned off, so it looks completely ordinary:
```
give @s iron_sword[enchantments={sharpness:2},tooltip_display={hidden_components:["minecraft:enchantments"]},enchantment_glint_override=false]
```
Confirm in-game that it has no glint and no enchantment line, yet still hits harder.
A renameable label. Give a diamond an item_name of your choice (a base name) and also a custom_name (the sticker on top). Hover it: you should see the custom_name, because it has the highest priority. Then imagine renaming it in an anvil: the custom_name would change, but the item_name underneath would not.

What Can Go Wrong

Your custom name comes out italic. You forgot italic:false. A custom_name appears italic unless overridden: Minecraft slants custom names by default. Add italic:false inside the text-component value (as in every example above) to make it upright.
rarity does nothing visible. Two common causes. Either you set a custom_name whose own color overrides the rarity color (the name color wins — see the Under the Hood box in Step 3), or you misspelled the value. Rarity must be exactly common, uncommon, rare, or epic; anything else isn’t a valid value.
The glint won’t turn off on an enchanted item. Make sure you used enchantment_glint_override=false, not true. false “does not display a glint, even with enchantments”; true forces one on. The two are opposites, and it’s easy to type the wrong one.

What You Know Now

You can change how an item looks and reads without changing what it does. You can name it two different ways, custom_name (top priority, player-style, italic-by-default) and item_name (the un-erasable base name); describe it with lore lines; color its name with rarity; force or remove the enchantment_glint_override shimmer; hide tooltip lines (or the whole tooltip) with tooltip_display; and write the pointers (item_model, tooltip_style, and custom_model_data) that hook an item up to custom artwork you’ll build in Chapter 29. Most of all, you can read a long bracketed /give and say exactly what each component does, the skill the rest of Part VI builds on.

Minecraft Data Packs: A Complete Guide