Item Models

Since 1.21.4

Custom item models allow developers to specify what model/texture to use when rendering items in Minecraft. The concept of custom models has exited in-game for a long time, but was overhauled in 1.21.4.

More detailed instructions for resource packs are available at guide.love-tolerance.com.

Content on this page is largely pulled from the official Minecraft patch notes, with light editing and formatting.

Model syntax

Item models are selected based on the minecraft:item_model component.

The model for item with item_model=foo:bar is stored in /assets/foo/items/bar.json

{
  "model": {
    "type": <item model type>,
    <item model type specific fields>
  }
}

Item model types

`minecraft:model`

Renders a plain model from models directory
Fields:
- model: namespaced ID of model in models (e.g. minecraft:block/yellow_glazed_terracotta)
- tints: a list of tint sources to apply to elements of rendered model (first entry applies to tintindex 0, second one -1, etc.)
  - Format:
    - type: type of tint source
    - <type-specific>: additional fields depending on tint source type

`minecraft:special`

Renders a special (not data-driven) model -Fields:
- model: special model instance
  - Format:
    - type: type of special model
    - <type-specific>: additional fields depending on special model type
- base: namespaced ID of model in models, providing transformations, particle texture and GUI light

`minecraft:composite`

Renders multiple sub-models
All models are rendered in the same space
Fields:
- models: a list of item models to render

`minecraft:condition`

Renders an item model depending on a boolean property
Fields:
- property: type of boolean property
- <property-specific>: additional fields depending on property type, added inline
- on_true: item model to render when property is true
- on_false: item model to render when property is false

`minecraft:select`

Renders an item model based on one or more discrete properties
Fields:
- property: type of discrete property
- <property-specific>: additional fields depending on property type, added inline
- cases: list of cases to match in format:
  - when: value to match against property, type depends on property
    - could be a single value or a list of values
  - model: item model to render when case is selected
- fallback: item model to render if none of the cases matched the value
  - if not present, placeholder “missing” model will be rendered instead

`minecraft:range_dispatch`

Renders an item model based on numeric property
Will select last entry with threshold less or equal to property value
Fields:
- property: type of numeric property
- <property-specific>: additional fields depending on property type
- scale: factor to multiply property value with, default: 1.0
- entries: list of entries in format:
  - threshold: float value
  - model: item model to render when entry is selected
  - Note: order of fields does not matter, list will be sorted by threshold in ascending order before use
- fallback: item model to render if no entries were less or equal to property value
  - if not present, placeholder “missing” model will be rendered instead

`minecraft:bundle/selected_item`

Renders selected stack in minecraft:bundle_contents component, if present, otherwise does nothing

`minecraft:empty`

Does not render anything

Tint source types

These are used by the minecraft:model item model type.

`minecraft:constant`

Returns a constant RGB colour
Fields:
- value: A packed integer RGB value (e.g. -1) or an array of RGB channel percentages (e.g. [ 1, 1, 1 ])

`minecraft:dye`

Returns value from minecraft:dyed_color component or default if not present
Fields:
- default: RGB value (packed integer or channel percentages)

`minecraft:grass`

Returns grass colour at specific climate parameters, based on textures/colormap/grass.png
Same colours as ones selected by downfall and temperature in biome configuration
Fields:
- temperature: float in 0..1 (inclusive) range
- downfall: float in 0..1 (inclusive) range

`minecraft:firework`

Returns average of colours from minecraft:firework_explosion component or default colour if there are none
Fields:
- default: RGB value (packed integer or channel percentages)

`minecraft:potion`

Returns colour from minecraft:potion_contents component:
- if component is present:
  - custom colour, if there is one present in component
  - default colour, if effect list is empty
  - average of effect colours, otherwise
- default colour, otherwise
Fields:
- default: RGB value (packed integer or channel percentages)

`minecraft:map_color`

Return value from minecraft:map_color component or default colour if component is not present
Fields:
- default: RGB value (packed integer or channel percentages)

`minecraft:custom_model_data` (tint source)

Returns value from colours list in minecraft:custom_model_data component
Fields:
- index: index for field in colors, default: 0

`minecraft:team`

Returns team colour of context entity, if any
Fields:
- default: RGB value (packed integer or channel percentages)
  - returned when there is no context entity, entity is not in a team or team has no colour

Boolean properties

These are used by the minecraft:condition item model type.

`minecraft:using_item`

Returns true if player is currently using this item

`minecraft:broken`

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

`minecraft:damaged`

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

`minecraft:has_component`

Returns true if the given component is present on the item
Fields:
- component: component type
- ignore_default: if default component value should be handled as “no component”, default: false

`minecraft:fishing_rod/cast`

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

`minecraft:bundle/has_selected_item`

Returns true if bundle is “open”, i.e. it has selected item visible in GUI

`minecraft: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 the ICU documentation
Fields:
- locale: optional value describing locale
  - Examples: en_US: English language (used for things like week names), formatting as in USA cs_AU@numbers=thai;calendar=japanese: Czech language, Australian formatting, Thai numerals and Japanese calendar
  - default value is "", which means “root” locale (a set of defaults, including English names)
- time_zone: optional value describing time zone
  - If not present, defaults to timezone set on client
    - Examples:
      - Europe/Stockholm
      - GMT+0:45
- pattern: describes format to be used for time formatting
  - Examples:
    - 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

`minecraft:selected`

Returns true if item is selected on a hotbar

`minecraft:carried`

Returns true if item is carried between slots in GUI

`minecraft:keybind_down`

Returns true if keybind is currently active
Fields:
- keybind: keybind ID, same as value in keybind text component
  - Examples: key.use, key.left

`minecraft:extended_view`

Returns true if player has requested extended details by holding shift key down
- Note: not a keybind, can’t be rebound
Only works when item is displayed in UI

`minecraft:custom_model_data` (boolean property)

Returns value from flags list in the minecraft:custom_model_data component
Fields:
- index: index for field in flags, default: 0

`minecraft:view_entity`

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

`minecraft:component` (boolean property)

Uses component predicates (like ones used in item predicates) to match item components
However, instead of encoding them as a map of <predicate type>:<predicate value>, a single predicate is encoded in two fields
Fields:
- predicate: type of component predicate (member of minecraft:data_component_predicate_type registry)
- value: predicate-specific value

Discrete properties

These are used by the minecraft:select item model type.

`minecraft:main_hand`

Returns main hand of holding player
Values: left, right

`minecraft:charge_type`

Returns charge type stored in the minecraft:charged_projectiles component
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

`minecraft:trim_material`

Returns value of material field from the minecraft:trim component, if present
Values: namespaced ID

`minecraft:block_state`

Returns value for some property from the minecraft:block_state component
Fields:
- block_state_property: string key to select from component
Values: any string

`minecraft:display_context`

Returns context this item is rendered in
Values:
- none
- thirdperson_lefthand
- thirdperson_righthand
- firstperson_lefthand
- firstperson_righthand
- head
- gui
- ground
- fixed

`minecraft:custom_model_data` (discrete property)

Returns value from strings list in the minecraft:custom_model_data component
Fields:
- index: index for field in strings, default: 0
Values: any string

`minecraft:context_entity_type`

Returns holding entity type, if present
Values: namespaced entity type ID

`minecraft:context_dimension`

Returns the ID of the dimension in context, if any
Values: namespaced dimension ID (like minecraft:overworld)

`minecraft:component` (discrete property)

Returns value of component on item, if any
Fields:
- component: namespaced ID of component type
Possible values: depends on component type
- Example: if component is set to minecraft:wolf/collar, list of cases will accept dye colors, like lime
If the selected value comes from a registry and the current datapacks do not provide it, the entry will be silently ignored

Numerical properties

These are used by the minecraft:range_dispatch item model type.

`minecraft:bundle/fullness`

Returns weight of the minecraft:bundle_contents component or 0 if not present

`minecraft:damage`

Returns value for damage component
Fields:
- normalize: boolean, default: true
  - if true, returns value of damage divided by the minecraft:max_damage component, clamped to 0..1
  - if false, returns value of damage, clamped to 0..max_damage

`minecraft:count`

Returns stack size
Fields:
- normalize: boolean, default: true
  - if true, returns count divided by the minecraft:max_stack_size component, clamped to 0..1
  - if false, returns count clamped to 0..max_stack_size

`minecraft:cooldown`

Returns remaining cooldown for item, scaled to 0..1

`minecraft:time`

Returns value of day time or moon phase, scaled to 0..1
Used by the clock
Fields:
- wobble: if true, value will oscillate for some time around target before settling, default: true
- source: time source, possible values:
  - daytime: time of day
  - moon_phase: moon phase
  - random: random value

`minecraft:compass`

Returns angle, scaled to 0..1 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
Used by the compass, and the recovery compass
Fields:
- 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
  - wobble: if true, value will oscillate for some time around target before settling, default: true
  - none: always returns an invalid target

`minecraft:crossbow/pull`

Returns crossbow-specific use time

`minecraft:use_duration`

Returns item use ticks
Fields:
- remaining: if true, returned value will be remaining use ticks, if false: ticks so far, default: false

`minecraft:use_cycle`

Returns remaining use ticks modulo period
Fields:
- period: positive float, default 1.0

`minecraft:custom_model_data` (numeric property)

Returns value from floats list in the minecraft:custom_model_data component
Fields:
- index: index for field in floats, default: 0

Special model types

These are used by the minecraft:special item model type.

`minecraft:bed`

Renders a whole bed
Fields:
- texture: namespaced ID for texture, without textures/entity/bed/ prefix and .png suffix

`minecraft:banner`

Renders a banner with patterns from minecraft:banner_patterns component
Fields:
- color: colour of banner base, one of 16 predefined colours

`minecraft:conduit`

Renders a conduit

`minecraft:chest`

Renders a single chest
Fields:
- texture: namespaced ID for texture, without textures/entity/chest/ prefix and .png suffix
- openness: float, 0.0 (default) - fully closed, 1.0: fully open

`minecraft:head`

Renders a head
Uses profile from minecraft:profile component when applicable
Fields:
- kind: one of skeleton, wither_skeleton, player, zombie, creeper, piglin, or dragon
- texture: optional namespaced ID for texture, without textures/entity/ prefix and .png suffix
  - If absent, default texture will be used, depending on kind field
  - Additionally, if present, the minecraft:profile component is ignored
- animation: float controlling head animation (like Piglin ears or Ender Dragon jaw), default: 0.0

`minecraft:shulker_box`

Renders a shulker box
Fields:
- texture: namespaced ID for texture, without textures/entity/shulker/ prefix and .png suffix
- openness: float, 0.0 (default) - fully closed, 1.0: fully open
- orientation: orientation for rendering, default: up

`minecraft:shield`

Renders a shield
Uses patterns from minecraft:banner_patterns component and colour from minecraft:base_color component

`minecraft:trident`

Renders a trident

`minecraft:decorated_pot`

Renders a decorated pot
Uses values from minecraft:pot_decorations component

`minecraft:standing_sign`

Renders a standing sign
Fields:
- wood_type: one of oak, spruce, birch, acacia, cherry, jungle, dark_oak, pale_oak, mangrove, bamboo, crimson, or warped
- texture: optional namespaced ID for texture, without textures/entity/signs/ prefix and .png suffix
  - if not present, it will be derived from wood_type

`minecraft:hanging_sign`

Renders a hanging sign
Fields:
- wood_type: one of oak, spruce, birch, acacia, cherry, jungle, dark_oak, pale_oak, mangrove, bamboo, crimson, or warped
- texture: optional namespaced ID for texture, without textures/entity/signs/hanging/ prefix and .png suffix
  - if not present, it will be derived from wood_type

Item Models

Model syntax

Item model types

minecraft:model

minecraft:special

minecraft:composite

minecraft:condition

minecraft:select

minecraft:range_dispatch

minecraft:bundle/selected_item

minecraft:empty

Tint source types

minecraft:constant

minecraft:dye

minecraft:grass

minecraft:firework

minecraft:potion

minecraft:map_color

minecraft:custom_model_data (tint source)

minecraft:team

Boolean properties

minecraft:using_item

minecraft:broken

minecraft:damaged

minecraft:has_component

minecraft:fishing_rod/cast

minecraft:bundle/has_selected_item

minecraft:local_time

minecraft:selected

minecraft:carried

minecraft:keybind_down

minecraft:extended_view

minecraft:custom_model_data (boolean property)

minecraft:view_entity

minecraft:component (boolean property)

Discrete properties

minecraft:main_hand

minecraft:charge_type

minecraft:trim_material

minecraft:block_state

minecraft:display_context

minecraft:custom_model_data (discrete property)

minecraft:context_entity_type

minecraft:context_dimension

minecraft:component (discrete property)