Item Options

This page describes configuring an item in JSON config formatting and the available options for them.

Item Options

The item definitions themselves are also in a MAP format (key -> value), containing all the available options for the item. Below are the available options for items.

Item (required)

An item resource location (combination of mod_id:item_id). This can be any item, vanilla or modded. Unknown item stacks will default to minecraft:air. See the Supported Items section for more information on supported items.

"item": "minecraft:stone"

Slots

Aliases: slot

This option is not always available depending on the context of the item. For example, in a Reward’s "display": {} configuration, the slots setting is not available.

A list of slots that this item will be inserted into. This value should be between 0 and the (size * 9) - 1. EX: if "size: 3", then between 0 and 26. Defaults to an empty list if not provided.

Tip

Some options are flexible-lists, meaning you can either set it to a specific value or define a list!

"slots": 1
"slots": [1, 2, 3]

"slots": [0, 1, 7, 8]

Amount

The amount of this item that should be displayed in each slot. Defaults to 1 if not provided.

"amount": 10

Name

The name to override the item with. Defaults to the item’s normal name if not provided. Uses MiniMessage formatting!

"name": "<red>Example Stone"

Lore

A list of lore to override the item with. Defaults to an empty list if not provided. Uses MiniMessage formatting!

"lore": [
  "<gray>Example Line 1",
  "<gray>Example Line 2"
]

Custom Model Data

An number representing the Custom Model Data of the item. This is a quick option for the "minecraft:custom_model_data" component, added for ease of use. Not applied if not provided.

"custom_model_data": 123456

Components (nbt)

Aliases: nbt

A list of components that are set onto the item. This follows the same formatting as applying components to an item via /give. No additional components are applied if not provided.

Note

Components are the new way of defining item NBT in Minecraft. They replaced the older NBT format in versions 1.20.5+. For more information on components, see the Minecraft Wiki on Data Components.

"components": {
  "minecraft:enchantments": {
    "levels": {
    "minecraft:unbreaking": 3
    },
    "show_in_tooltip": false
  },
  "minecraft:hide_additional_tooltip": {}
}

Components Guide to configuring item components (nbt)

Actions

This option is not always available depending on the context of the item. For example, in a Reward’s "display": {} configuration, the actions setting is not available, but it is for the "items" section of a Preview GUI.

A list of Actions that are executed when the item is clicked on. See Actions for more information.

"actions": {
  "action_1": {
    "type": "COMMAND_CONSOLE",
    "click": "ANY",
    "commands": ["give %player% diamond_sword 1"]
  },
  "action_2": {
    "type": "MESSAGE",
    "click": "ANY",
    "message": ["<blue>You have received the Example Sword!"]
  }
}

Actions Guide to configure item click actions

Supported Items

The "item": "" option supports a variety of inputs, either default mod_id:item_id identifiers or special keywords for specific item types. All inputs are parsed against any Placeholder Services.

Vanilla Items

Vanilla items can be called on using either minecraft:<item_id> or just <item_id>. For example, both minecraft:stone and stone will give a stone block.

Modded Items

Modded items can be called on using their full mod_id:item_id identifier. For example, cobblemon:poke_ball will give a Poke Ball item from Cobblemon.

Player Heads

Player Heads can be set using the special keyword playerhead followed by an option specifier. Below are available option specifiers:

• playerhead - Gives the head of the player viewing the GUI.
• playerhead-<uuid> - Gives the head of the player with the specified UUID. This will work if the player is offline but must have played on the server before.
• playerhead-<username> - Gives the head of the player with the specified username. This will only work if the player is online.
• playerhead-<base64> - Gives a custom head with the texture specified by the base64 string. Useful for custom heads from head databases.

Example Item Definition

"item_1": {
  "item": "minecraft:diamond_sword",
  "slots": [0],
  "count": 1,
  "name": "<blue><b>Example Sword",
  "lore": ["<gray><italic>Example lore!"],
  "components": {
    "minecraft:enchantments": {
      "levels": {
        "minecraft:unbreaking": 3
      },
      "show_in_tooltip": false
    },
    "minecraft:hide_additional_tooltip": {}
  },
  "actions": {
    "action_1": {
      "type": "COMMAND_CONSOLE",
      "click": "ANY",
      "commands": ["give %player% diamond_sword 1"]
    },
    "action_2": {
      "type": "MESSAGE",
      "click": "ANY",
      "message": ["<blue>You have received the Example Sword!"]
    }
  }
}