{{Exclusive|java}}
{{TOC|right}}

To render items there are several different variants of them (like [[Armor]]s with [[Trims]] patterns). The item model definition file lists all the existing variants and links them to their corresponding model. Items can also be composed of several different models at the same time, with "composite" object. The models are then used depending on various states of the item, like [[Data component format|components]] and their values, if they are currently used, their position in the inventory, etc.

The item model definitions are stored as [[JSON]] files in a [[resource pack]] in the {{cd|assets/{{ph|namespace}}/items}} folder.

The item model definition used by an item is based on the component {{cd|minecraft:item_model}}, which references the [[Resource_location|resource location]] of the item model at {{cd|/assets/{{ph|namespace}}/items/{{ph|id}}}} and can be changed through [[commands]].

== JSON format ==
<div class="treeview">
* {{nbt|compound}} Root object
** {{nbt|bool|hand_animation_on_swap}}: Optional. Describing if down-and-up animation should be played in first-person view when item slot is changed (either type, count, components or by swapping the item into the other hand). Default: {{cd|true}}.
** {{nbt|compound|model}}: Set the basic '''Item model''' object.
</div>

=== Item model ===
<div class="treeview">
* {{nbt|compound}} An '''Item model''' object
** {{nbt|string|type}}: One of {{cd|d=or|minecraft:model|minecraft:composite|minecraft:condition|minecraft:select|minecraft:range_dispatch|minecraft:empty|minecraft:bundle/selected_item|minecraft:special}}.
** Additional fields depending on value of type, see [[#Item model types|Item model types]].
</div>

== Item model types ==

=== model ===
Render a plain model from the {{cd|models}} directory.

<div class="treeview">
* {{nbt|compound}} Root '''model''' item model object
** {{nbt|string|type}}: {{cd|minecraft:model}}
** {{nbt|string|model}}: Specifies the path to the model file of the item, in form of a Namespaced ID.
** {{nbt|list|tints}}: Optional. List of '''tint sources''' to apply to the elements of rendered model (first entry applies to {{cd|tintindex}} 0, second one to {{cd|tintindex}} 1, etc.)
*** {{nbt|compound}} A '''tint source''' object
**** {{nbt|string|type}}: One of {{cd|d=or|minecraft:constant|minecraft:dye|minecraft:grass|minecraft:firework|minecraft:potion|minecraft:map_color|minecraft:team|minecraft:custom_model_data}}.
**** Additional fields depending on value of '''tint source type'''.
</div>

==== Tint sources types ====
===== constant =====
Return a constant RGB color.

<div class="treeview">
* {{nbt|compound}} Root '''constant''' tint source object
** {{nbt|string|type}}: {{cd|minecraft:constant}}
** {{nbt|int}}{{nbt|int-array|value}}: A packed integer RGB value (e.g. {{cd|-1}}) or an array of RGB values (e.g. {{cd|[1, 1, 1]}})
</div>

===== dye =====
Return value from {{cd|minecraft:dyed_color}} component or '''default''' if not present

<div class="treeview">
* {{nbt|compound}} Root '''dye''' tint source object
** {{nbt|string|type}}: {{cd|minecraft:dye}}
** {{nbt|int}}{{nbt|int-array|default}}: An RGB value.
</div>

===== grass =====
Return grass color at specific climate parameters, based on {{cd|textures/colormap/grass.png}}

<div class="treeview">
* {{nbt|compound}} Root '''grass''' tint source object
** {{nbt|string|type}}: {{cd|minecraft:grass}}
** {{nbt|float|temperature}}: Positive float between {{cd|0.0}} and {{cd|1.0}}.
** {{nbt|float|downfall}}: Positive float between {{cd|0.0}} and {{cd|1.0}}.
</div>

===== firework =====
Return average of colors from {{cd|minecraft:firework_explosion}} component or '''default''' color if there are none.

<div class="treeview">
* {{nbt|compound}} Root '''firework''' tint source object
** {{nbt|string|type}}: {{cd|minecraft:firework}}
** {{nbt|int}}{{nbt|int-array|default}}: An RGB value.
</div>

===== potion =====
Return color from {{cd|minecraft:potion_contents}} component:
* if component is present:
** ''custom_color'' value, if there is one present in component
** '''default''' color, if effect list is empty
** average of effect colors
* else, '''default''' color

<div class="treeview">
* {{nbt|compound}} Root '''potion''' tint source object
** {{nbt|string|type}}: {{cd|minecraft:potion}}
** {{nbt|int}}{{nbt|int-array|default}}: An RGB value.
</div>

===== map_color =====
Return value from {{cd|minecraft:map_color}} component or '''default''' color if component is not present.

<div class="treeview">
* {{nbt|compound}} Root '''map_color''' tint source object
** {{nbt|string|type}}: {{cd|minecraft:map_color}}
** {{nbt|int}}{{nbt|int-array|default}}: An RGB value.
</div>

===== team =====
Returns the team color of context entity, if any. Else, when there is no context entity, entity is not in a team or team has no color, return '''default'''.

<div class="treeview">
* {{nbt|compound}} Root '''team''' tint source object
** {{nbt|string|type}}: {{cd|minecraft:team}}
** {{nbt|int}}{{nbt|int-array|default}}: An RGB value.
</div>

===== custom_model_data =====
Return value from {{cd|colors}} list in {{cd|minecraft:custom_model_data}} component.

<div class="treeview">
* {{nbt|compound}} Root '''custom_model_data''' tint source object
** {{nbt|string|type}}: {{cd|minecraft:custom_model_data}}
** {{nbt|int|index}}: Optional. Index for field in {{cd|colors}}. Default: {{cd|0}}.
** {{nbt|int}}{{nbt|int-array|default}}: An RGB value.
</div>


=== composite ===
Render multiple sub-models in the same space.

<div class="treeview">
* {{nbt|compound}} Root '''composite''' item model object
** {{nbt|string|type}}: {{cd|minecraft:composite}}
** {{nbt|list|models}}: List of '''Item model''' objects to render.
</div>


=== condition ===

<div class="treeview">
* {{nbt|compound}} Root '''condition''' item model object
** {{nbt|string|type}}: {{cd|minecraft:condition}}
** {{nbt|string|property}}: type of boolean property. One of {{cd|d=or|minecraft:using_item|minecraft:broken|minecraft:damaged|minecraft:has_component|minecraft:fishing_rod/cast|minecraft:bundle/has_selected_item|minecraft:selected|minecraft:carried|minecraft:extended_view|minecraft:keybind_down |minecraft:view_entity|minecraft:custom_model_data}}.
** Additional fields depending on value of '''boolean property type'''.
** {{nbt|compound|on_true}}: The '''Item model''' object when the property is {{cd|true}}.
** {{nbt|compound|on_false}}: The '''Item model''' object when the property is {{cd|false}}.
</div>

==== Boolean property types ====
===== using_item =====
Return {{cd|true}} if player is currently using this item.

No additional fields for this type.

===== broken =====
Return {{cd|true}} if the item is damageable and has only one use remaining before breaking.

No additional fields for this type.

===== damaged =====
Return {{cd|true}} if the item is damageable and has been used at least once.

No additional fields for this type.

===== has_component =====
Return {{cd|true}} if the given component is present on the item.

<div class="treeview">
* additional fields:
** {{nbt|string|component}}: Component name.
** {{nbt|string|ignore_default}}: Optional. If default component value should be handled as "no component". Default: false.
</div>

===== fishing_rod/cast =====
Return {{cd|true}} if there is a fishing bobber attached to currently used fishing rod.

No additional fields for this type.

===== bundle/has_selected_item =====
Return {{cd|true}} if bundle is "open", i.e. it has selected item visible in GUI.

No additional fields for this type.

===== selected =====
Return {{cd|true}} if item is selected on a hotbar.

No additional fields for this type.

===== carried =====
Return {{cd|true}} if item is carried between slots in GUI.

No additional fields for this type.

===== extended_view =====
Return {{cd|true}} if player has requested extended details by holding shift key down. Only works when item is displayed in UI. Note: not a keybind, can't be rebound.

No additional fields for this type.

===== keybind_down =====
Return {{cd|true}} if keybind is currently active.

<div class="treeview">
* additional fields:
** {{nbt|int|keybind}}: [[Controls#Configurable_controls|Keybind ID]], same as value in {{cd|keybind}} text component.
</div>

===== view_entity =====
* When not spectating, return {{cd|true}} if context entity is the local player entity, i.e. the one controlled by client.
* When spectating, return {{cd|true}} if context entity is the ''spectated'' entity.
* If context entity is not present, will return {{cd|false}}.

No additional fields for this type.

===== custom_model_data =====
Return value from {{cd|flags}} list in {{cd|minecraft:custom_model_data}} component.

<div class="treeview">
* additional fields:
** {{nbt|int|index}}: Optional. Index for field in {{cd|flags}}. Default: {{cd|0}}.
</div>


=== select ===
Render an item model based on discrete property.

<div class="treeview">
* {{nbt|compound}} Root '''select''' item model object
** {{nbt|string|type}}: {{cd|minecraft:select}}
** {{nbt|string|property}}: type of property. One of {{cd|d=or|minecraft:main_hand|minecraft:charge_type|minecraft:trim_material|minecraft:block_state|minecraft:display_context|minecraft:local_time|minecraft:context_dimension|minecraft:context_entity_type|minecraft:custom_model_data}}.
** Additional fields depending on value of '''property type'''.
** {{nbt|list|cases}}: List of cases to match.
*** {{nbt|compound}} ''A cases to match''
**** {{nbt|string}}{{nbt|list|when}}: Value to match against property, type depends on property. If a list, will match any value of them.
**** {{nbt|compound|model}}: The '''Item model''' object for this case.
** {{nbt|compound|fallback}}: The '''Item model''' object if no valid entry was found. Optional, but will render a "missing" error model instead.
</div>

==== Property types ====
===== main_hand =====
Return main hand of holding player.

No additional fields for this type.

Values: {{cd|d=or|left|right}}.

===== charge_type =====
Return charge type stored in {{cd|minecraft:charged_projectiles}} component.

No additional fields for this type.

Values:
* {{cd|none}}: If there are no projectiles or component is not present.
* {{cd|rocket}}: If there is at least one firework rocket.
* {{cd|arrow}}: Any other case.

===== trim_material =====
Return value of {{cd|material}} field from {{cd|minecraft:trim}} component, if present.

No additional fields for this type.

Values: Namespaced ID trim material.

===== block_state =====
Return value for some property from {{cd|minecraft:block_state}} component.

<div class="treeview">
* additional fields:
** {{nbt|string|block_state_property}}: String key to select from component.
</div>

Values: Any string.

===== display_context =====
Return context this item is rendered in.

No additional fields for this type.

Values:
* {{cd|none}}
* {{cd|thirdperson_lefthand}}
* {{cd|thirdperson_righthand}}
* {{cd|firstperson_lefthand}}
* {{cd|firstperson_righthand}}
* {{cd|head}}
* {{cd|gui}}
* {{cd|ground}}
* {{cd|fixed}}

Values: Any string.

===== local_time =====
Returns the current time formatted according to a given pattern. The value is updated every second. For full format documentation for locale, time zone and pattern, see ICU (International Components for Unicode) documentation.

<div class="treeview">
* additional fields:
** {{nbt|string|locale}}: .
** {{nbt|string|time_zone}}: Optional. Value describing locale Default {{cd|""}} which means "root" locale (a set of defaults, including English names).
*** {{cd|en_US}}: English language (used for things like week names), formating as in USA. 
*** <code>cs_AU@numbers=thai;calendar=japanese</code>: Czech language, Australian formatting, Thai numerals and Japanese calendar.
** {{nbt|string|time_zone}}: describes format to be used for time formatting.
*** Examples: {{cd|d=,|Europe/Stockholm|GMT+0:45}}
** {{nbt|string|pattern }}: Optional. Describing time. If not present, defaults to timezone set on client.
*** {{cd|yyyy-MM-dd}}: 4-digit year number, then 2-digit month number, then 2-digit day of month number, all zero-padded if needed, separated by {{cd|-}}.
*** {{cd|HH:mm:ss}}: current time (hours, minutes, seconds), 24-hour cycle, all zero-padded to 2 digits of needed, separated by {{cd|:}}.
</div>

Values: Any string.

===== context_dimension =====
Return the ID of the dimension in context, if any.

No additional fields for this type.

Values: Namespaced dimension ID.

===== context_entity_type =====
Return the holding entity type, if present.

No additional fields for this type.

Values: Namespaced entity type ID.

===== custom_model_data =====
Return value from {{cd|strings}} list in {{cd|minecraft:custom_model_data}} component.

<div class="treeview">
* additional fields:
** {{nbt|int|index}}: Optional. Index for field in {{cd|strings}}. Default: {{cd|0}}.
</div>

Values: Any string.

=== range_dispatch ===
Render an item model based on numeric property. Will select last entry with threshold less or equal to property value.

<div class="treeview">
* {{nbt|compound}} Root '''range_dispatch''' item model object
** {{nbt|string|type}}: {{cd|minecraft:range_dispatch}}
** {{nbt|string|property}}: type of numeric property. One of {{cd|d=or|minecraft:bundle/fullness|minecraft:damage|minecraft:count|minecraft:cooldown|minecraft:time|minecraft:compass|minecraft:crossbow/pull, minecraft:use_duration|minecraft:use_cycle|minecraft:custom_model_data}}.
** Additional fields depending on value of '''numeric property type'''.
** {{nbt|float|scale}}: Optional. Factor to multiply property value with. Default: {{cd|1.0}}.
** {{nbt|list|entries}}:
*** {{nbt|compound}} ''An entry object''
**** {{nbt|float|threshold}}: Threshold float value to select this entry.
**** {{nbt|compound|model}}: The '''Item model''' object for this threshold.
** {{nbt|compound|fallback}}: The '''Item model''' object if no valid entry was found. Optional, but will render a "missing" error model instead.
</div>

==== Numeric property types ====
===== bundle/fullness =====
Return weight of {{cd|minecraft:bundle_contents}} component or {{cd|0}} if not present.

No additional fields for this type.

===== damage =====
Return value for {{cd|minecraft:damage}} component or {{cd|0}} if not present.

<div class="treeview">
* additional fields:
** {{nbt|bool|normalize}}: Optional. Default: {{cd|true}}.
*** If {{cd|true}}, return value of damage divided by {{cd|minecraft:max_damage}} component, clamped to {{cd|0.0}} to {{cd|1.0}}.
*** If {{cd|false}}, return raw value of damage, clamped to {{cd|0}} to {{cd|minecraft:max_damage}}.
</div>

===== count =====
Return stack size.

<div class="treeview">
* additional fields:
** {{nbt|bool|normalize}}: Optional. Default: {{cd|true}}.
*** If {{cd|true}}, return count divided by {{cd|minecraft:max_stack_size}} component, clamped to {{cd|0.0}} to {{cd|1.0}}.
*** If {{cd|false}}, return count clamped to {{cd|0}} to {{cd|minecraft:max_stack_size}}.
</div>

===== cooldown =====
Return remaining cooldown for item, scaled betewen {{cd|0.0}} to {{cd|1.0}}.

No additional fields for this type.

===== time =====
Return value of a in-game time, scaled betewen {{cd|0.0}} to {{cd|1.0}}.

<div class="treeview">
* additional fields:
** {{nbt|string|source}}: Time source to return. On of {{cd|d=or|daytime|moon_phase|random}}.
** {{nbt|bool|wobble}}: Optional. If {{cd|true}}, value will oscillate for some time around target before settling. Default: {{cd|true}}.
</div>

===== compass =====
Return an angle, scaled from {{cd|0.0}} to {{cd|1.0}} in x-z plane between holder position and target. If target is not valid (not present, in other dimension or to close to holder position) random value will be returned.

<div class="treeview">
* additional fields:
** {{nbt|string|target}}: One of:
*** {{cd|spawn}}: points at world spawn.
*** {{cd|lodestone}}: points at location stored in {{cd|minecraft:lodestone_tracker}} component.
*** {{cd|recovery}}: points at last player death location.
*** {{cd|none}}: always return an invalid target.
** {{nbt|bool|wobble}}: Optional. If {{cd|true}}, value will oscillate for some time around target before settling. Default: {{cd|true}}.
</div>

===== crossbow/pull =====
Return crossbow-specific use time.

No additional fields for this type.

===== use_duration =====
Return item use ticks.

<div class="treeview">
* additional fields:
** {{nbt|bool|remaining}}: Optional. If {{cd|true}}, returned value will be remaining use ticks, if {{cd|false}} - ticks so far. Default: {{cd|false}}.
</div>

===== use_cycle =====
Return remaining use ticks modulo {{cd|period}}.

<div class="treeview">
* additional fields:
** {{nbt|float|period}}: Optional. Must be positive. Default {{cd|1.0}}.
</div>

===== custom_model_data =====
Return value from {{cd|floats}} list in {{cd|minecraft:custom_model_data}} component or {{cd|0}} if not present.

<div class="treeview">
* additional fields:
** {{nbt|int|index}}: Optional. Index for field in {{cd|floats}}. Default: {{cd|0}}.
</div>


=== empty ===
Does not render anything.

No additional fields for this type.


=== bundle/selected_item ===
Render the selected stack in {{cd|minecraft:bundle_contents}} component, if present, otherwise does nothing.

No additional fields for this type.


=== special ===
Render a special model.

<div class="treeview">
* {{nbt|compound}} Root '''special''' item model object
** {{nbt|string|type}}: {{cd|minecraft:special}}
** {{nbt|compound|model}}
*** {{nbt|string|type}}: type of special model. One of {{cd|d=or|minecraft:bed|minecraft:banner|minecraft:conduit|minecraft:chest|minecraft:decorated_pot|minecraft:head|minecraft:shulker_box|minecraft:shield|minecraft:standing_sign|minecraft:hanging_sign|minecraft:trident}}.
*** Additional fields depending on value of '''special model type'''.
** {{nbt|string|base}}: Namespaced ID of model in {{cd|models}} directory, to providing transformations, particle texture and GUI light.
</div>

==== special model types ====
===== bed =====
Render a whole bed.

<div class="treeview">
* {{nbt|compound}} Root '''bed''' special type object
** {{nbt|string|type}}: {{cd|minecraft:bed}}
** {{nbt|string|texture}}: Namespaced ID for the texture, without {{cd|textures/entity/bed/}} prefix and {{cd|.png}} suffix.
</div>

===== banner =====
Render a banner with patterns from {{cd|minecraft:banner_patterns}} component.

<div class="treeview">
* {{nbt|compound}} Root '''banner''' special type object
** {{nbt|string|type}}: {{cd|minecraft:banner}}
** {{nbt|string|color}}: Color of the banner base, one of 16 predefined colors.
</div>

===== conduit =====
Render conduit.

No additional fields for this type.

===== chest =====
Render a single chest.

<div class="treeview">
* {{nbt|compound}} Root '''chest''' special type object
** {{nbt|string|type}}: {{cd|minecraft:chest}}
** {{nbt|string|texture}}: Namespaced ID for the texture, without {{cd|textures/entity/chest/}} prefix and {{cd|.png}} suffix.
** {{nbt|float|openness}}: Optional. Render the chest in the specified open state, between {{cd|0.0}} (fully closed) to {{cd|1.0}} (fully open). Default: {{cd|0.0}}.
</div>

===== decorated_pot =====
Render a decorated pot. Uses values from {{cd|minecraft:pot_decorations}} component.

No additional fields for this type.

===== head =====
Render a head. Uses profile from {{cd|minecraft:profile}} component when applicable.

<div class="treeview">
* {{nbt|compound}} Root '''head''' special type object
** {{nbt|string|type}}: {{cd|minecraft:head}}
** {{nbt|string|kind}}: One of {{cd|d=or|skeleton|wither_skeleton|player|zombie|creeper|piglin|dragon}}.
** {{nbt|string|texture}}: Optional. Namespaced ID for the texture, without {{cd|textures/entity/}} prefix and {{cd|.png}} suffix.
*** If absent, default texture will be used, depending on {{cd|kind}} field. Additionally, if present, {{cd|minecraft:profile}} component is ignored.
** {{nbt|float|animation}}: Optional. Controlling head animation if available for this {{cd|kind}} of head (like Piglin ears or Ender Dragon jaw). Default: {{cd|0.0}}.
*** The {{cd|dragon}} animation is {{cd|10}} units long. Mouth fully closed at {{cd|-2.5}} and fully open at {{cd|2.5}} <ref name="head_animation">[https://www.youtube.com/watch?v=z6rrHbFp5nw&t=67 News in Resource Pack Version 46 (1.21.4 Pre-Release 1)]</ref>.
*** The {{cd|piglin}} ears wiggle out of sync. The left ear period is {{cd|8.3333}} and right ear period is {{cd|10.0}}.<ref name="head_animation"/>
</div>

===== shulker_box =====
Render a shulker box.

<div class="treeview">
* {{nbt|compound}} Root '''shulker_box''' special type object
** {{nbt|string|type}}: {{cd|minecraft:shulker_box}}
** {{nbt|string|name}}: Namespaced ID for the texture, without {{cd|textures/entity/shulker/}} prefix and {{cd|.png}} suffix
** {{nbt|float|openness}}: Optional. Render the shulker box in the specified open state, between {{cd|0.0}} (fully closed) to {{cd|1.0}} (fully open). Default: {{cd|0.0}}.
** {{nbt|string|orientation}}: Optional. Orientation for rendering. Default: up.
</div>

===== shield =====
Render a shield. Uses patterns from {{cd|minecraft:banner_patterns}} component and color from {{cd|minecraft:base_color}} component.

No additional fields for this type.

===== standing_sign =====
Renders a standing sign.

<div class="treeview">
* {{nbt|compound}} Root '''standing_sign''' special type object
** {{nbt|string|type}}: {{cd|minecraft:standing_sign}}
** {{nbt|string|wood_type}}: One of {{cd|d=or|oak|spruce|birch|acacia|cherry|jungle|dark_oak|pale_oak|mangrove|bamboo|crimson|warped}}.
** {{nbt|string|texture}}: Optional. Namespaced ID for the texture, without {{cd|textures/entity/}} prefix and {{cd|.png}} suffix. If present, {{cd|wood_type}} field is ignored.
</div>

===== hanging_sign =====
Renders a hanging sign.

<div class="treeview">
* {{nbt|compound}} Root '''hanging_sign''' special type object
** {{nbt|string|type}}: {{cd|minecraft:hanging_sign}}
** {{nbt|string|wood_type}}: One of {{cd|d=or|oak|spruce|birch|acacia|cherry|jungle|dark_oak|pale_oak|mangrove|bamboo|crimson|warped}}.
** {{nbt|string|texture}}: Optional. Namespaced ID for the texture, without {{cd|textures/entity/}} prefix and {{cd|.png}} suffix. If present, {{cd|wood_type}} field is ignored.
</div>

===== trident =====
Render a trident.

No additional fields for this type.

== History ==
{{HistoryTable
|{{HistoryLine|java}}
|{{HistoryLine||1.21.4|dev=24w45a|Added Item model definitions.}}
|{{HistoryLine|||dev=24w46a|Added {{cd|holder_type}} property types.
|Added {{cd|keybind_down}} boolean property types.
|Added {{cd|standing_sign}} and {{cd|hanging_sign}} special model types.
|Added {{cd|texture}} field to {{cd|head}} special model types.
|Removed {{cd|xmas}} boolean property, replaced by {{cd|local_time}} property model types.
|Removed {{cd|shift_down}} boolean property, replaced by {{cd|extended_view}} boolean property.
}}
|{{HistoryLine|||dev=Pre-Release 1|Add {{cd|hand_animation_on_swap}} field to items model definition.
|Added {{cd|empty}} item model type.
|Added {{cd|team}} tint sources type.
|Added {{cd|context_dimension}} property type.
|Added {{cd|view_entity}} boolean property type.
|Renamed {{cd|holder_type}} to {{cd|context_entity_type}} property type.
|Removed {{cd|natural_only}} field and added {{cd|source}} field in {{cd|time}} numeric property type.
|Added {{cd|none}} to posible values for {{cd|target}} field  in {{cd|compass}} numeric property type.
|Added {{cd|animation}} field to {{cd|head}} special model type.
}}
}}

== Navigation ==
{{Navbox Java Edition technical|resourcepack}}

[[de:Gegenstandsmodelldefinition]]
