[!NOTE] Version note: This page covers the plugin shape for Minecraft 1.21.11, 26.1.2, and 26.2.

Other plugin pages:

• Minecraft 1.21 and 1.21.1: Creating Your Plugin
• Minecraft 1.12.2: Creating Your Plugin
• Minecraft 1.16.5, 1.18.2, 1.19.2, and 1.20.1: Creating Your Plugin

Creating a JEI Plugin

JEI plugins implement IModPlugin. Keep all direct JEI API references inside your plugin or other code that is only loaded when JEI is present.

Minimal Plugin

import mezz.jei.api.IModPlugin;
import mezz.jei.api.JeiPlugin;
import net.minecraft.resources.Identifier;

@JeiPlugin
public class ExampleJeiPlugin implements IModPlugin {
  @Override
  public Identifier getPluginUid() {
    return Identifier.fromNamespaceAndPath("examplemod", "jei_plugin");
  }
}

The plugin UID must be unique. Use your mod id as the namespace, and use a distinct path if your mod has more than one JEI plugin.

Under NeoForge, JEI finds plugins with the @JeiPlugin annotation. The plugin class must have a no-argument constructor.

Under Fabric, add the plugin class to the jei_mod_plugin entrypoint in fabric.mod.json:

{
  "entrypoints": {
    "jei_mod_plugin": [
      "com.example.ExampleJeiPlugin"
    ]
  }
}

Common Plugin Shape

Most custom recipe integrations use these methods:

1. registerCategories to register your IRecipeCategory.
2. registerRecipes to register recipe instances for your recipe type.
3. registerRecipeCatalysts to register the blocks or items that craft those recipes.
4. registerGuiHandlers or registerRecipeTransferHandlers if your screen supports click areas, ghost ingredients, or recipe transfer.

Plugin Stages

registerItemSubtypes

Tell JEI how to compare item subtypes that depend on data components, NBT, or capabilities.

registerFluidSubtypes

Tell JEI how to compare fluid subtypes when fluid identity depends on extra data.

registerIngredients

Register custom ingredient types beyond the built-in item and fluid ingredients. Use this for ingredients that need their own helper, renderer, codec, and ingredient list.

registerExtraIngredients

Add extra ingredients to an already-registered ingredient type. Use this for item stacks that are not in the creative menu, or for additional fluid stacks not covered by the registry defaults.

registerIngredientAliases

Add search aliases for ingredients. Aliases may be literal search terms or translation keys.

registerModInfo

Add extra mod metadata, such as alternate mod names that players can search for.

registerCategories

Register custom recipe categories.

registerVanillaCategoryExtensions

Extend existing Vanilla categories, such as crafting or smithing, for custom Vanilla recipe behavior.

registerRecipes

Register recipes for modded and vanilla categories. This is where you should register custom machine recipes and other recipes that JEI does not automatically discover.

registerRecipeTransferHandlers

Register handlers for the + button that transfers ingredients into a menu.

registerRecipeCatalysts

Register crafting stations for recipe types. For example, register your machine block as the crafting station for that machine's recipe type.

registerGuiHandlers

Register GUI integration, including recipe click areas, ghost ingredients, and screen areas that JEI should avoid drawing over.

registerAdvanced

Register advanced hooks like recipe manager plugins, category decorators, custom recipe buttons, and JEI feature toggles. Most integrations do not need this.

registerRuntime

Override JEI runtime services. This is intended for mods that replace JEI's UI while still supporting JEI API integrations.

onRuntimeAvailable

Access runtime services through IJeiRuntime after JEI finishes loading.

onRuntimeUnavailable

Clear cached runtime references after the player quits or logs out of a world.

onConfigManagerAvailable

Access JEI's config manager early through IJeiConfigManager.

Use the API Javadocs for exact method signatures on your target Minecraft version.