Minecraft CustomModelData Guide: What It Is and How It Works

What is CustomModelData?

Added in Minecraft 1.14, CustomModelData allows pack creators to attach different textures or 3D models to one vanilla item by using numeric identifiers.

• Without tags, an iron sword looks like the normal vanilla sword.
• With CustomModelData: 1, it can look like a katana.
• With CustomModelData: 2, it can render as a 3D chainsaw.

For the server and game mechanics, it is still an iron sword. Only the client-side visual wrapper changes.

How it works

The resource pack uses item model overrides. The base model tells the game to load another model when a specific CustomModelData value is present.

{
  "parent": "item/handheld",
  "textures": { "layer0": "item/iron_sword" },
  "overrides": [
    { "predicate": { "custom_model_data": 1 }, "model": "item/custom_katana" },
    { "predicate": { "custom_model_data": 2 }, "model": "item/custom_chainsaw" }
  ]
}

NBT vs Components

Minecraft 1.20.5 changed item data from old NBT syntax to Data Components. The visual result is similar, but commands changed.

Before 1.20.5

/give @p minecraft:iron_sword{CustomModelData:1} 1

1.20.5 and newer

/give @p minecraft:iron_sword[minecraft:custom_model_data=1] 1

Minecraft Resource Pack Generator accounts for this switch when it shows give commands for your custom items.