Items model definition

This article is about files that link to raw item models and configure their rendering. For raw models that directly define the appearance and shape of items, see Model § Item_models.
This feature is exclusive to Java Edition.
 

Items models[1] are processor files used by the game to define and select which model to use for rendering items, depending of various criteria such as components, item interactions, their position in the inventory, or numerous other in-game values.

Items models are stored as JSON files in a resource pack in the assets/<namespace>/items folder.

Which items model is used by an item is based on the component minecraft:item_model, which references the resource location of the items model at /assets/<namespace>/items/<id>, and can be changed through commands.

JSON format

  • [NBT Compound / JSON Object] Root object
    • [Boolean] hand_animation_on_swap: Optional. Describes if a down-and-up animation should be played in first-person view when the item slot is changed (either type, count, components or by swapping the item into the other hand). Default: true.
    • [Boolean] oversized_in_gui: Optional. Describes if the items model is allowed to render bigger than the item slot. If false the render will be clipped to the item slot size. Default: false.
      • The ability of items being rendered outside of their slots is not considered officially supported by Mojang. It's a backward compatibility until an official functionality is developed at some point in the future.[2]
    • [NBT Compound / JSON Object] model: Set the basic Items model object.

Items model

  • [NBT Compound / JSON Object] An Items model object
    • [String] type: One of minecraft:model, minecraft:composite, minecraft:condition, minecraft:select, minecraft:range_dispatch, minecraft:empty, minecraft:bundle/selected_item or minecraft:special.
    • Additional fields depending on value of type, see § Items model types.

Items model types

model

Render a plain model from the models directory.

  • [NBT Compound / JSON Object] Root model items model object
    • [String] type: minecraft:model
    • [String] model: Specifies the path to the model file of the item, in form of a Namespaced ID.
    • [NBT List / JSON Array] tints: Optional. List of tint sources to apply to the elements of rendered model (first entry applies to tintindex 0, second one to tintindex 1, etc.)
      • [NBT Compound / JSON Object] A tint source object
        • [String] type: One of minecraft:constant, minecraft:dye, minecraft:firework, minecraft:grass, minecraft:map_color, minecraft:potion, minecraft:team or minecraft:custom_model_data.
        • Additional fields depending on value of tint source type.
        • Disclaimer: The tint sources will work only if the target model is herited from builtin/generated and have no elements, else the item model will be render normaly without apply the tint color.

Tint sources types

constant

Return a constant RGB color.

  • [NBT Compound / JSON Object] Root constant tint source object
    • [String] type: minecraft:constant
    • [Int][NBT List / JSON Array] value: A packed integer RGB value (e.g. -1) or an array of decimal RGB values, each between 0.0 and 1.0 (e.g. [1, 1, 1])
dye

Return value from minecraft:dyed_color component or default if not present

  • [NBT Compound / JSON Object] Root dye tint source object
    • [String] type: minecraft:dye
    • [Int][NBT List / JSON Array] default: An RGB value.
firework

Return average of colors from minecraft:firework_explosion component or default color if there are none.

  • [NBT Compound / JSON Object] Root firework tint source object
    • [String] type: minecraft:firework
    • [Int][NBT List / JSON Array] default: An RGB value.
grass

Return grass color at specific climate parameters, based on textures/colormap/grass.png

  • [NBT Compound / JSON Object] Root grass tint source object
    • [String] type: minecraft:grass
    • [Float] temperature: Positive float between 0.0 and 1.0.
    • [Float] downfall: Positive float between 0.0 and 1.0.
map_color

Return value from minecraft:map_color component or default color if component is not present.

  • [NBT Compound / JSON Object] Root map_color tint source object
    • [String] type: minecraft:map_color
    • [Int][NBT List / JSON Array] default: An RGB value.
potion

Return color from 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
  • [NBT Compound / JSON Object] Root potion tint source object
    • [String] type: minecraft:potion
    • [Int][NBT List / JSON Array] default: An RGB value.
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.

  • [NBT Compound / JSON Object] Root team tint source object
    • [String] type: minecraft:team
    • [Int][NBT List / JSON Array] default: An RGB value.
custom_model_data

Return value from colors list in minecraft:custom_model_data component.

  • [NBT Compound / JSON Object] Root custom_model_data tint source object
    • [String] type: minecraft:custom_model_data
    • [Int] index: Optional. Index for field in colors. Default: 0.
    • [Int][NBT List / JSON Array] default: An RGB value.

composite

Render multiple sub-models in the same space.

  • [NBT Compound / JSON Object] Root composite items model object
    • [String] type: minecraft:composite
    • [NBT List / JSON Array] models: List of Items model objects to render.


condition

  • [NBT Compound / JSON Object] Root condition items model object
    • [String] type: minecraft:condition
    • [String] property: type of boolean property. One of minecraft:broken, minecraft:bundle/has_selected_item, minecraft:carried, minecraft:component, minecraft:damaged, minecraft:extended_view, minecraft:fishing_rod/cast, minecraft:has_component, minecraft:keybind_down, minecraft:selected, minecraft:using_item, minecraft:view_entity or minecraft:custom_model_data.
    • Additional fields depending on value of boolean property type.
    • [NBT Compound / JSON Object] on_true: The Items model object when the property is true.
    • [NBT Compound / JSON Object] on_false: The Items model object when the property is false.

Boolean property types

broken

Return true if the item is damageable and has only one use remaining before breaking.

No additional fields for this type.

bundle/has_selected_item

Return true if bundle is "open", i.e. it has selected item visible in GUI.

No additional fields for this type.

carried

Return true if item is carried between slots in GUI.

No additional fields for this type.

component

Uses component item sub predicates to match item components.

  • additional fields:
    • [String] predicate: Type of component predicate (member of minecraft:data_component_predicate_type registry).
    • [String] value: Value to match.
damaged

Return true if the item is damageable and has been used at least once.

No additional fields for this type.

extended_view

Return 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.

fishing_rod/cast

Return true if there is a fishing bobber attached to currently used fishing rod.

No additional fields for this type.

has_component

Return true if the given component is present on the item.

  • additional fields:
    • [String] component: Component name.
    • [Boolean] ignore_default: Optional. If default component value should be handled as "no component". Default: false.
keybind_down

Return true if keybind is currently active.

  • additional fields:
    • [String] keybind: Keybind ID, same as value in keybind text component.
selected

Return true if item is selected on a hotbar.

No additional fields for this type.

using_item

Return true if player is currently using this item.

No additional fields for this type.

view_entity
  • When not spectating, return true if context entity is the local player entity, i.e. the one controlled by client.
  • When spectating, return true if context entity is the spectated entity.
  • If context entity is not present, will return false.

No additional fields for this type.

custom_model_data

Return value from flags list in minecraft:custom_model_data component.

  • additional fields:
    • [Int] index: Optional. Index for field in flags. Default: 0.


select

Render an items model based on discrete property.

  • [NBT Compound / JSON Object] Root select items model object
    • [String] type: minecraft:select
    • [String] property: type of property. One of minecraft:block_state, minecraft:charge_type, minecraft:component, minecraft:context_dimension, minecraft:context_entity_type, minecraft:display_context, minecraft:local_time, minecraft:main_hand, minecraft:trim_material or minecraft:custom_model_data.
    • Additional fields depending on value of property type.
    • [NBT List / JSON Array] cases: List of cases to match.
      • [NBT Compound / JSON Object] A case to match
        • [String][NBT List / JSON Array] when: Value to match against property, type depends on property. If a list, will match any value of them.
        • [NBT Compound / JSON Object] model: The Items model object for this case.
    • [NBT Compound / JSON Object] fallback: The Items model object if no valid entry was found. Optional, but will render a "missing" error model if not present.

Property types

block_state

Return value for some property from minecraft:block_state component.

  • additional fields:
    • [String] block_state_property: String key to select from component.

Values: Any string.

charge_type

Return charge type stored in minecraft:charged_projectiles component.

No additional fields for this type.

Values:

  • none: If there are no projectiles or component is not present.
  • rocket: If there is at least one firework rocket.
  • arrow: Any other case.
component

Return value from a component. If the selected value comes from a registry and the current datapacks does not provide it, the entry will be silently ignored.

  • additional fields:
    • [String] component: Namespaced ID of the component type.

Values: Depends on the target component type.

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.

display_context

Return context this item is rendered in.

No additional fields for this type.

Values:

  • none
  • thirdperson_lefthand
  • thirdperson_righthand
  • firstperson_lefthand
  • firstperson_righthand
  • head
  • gui
  • ground
  • fixed
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.

  • additional fields:
    • [String] locale: Optional. Value describing locale. Default "" which means "root" locale (a set of defaults, including English names).
      • en_US: English language (used for things like week names), formating as in USA.
      • cs_AU@numbers=thai;calendar=japanese: Czech language, Australian formatting, Thai numerals and Japanese calendar.
    • [String] time_zone: Optional. Value describing time zone. If not present, defaults to timezone set on client.
      • Examples: Europe/Stockholm, GMT+0:45
    • [String] pattern: Describes format to be used for time formatting
      • 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 -.
      • HH:mm:ss: current time (hours, minutes, seconds), 24-hour cycle, all zero-padded to 2 digits of needed, separated by :.

Values: Any string.

main_hand

Return main hand of holding player.

No additional fields for this type.

Values: left or right.

trim_material

Return value of material field from minecraft:trim component, if present.

No additional fields for this type.

Values: Namespaced ID trim material.

custom_model_data

Return value from strings list in minecraft:custom_model_data component.

  • additional fields:
    • [Int] index: Optional. Index for field in strings. Default: 0.

Values: Any string.

range_dispatch

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

  • [NBT Compound / JSON Object] Root range_dispatch items model object
    • [String] type: minecraft:range_dispatch
    • [String] property: type of numeric property. One of minecraft:bundle/fullness, minecraft:compass, minecraft:cooldown, minecraft:count, minecraft:crossbow/pull, minecraft:damage, minecraft:time, minecraft:use_cycle, minecraft:use_duration or minecraft:custom_model_data.
    • Additional fields depending on value of numeric property type.
    • [Float] scale: Optional. Factor to multiply property value with. Default: 1.0.
    • [NBT List / JSON Array] entries:
      • [NBT Compound / JSON Object] An entry object
        • [Float] threshold: Threshold float value to select this entry.
        • [NBT Compound / JSON Object] model: The Items model object for this threshold.
    • [NBT Compound / JSON Object] fallback: The Items model object if no valid entry was found. Optional, but will render a "missing" error model instead.

Numeric property types

bundle/fullness

Return weight of minecraft:bundle_contents component or 0 if not present.

No additional fields for this type.

compass

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

  • additional fields:
    • [String] target: One of:
      • spawn: points at world spawn.
      • lodestone: points at location stored in minecraft:lodestone_tracker component.
      • recovery: points at last player death location.
      • none: always return an invalid target.
    • [Boolean] wobble: Optional. If true, value will oscillate for some time around target before settling. Default: true.
cooldown

Return remaining cooldown for item, scaled between 0.0 to 1.0.

No additional fields for this type.

count

Return stack size.

  • additional fields:
    • [Boolean] normalize: Optional. Default: true.
      • If true, return count divided by minecraft:max_stack_size component, clamped to 0.0 to 1.0.
      • If false, return count clamped to 0 to minecraft:max_stack_size.
crossbow/pull

Return crossbow-specific use time.

No additional fields for this type.

damage

Return value for minecraft:damage component or 0 if not present.

  • additional fields:
    • [Boolean] normalize: Optional. Default: true.
      • If true, return value of damage divided by minecraft:max_damage component, clamped to 0.0 to 1.0.
      • If false, return raw value of damage, clamped to 0 to minecraft:max_damage.
time

Return value of a in-game time, scaled between 0.0 to 1.0.

  • additional fields:
    • [String] source: Time source to return. One of daytime, moon_phase or random.
    • [Boolean] wobble: Optional. If true, value will oscillate for some time around target before settling. Default: true.
use_cycle

Return remaining use ticks modulo period.

  • additional fields:
    • [Float] period: Optional. Must be positive. Default 1.0.
use_duration

Return item use ticks.

  • additional fields:
    • [Boolean] remaining: Optional. If true, returned value will be remaining use ticks, if false - ticks so far. Default: false.
custom_model_data

Return value from floats list in minecraft:custom_model_data component or 0 if not present.

  • additional fields:
    • [Int] index: Optional. Index for field in floats. Default: 0.

empty

Does not render anything.

No additional fields for this type.


bundle/selected_item

Render the selected stack in minecraft:bundle_contents component, if present, otherwise does nothing.

No additional fields for this type.


special

Render a special model.

  • [NBT Compound / JSON Object] Root special items model object
    • [String] type: minecraft:special
    • [NBT Compound / JSON Object] model
      • [String] type: type of special model. One of minecraft:banner, minecraft:bed, minecraft:chest, minecraft:conduit, minecraft:decorated_pot, minecraft:head, minecraft:player_head, minecraft:shield, minecraft:shulker_box, minecraft:standing_sign, minecraft:hanging_sign or minecraft:trident.
      • Additional fields depending on value of special model type.
    • [String] base: Namespaced ID of model in models directory, to providing transformations, particle texture and GUI light.

special model types

Render a banner with patterns from minecraft:banner_patterns component.

  • [NBT Compound / JSON Object] Root banner special type object
    • [String] type: minecraft:banner
    • [String] color: Color of the banner base, one of 16 predefined colors.
bed

Render a whole bed.

  • [NBT Compound / JSON Object] Root bed special type object
    • [String] type: minecraft:bed
    • [String] texture: Namespaced ID for the texture in the beds texture atlas without the .png suffix. By default this includes textures in textures/entity/bed/, without the prefix.
chest

Render a single chest.

  • [NBT Compound / JSON Object] Root chest special type object
    • [String] type: minecraft:chest
    • [String] texture: Namespaced ID for the texture in the chests texture atlas without the .png suffix. By default this includes textures in textures/entity/chest/, without the prefix.
    • [Float] openness: Optional. Render the chest in the specified open state, between 0.0 (fully closed) to 1.0 (fully open). Default: 0.0.
conduit

Render conduit.

No additional fields for this type.

decorated_pot

Render a decorated pot. Uses values from minecraft:pot_decorations component.

No additional fields for this type.

head

Render a head.

  • [NBT Compound / JSON Object] Root head special type object
    • [String] type: minecraft:head
    • [String] kind: One of skeleton, wither_skeleton, player, zombie, creeper, piglin or dragon.
    • [String] texture: Optional. Namespaced ID for the texture, without textures/entity/ prefix and .png suffix.
      • If absent, default texture will be used, depending on kind field.
    • [Float] animation: Optional. Controlling head animation if available for this kind of head (like Piglin ears or Ender Dragon jaw). Default: 0.0.
      • The dragon animation is 10 units long. Mouth fully closed at -2.5 and fully open at 2.5 [3].
      • The piglin ears wiggle out of sync. The left ear period is 8.3333 and right ear period is 10.0.[3]
player_head

Render a player head. Use the data into the minecraft:profile component to select the texture to render.

No additional fields for this type.

shield

Render a shield. Uses patterns from minecraft:banner_patterns component and color from minecraft:base_color component.

No additional fields for this type.

shulker_box

Render a shulker box.

  • [NBT Compound / JSON Object] Root shulker_box special type object
    • [String] type: minecraft:shulker_box
    • [String] texture: Namespaced ID for the texture in the shulker boxes texture atlas without the .png suffix. By default this includes textures in textures/entity/shulker/, without the prefix.
    • [Float] openness: Optional. Render the shulker box in the specified open state, between 0.0 (fully closed) to 1.0 (fully open). Default: 0.0.
    • [String] orientation: Optional. Orientation for rendering. Default: up.
standing_sign

Renders a standing sign.

  • [NBT Compound / JSON Object] Root standing_sign special type object
    • [String] type: minecraft:standing_sign
    • [String] wood_type: One of oak, spruce, birch, acacia, cherry, jungle, dark_oak, pale_oak, mangrove, bamboo, crimson or warped.
    • [String] texture: Optional. Namespaced ID for the texture in the signs texture atlas without the .png suffix. By default this includes textures in textures/entity/signs/, without the prefix. If present, wood_type field is ignored.
hanging_sign

Renders a hanging sign.

  • [NBT Compound / JSON Object] Root hanging_sign special type object
    • [String] type: minecraft:hanging_sign
    • [String] wood_type: One of oak, spruce, birch, acacia, cherry, jungle, dark_oak, pale_oak, mangrove, bamboo, crimson or warped.
    • [String] texture: Optional. Namespaced ID for the texture in the signs texture atlas without the .png suffix. By default this includes textures in textures/entity/signs/, without the prefix. If present, wood_type field is ignored.
trident

Render a trident.

No additional fields for this type.

References

  1. ↑ Name from the official name ("Item model", 24w45a news) and file directory (assets/<namespace>/items).
  2. ↑ "Minecraft 1.21.6 Pre-Release 1" – Minecraft.net, May 28, 2025.
  3. ↑ a b News in Resource Pack Version 46 (1.21.4 Pre-Release 1)

History

Java Edition
1.21.424w45aAdded Item model definitions.
24w46aAdded holder_type property types.
Added keybind_down boolean property types.
Added standing_sign and hanging_sign special model types.
Added texture field to head special model types.
Removed xmas boolean property, replaced by local_time property model types.
Removed shift_down boolean property, replaced by extended_view boolean property.
Pre-Release 1Add hand_animation_on_swap field to items model definition.
Added empty item model type.
Added team tint sources type.
Added context_dimension property type.
Added view_entity boolean property type.
Renamed holder_type to context_entity_type property type.
Removed natural_only field and added source field in time numeric property type.
Added none to possible values for target field in compass numeric property type.
Added animation field to head special model type.
1.21.525w03aAdd component property type.
25w04aAdd component boolean property type.
1.21.6Pre-Release 1Remove the support of loading profile data for head special type to render player head.
Add player_head special type.
Add oversized_in_gui field to items model definition.

Navigation

  • v
  • t
  • e
Java Edition technical
This article is issued from Minecraft Wiki. The text is available under CC BY-NC-SA 3.0 unless otherwise noted. Additional terms may apply for the media files.