Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Chapter 21 — Understanding Data Components

What You’ll Build

Way back in Chapter 1 you learned /give, and you gave yourself plain items: a diamond, a sword, a stack of bread. Since then, little promises have been piling up. In Chapter 5 you saw show_item mentioned but skipped it. In Chapter 17 a loot function called set_components appeared and we said “later.” In Chapter 20 your item modifier used set_components again and we said “later” again.

This is later. This chapter is the keystone of Part VI, and it answers one question: what is an item made of? Once you can answer that, you can build a sword that’s already enchanted, a stick named “Magic Wand,” a bone carrying secret data only your data pack can read, or a glass block you can wear on your head, all from a single /give command, no anvil and no crafting required.

By the end you’ll have a function in your mypack pack called mypack:component_demo that hands you a small collection of custom-built items and, more importantly, you’ll understand the system behind them so the next three chapters are just filling in details. This chapter extends the mypack pack you started in Chapter 9 and uses the test world you’ve used since Chapter 1.

An item is an ID plus components

Here is the big idea, stated as plainly as possible:

“Data components, or simply components, are structured data used to store information and define behavior.”

A data component (also called an item component when it lives on an item) is a named property attached to an item. Each component has an ID (a namespace:path identifier, exactly like the ones you met in Chapter 8) and a value. The component minecraft:custom_name holds an item’s name; minecraft:damage holds how worn-out a tool is; minecraft:enchantments holds its enchantments. An item, in modern Minecraft, is really just an item ID plus a bag of components.

That bag can travel: item components can exist anywhere that an item is stored, such as the player’s inventory, container block entities, and structure files. A named sword keeps its name whether it’s in your hand, in a chest, or saved inside a structure file, because the name isn’t painted on. It’s a component riding along with the item.

Modern Minecraft. If you’ve watched older tutorials, you may have heard about NBT tags and things like {display:{Name:...}} glued onto items. Components are the system that replaced most of that. In fact, data components partially replace the NBT format. When a tutorial tells you to edit an item’s NBT directly, it’s almost always out of date: the modern answer is a component. We’ll keep pointing this out, because the internet is full of the old way.

One honest limit: not everything about an item is a component. Some behavior is welded to the item ID itself, and that behavior cannot be removed from the item, nor applied to a different item that does not have that behavior by default. You can’t turn a dirt block into a sword by bolting components onto it. Components decorate and configure an item; they leave what it fundamentally is untouched.

Every item already has components: defaults

You don’t start from an empty bag. Every item type (item ID) has a set of default data components.

A diamond sword doesn’t need you to tell it that it’s a weapon with a durability bar: those facts come built in. Look at the master list of components and you’ll see each one tagged with an item that has it by default: weapon is listed next to the diamond sword, max_damage (durability) next to the diamond axe, food next to cooked beef, enchantment_glint_override next to the experience bottle. Those are default components: the properties an item type carries automatically.

Here’s the clever part. Item stacks must specify an item ID, which implicitly sets these default components, and default components are not saved on individual item stacks. In plain English: the defaults aren’t written down on each individual sword. The game already knows what a diamond sword’s defaults are, so it doesn’t waste space repeating them. A freshly given diamond sword stores nothing extra: it’s just the ID, and the game fills in the rest.

So what do you store? Only the parts you change. Those implicitly-set default components may be overridden by an individual item stack. To override a component is to specify your own value for it on one particular item, replacing the default. That’s the whole game of this chapter: take an item, override a component or two, and you’ve built something custom.

The bracket syntax: [component=value]

Now the syntax you’ve been waiting for since Chapter 1. When you write an item in a command (like the item argument of /give) you can attach components in square brackets right after the item ID. Here is the exact form:

items are represented in the format item_id[component1=value, component2=value], with component being the namespaced ID of a component, and the value being the value of the component written in SNBT format.

Let’s unpack that, because every piece matters:

  • item_id comes first: the item you’re starting from, e.g. diamond_sword. (Because minecraft: is the default namespace from Chapter 8, you may write diamond_sword or minecraft:diamond_sword; they mean the same thing.)
  • [ ... ]: square brackets hold the list of components.
  • component=value: each entry is a component ID, an = sign, then its value.
  • Commas separate multiple components inside the brackets.
  • The value is written in SNBT, the same string-NBT format you learned in Chapter 12, with its {key:value} compounds, [...] lists, and number suffixes. A component value can be a single number, a quoted string, a compound, or a whole text component, depending on the component.

So this command, a standard custom_name example, gives you a renamed stick:

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

Read it left to right: start with a stick, override its custom_name component, and the value is a text component: yes, exactly the objects you built in Chapter 5, with text, color, and italic. The named sword from the Cursed Blade in Chapter 17 and the upgraded item in Chapter 20 were setting this very same component, just from inside JSON instead of inside brackets.

Two short rules round this out:

“Any components that are not specified are implicitly set to the component’s default value for that item type. If no components are specified, the square brackets can be removed, leaving just the item ID.”

In other words: anything you don’t mention keeps its default, and diamond with no brackets is just a plain diamond. The brackets are optional; they’re only there when you want to change something.

Removing a component with !

Adding and changing components covers two of the three things you can do. The third is removing one, and it has its own punctuation: the exclamation mark, !. Components can be removed by prefixing them with an exclamation mark, like item_id[!component3].

Notice there’s no =value: you’re knocking the component out rather than setting it to anything. The classic example uses the enchanted-look glow that some items have by default:

/give @s experience_bottle[!enchantment_glint_override]

An experience bottle normally shimmers with the enchantment glint. Writing !enchantment_glint_override removes that override component, taking the shimmer away. (You’ll meet a tidier version of this with a different item in the walkthrough below.) The ! form is how you say “I don’t want this component on this item,” and you’ll reach for it whenever an item’s default behavior is in your way.

Under the Hood (skippable). Remember that some behavior is welded to the item ID and can’t be removed. The ! form removes a component override, pushing a component back toward its default or absent state. It does not let you strip out the hardcoded essence of an item. You can remove enchantment_glint_override from an experience bottle; you cannot remove “is a sword” from a sword.

Where it all lives: the components compound

When you’re typing a /give, you see the friendly bracket form. But once that item is sitting in the world, how is it actually stored? Here is the saved shape of any item:

When saved in the NBT format, items are written as a compound with: id (the item’s resource location), count (how many are stacked, default 1), and components, an optional map of additional (non-default) data components.

So an item on disk is a small compound with up to three tags: id, count, and components. That third one, the components compound, is the bag we’ve been talking about, and the word additional is the key. Only the components you overrode get written there. The defaults stay invisible, filled in by the game, exactly as we said earlier.

The bracket form and the components compound are two views of the same thing. When you write stick[custom_name=...] in a command, the game stores it as a stick whose components compound contains one entry, minecraft:custom_name. The brackets are the keyboard-friendly way to write components, and the components compound is how the game saves them.

Try It! Give yourself a renamed item, then read its components back with the read-only tool from Chapter 10 / Chapter 12: hold the item and run /data get entity @s SelectedItem. You’ll see the components compound printed out, holding only the component you changed: proof that defaults aren’t stored on the stack.

Walkthrough: a function that builds custom items

Let’s put the system to work. You’ll add one function to your mypack pack that gives you a handful of items, each showing off one idea from this chapter. Create this file:

mypack/data/mypack/function/component_demo.mcfunction

say Handing out custom-built items...

# 1. ADD a component: a renamed, recolored stick (text component as the value)
give @s stick[custom_name={text:"Magic Wand",color:"light_purple",italic:false}]

# 2. ADD several at once: a wooden sword that's already enchanted
give @s wooden_sword[enchantments={sharpness:3,knockback:2}]

# 3. CHANGE a number: a diamond axe that's nearly worn out (damage = points used up)
give @s diamond_axe[damage=500]

# 4. REMOVE a component with ! : an experience bottle with no glint
give @s experience_bottle[!enchantment_glint_override]

# 5. Hidden data only your pack can read (we'll use this kind of thing later)
give @s iron_sword[custom_data={foo:1}]

Every line here is a /give whose item carries components in brackets, each a standard worked example of one component. Let’s walk through what each one teaches:

  • The stick adds a custom_name component whose value is a text component. The name shows up in light purple and, because we set italic:false, without the slanted “this-was-renamed” styling.
  • The wooden sword adds two enchantments at once by setting the enchantments component to {sharpness:3,knockback:2}: Sharpness III and Knockback II, ready to swing, no enchanting table needed.
  • The diamond axe changes the damage component to 500. To be precise: damage is the number of durability points used up, so a high number means a nearly-broken tool.
  • The experience bottle removes its enchantment_glint_override with !, so it stops shimmering.
  • The iron sword carries a custom_data component, {foo:1}. The custom_data component holds custom data not used by the game: a private notepad your data pack can stamp on an item and check for later. We’re only planting the flag here; Chapter 24 digs into it.

Now wire the function so you can run it. You already have the mypack:load greeting from Chapter 9; this new function is something you trigger on demand, so you just call it by name. Make sure your pack is loaded, then in the chat bar type:

/reload
/function mypack:component_demo

/reload re-reads your data pack (Chapter 8), and /function runs your new file. Five custom items should land in your inventory. Hover over each one to see the name, the enchantments, and (for the items with hidden data) nothing unusual on the tooltip, because custom_data is invisible to players.

Figure (to be captured). inventory after running mypack:component_demo, showing the purple “Magic Wand” stick, the enchanted wooden sword’s glint, and the non-glinting experience bottle side by side

Modern Minecraft. Notice we never opened an anvil, an enchanting table, or a crafting grid. Every one of these items was born customized, straight from a component. That’s the shift this part of the book is about: in modern Minecraft you describe the item you want in data, and the game makes it.

Practice

These extend the demo function — keep working in the same mypack:component_demo file (or copy it to a new one if you’d like to keep the original).

  1. Two names, one item. A lore component adds description lines under an item’s name. Add a line giving yourself a diamond with both a custom_name and a lore line, separating the two components with a comma inside one set of brackets. (Peek at the next chapter’s territory — that’s fine, you’re just practicing the bracket syntax here.)

  2. Glint on, glint off. enchantment_glint_override can be set, not just removed. Give yourself a plain stick that shimmers by setting enchantment_glint_override to true, then on the next line give yourself an experience_bottle that doesn’t shimmer using the ! removal form. Run both and compare.

  3. Read it back. Give yourself any item with two overridden components, then hold it and run /data get entity @s SelectedItem. Find the components compound in the output and confirm it lists exactly the two components you changed, and none of the defaults.

What Can Go Wrong

You typed : instead of = inside the brackets. Components use component=value, with an equals sign. The format is item_id[component1=value]. A colon belongs inside SNBT compounds ({text:"..."}), not between a component and its value. Mixing them up is the single most common component typo.

You forgot the quotes (or added the wrong ones) in the value. The value is SNBT (Chapter 12), so a text string like a name needs to follow SNBT’s rules: strings inside a component value are quoted, e.g. {text:"Magic Wand"}. If the game rejects your command, re-check that every brace { }, bracket [ ], and quote in the value is balanced and matched, just like any JSON you wrote in Part V.

You expected ! to delete the item’s behavior, and it didn’t. Removing a component with ! only removes an override; it can’t strip behavior that’s welded to the item ID. [!enchantment_glint_override] works because the glint is a component; trying to !-remove a sword’s swordness won’t do anything, because that isn’t a component at all. Such behavior cannot be removed from the item.

What You Know Now

You now understand the modern item system from the ground up. An item is an item ID plus a bag of data components: named properties like custom_name, enchantments, and damage. Every item type ships with default components it fills in automatically and doesn’t bother saving; you build custom items by overriding those defaults. In commands you write components in square brackets after the item ID (item_id[component=value, ...], with values in SNBT), and you remove a component by prefixing it with !, as in item_id[!component]. Under the surface, your overrides live in the item’s components compound alongside its id and count. You can give yourself items with any of this baked in from a single /give. Everything in the next three chapters is just which components exist and what their values look like. Chapter 22 covers how items look (names, lore, rarity, models), Chapter 23 covers what they do (food, tools, weapons, armor, durability), and Chapter 24 covers the specialty components, including a proper tour of the custom_data you just planted.