Bedrock Add-ons JSON 2026

How to Make a Custom Item in Minecraft Bedrock (2026)

Create a real, survival-ready item with a working icon, display name, Creative inventory entry, optional food behavior, and a clean debugging path.

18 min read
Reviewed July 2026
Beginner to intermediate
Current workflowThis guide was checked against the stable Minecraft Creator documentation in July 2026. It uses current item components and avoids old tutorials that rely on deprecated item fields.

The short answer

A custom Bedrock item needs an item definition in the Behavior Pack. If it has its own icon or display name, it also needs matching Resource Pack files. Four values must agree: the item identifier, the minecraft:icon value, the key in item_texture.json, and the PNG path.

We will build Ruby Apple, an edible item with the identifier icedfox:ruby_apple. The same foundation works for materials, quest items, tools, weapons, gadgets, food, or scripted objects.

Before you start

  • A working Behavior Pack and Resource Pack with valid manifests.
  • A code editor such as Visual Studio Code.
  • A square PNG icon. A 16x16 or 32x32 transparent image is a sensible starting point.
  • Minecraft Bedrock with both development packs active in a test world.
Need the pack foundation?Build the manifests first with our Bedrock manifest.json guide. Do not debug an item inside packs that Minecraft is not loading correctly.

Use this exact file structure

Keep behavior and presentation separate. The Behavior Pack tells the game what the item does; the Resource Pack tells the client what it looks like and what it is called.

Pack structure
RubyApple_BP/
  manifest.json
  items/
    ruby_apple.json

RubyApple_RP/
  manifest.json
  textures/
    item_texture.json
    items/
      ruby_apple.png
  texts/
    en_US.lang
    languages.json

Folder names are case-sensitive on some platforms and servers. Pick lowercase file names, use underscores consistently, and do not silently change ruby_apple to RubyApple in one file.

Step 1: create the item JSON

Create RubyApple_BP/items/ruby_apple.json. This complete example places the item in the Creative inventory and makes it edible.

items/ruby_apple.json
{
  "format_version": "1.21.90",
  "minecraft:item": {
    "description": {
      "identifier": "icedfox:ruby_apple",
      "menu_category": {
        "category": "items",
        "group": "minecraft:itemGroup.name.food"
      }
    },
    "components": {
      "minecraft:icon": "ruby_apple",
      "minecraft:max_stack_size": 64,
      "minecraft:use_animation": "eat",
      "minecraft:use_modifiers": {
        "use_duration": 1.6,
        "movement_modifier": 0.35
      },
      "minecraft:food": {
        "nutrition": 6,
        "saturation_modifier": 0.8,
        "can_always_eat": false
      }
    }
  }
}

What each important field does

  • identifier is the permanent namespaced ID used by commands, recipes, loot tables, and scripts.
  • menu_category makes the item discoverable in Creative mode.
  • minecraft:icon points to a texture key, not directly to a PNG file.
  • minecraft:food makes the item edible and controls hunger and saturation.
  • minecraft:use_modifiers controls use time and movement while the item is being used.

If you want a simple material instead of food, remove minecraft:food, minecraft:use_animation, and minecraft:use_modifiers. Keep the identifier, icon, category, and stack size.

Step 2: register the icon texture

Save the icon as RubyApple_RP/textures/items/ruby_apple.png. Then create or extend textures/item_texture.json:

textures/item_texture.json
{
  "resource_pack_name": "Ruby Apple Resources",
  "texture_name": "atlas.items",
  "texture_data": {
    "ruby_apple": {
      "textures": "textures/items/ruby_apple"
    }
  }
}

The key ruby_apple matches the value used by minecraft:icon. The texture path excludes .png. If either string differs by one character, the item can exist and function while its icon remains missing.

Do not use a model texture as the inventory iconA UV texture made for a 3D model usually looks like scattered fragments in the inventory. Use a dedicated square icon for the hotbar and inventory, even when the held item has a separate model or attachable.

Step 3: add the display name

Create texts/languages.json and declare the language files included by the Resource Pack:

texts/languages.json
[
  "en_US"
]

Then add the item name to texts/en_US.lang:

texts/en_US.lang
item.icedfox:ruby_apple.name=Ruby Apple

For a public addon, add more language files rather than hard-coding several names in JSON. The en_US file also works as the normal fallback when another translation is unavailable.

Step 4: test one layer at a time

  1. Activate the Behavior Pack and its linked Resource Pack in a disposable test world.
  2. Run /give @s icedfox:ruby_apple.
  3. Confirm the name and icon in the hotbar.
  4. Switch to Survival, reduce hunger, and eat the item.
  5. Check the Creative inventory category and search for "Ruby Apple".
  6. Leave and reload the world once to catch pack-cache problems.

If the command says the item is unknown, debug the Behavior Pack. If the item is given but has no name or icon, debug the Resource Pack. That distinction cuts the problem in half immediately.

Turn the basic item into a real addon feature

Once the static item works, extend it deliberately:

  • Add a shaped or shapeless survival recipe with the custom recipes guide.
  • Use durability, repairability, damage, digger, wearable, throwable, shooter, or cooldown components where the item type calls for them.
  • Use a custom component and Script API only for behavior that data-driven components cannot express cleanly.
  • Add the item to loot tables, trades, mob drops, structures, or progression instead of leaving it Creative-only.
  • Test multiplayer behavior and item persistence before publishing.

A good item is more than a JSON file. Players need to understand how to obtain it, why it matters, and where it sits in the addon progression.

Common custom item problems

The item is unknown in the /give command

Confirm the Behavior Pack is active, the item file is inside items/, the JSON parses, and the identifier includes your namespace. Open the Content Log before changing random fields.

The item is invisible or uses the missing-texture icon

Compare minecraft:icon, the texture_data key, and the PNG path character by character. Confirm the file is a real PNG and the Resource Pack is active.

The item name shows a translation key

Check the line in en_US.lang, verify languages.json, and make sure both are inside the Resource Pack texts/ folder.

The icon works but the item cannot be eaten

The Behavior Pack is loading, so focus on the use components. Keep minecraft:food, minecraft:use_modifiers, and minecraft:use_animation together, then check the Content Log for a version or schema error.

The item works only in an old test world

Development pack caches can hide changes. Increase the pack version when distributing an update, remove duplicate imported copies, and retest in a clean world.

Frequently asked questions

Do custom items need both a Behavior Pack and Resource Pack?

The definition belongs in a Behavior Pack. Add a Resource Pack when the item has a custom icon, model, attachable, sounds, or translated name.

Can I create the item with Blockbench instead?

Yes. The Minecraft Item Wizard can generate a useful starting pack and is especially helpful for 3D held items. You should still understand the exported files so you can maintain the addon after the wizard step.

Why should I use my own namespace?

A namespace prevents collisions with vanilla content and other addons. Do not create custom content under minecraft:; use a stable studio or project namespace.

Official sources checked