[!NOTE] Version note: This page covers the plugin shape for Minecraft 1.21 and 1.21.1.

Other plugin pages:

• Minecraft 1.21.11, 26.1.2, and 26.2: Creating Your Plugin
• Minecraft 1.16.5, 1.18.2, 1.19.2, and 1.20.1: Creating Your Plugin
• Minecraft 1.12.2: Creating Your Plugin

Creating a JEI Plugin

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

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

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

The plugin UID must be unique. Use your mod id as the namespace and a distinct path for the plugin.

Under NeoForge and Forge, 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 RecipeType.
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.

registerExtraIngredients

Add extra ingredients to an already-registered ingredient type.

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.

registerRecipeTransferHandlers

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

registerRecipeCatalysts

Register crafting stations for recipe types. In these versions the method name is addRecipeCatalysts.

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.