Note

Version note: This page covers Minecraft 1.21.11, 26.1.2, and 26.2.

Related pages for other README-supported versions:

Minecraft 1.21 and 1.21.1: Getting Started, Creating Your Plugin, Recipe Categories
Minecraft 1.18.2, 1.19.2, and 1.20.1: Essential Extras, Recipe Click Areas, Recipe Transfer Handlers
Minecraft 1.16.5: Essential Extras, Recipe Click Areas, Recipe Transfer Handlers
Minecraft 1.12.2: Recipe Click Areas, Recipe Transfer Handlers

GUI Integration

Use registerGuiHandlers when JEI needs to understand your screen layout, clickable areas, non-slot ingredients, or ghost ingredient targets.

@Override
public void registerGuiHandlers(IGuiHandlerRegistration registration) {
  registration.addRecipeClickArea(
    CrusherScreen.class,
    78,
    34,
    24,
    17,
    ExampleJeiPlugin.CRUSHING
  );

  registration.addGuiContainerHandler(CrusherScreen.class, new CrusherGuiHandler());
  registration.addGhostIngredientHandler(CrusherScreen.class, new CrusherGhostIngredientHandler());
}

Click Areas

Use addRecipeClickArea for a fixed area of your container screen that should open JEI to one or more recipe types.

The x, y, width, and height values are relative to the left and top of the GUI, not the full screen.

registration.addRecipeClickArea(CrusherScreen.class, 78, 34, 24, 17, ExampleJeiPlugin.CRUSHING);

For dynamic areas, implement IGuiContainerHandler#getGuiClickableAreas.

Extra Areas

If your screen draws tabs, side panels, or other widgets outside the normal GUI rectangle, return those rectangles so JEI can avoid covering them.

public final class CrusherGuiHandler implements IGuiContainerHandler<CrusherScreen> {
  @Override
  public List<Rect2i> getGuiExtraAreas(CrusherScreen screen) {
    return List.of(screen.getUpgradePanelArea());
  }
}

These rectangles are in absolute screen coordinates.

Clickable Ingredients

JEI detects normal slots automatically. Use getClickableIngredientUnderMouse for ingredients drawn outside slots, such as a fluid tank, an energy-like custom ingredient, or a rendered item preview.

public final class CrusherGuiHandler implements IGuiContainerHandler<CrusherScreen> {
  @Override
  public Optional<? extends IClickableIngredient<?>> getClickableIngredientUnderMouse(
    IClickableIngredientFactory factory,
    CrusherScreen screen,
    double mouseX,
    double mouseY
  ) {
    Rect2i tankArea = screen.getTankArea();
    if (!tankArea.contains((int) mouseX, (int) mouseY)) {
      return Optional.empty();
    }

    return factory.createBuilder(screen.getTankItemStack())
      .buildWithArea(tankArea);
  }
}

For fluids or custom ingredient types, use factory.createBuilder(ingredientType, ingredient) with the platform ingredient type you registered or imported.

Ghost Ingredients

Use IGhostIngredientHandler when players should be able to drag ingredients from JEI into your screen as filters, patterns, or recipe templates. Ghost ingredients are not moved from the player's inventory.

public final class CrusherGhostIngredientHandler implements IGhostIngredientHandler<CrusherScreen> {
  @Override
  public <I> List<Target<I>> getTargetsTyped(CrusherScreen screen, ITypedIngredient<I> ingredient, boolean doStart) {
    Rect2i area = screen.getGhostFilterArea();

    return List.of(new Target<>() {
      @Override
      public Rect2i getArea() {
        return area;
      }

      @Override
      public void accept(I ingredient) {
        screen.setGhostFilter(ingredient);
      }
    });
  }

  @Override
  public void onComplete() {
  }
}

Target areas are in absolute screen coordinates. Use the typed ingredient to decide whether your screen can accept the dragged ingredient.

When To Use Each Handler

Use addRecipeClickArea for a static button, arrow, flame, progress bar, or machine icon that opens recipes.
Use getGuiExtraAreas when JEI overlaps parts of your screen.
Use getClickableIngredientUnderMouse for rendered ingredients that are not normal container slots.
Use addGhostIngredientHandler for filters, encoded patterns, and recipe previews.
Use addGuiScreenHandler only when your screen is not an AbstractContainerScreen.