SSGL Wiki

Image Buttons

Image buttons display images without text labels.

They are useful for camera previews, screenshot galleries, image selectors, thumbnails, and other visual interfaces. Unlike ordinary buttons, image buttons display the supplied texture directly.

Basic image button

Create an identifier for your texture:

Identifier cameraImage =
    Identifier.fromNamespaceAndPath(
        "mymod",
        "textures/gui/camera.png"
    );

Add the image button:

gui.add(
    GuiElement.imageButton(
        cameraImage,
        () -> openCamera()
    )
);

The default button size is 64 x 64 pixels.

Custom dimensions

You can provide a custom button width and height:

GuiElement.imageButton(
    cameraImage,
    96,
    64,
    this::openCamera
);

The default dimensions are not mandatory when using the custom-size overload.

Image aspect ratio

SSGL preserves the original image aspect ratio.

Images are scaled using a contain-style fit:

  • Images are never stretched
  • Images are not cropped
  • The entire image remains visible
  • Images are centered inside the button
  • Empty space remains around images that do not fill the button

For example, a 256 x 128 image inside a 64 x 64 button is displayed at 64 x 32 pixels.

Both horizontal and vertical images are supported.

Missing images and placeholders

If no image is provided, or if the resource image is missing or invalid, SSGL displays a question mark (?).

You can create an empty image button directly:

GuiElement.imageButton(
    () -> openCamera()
);

You can also provide custom dimensions:

GuiElement.imageButton(
    96,
    64,
    this::openCamera
);

This is useful when a preview is not yet available.

Image button alignment

Image buttons use the same alignment API as other elements.

GuiElement.imageButton(
    cameraImage,
    96,
    64,
    this::openCamera
).align(Alignment.CENTER);

Alignment controls the position of the button inside its allocated layout space. The image itself remains centered inside the button.

Tooltips

Image buttons support both ordinary strings and Minecraft Component tooltips.

String tooltip:

GuiElement.imageButton(
    cameraImage,
    "Open camera",
    this::openCamera
);

Translated tooltip:

GuiElement.imageButton(
    cameraImage,
    Component.translatable("mymod.gui.camera.tooltip"),
    this::openCamera
);

Tooltips are only registered when non-empty text is provided. When no tooltip is supplied, the image button simply displays its image or placeholder.

Accessibility narration

Image buttons also accept a narration Component.

It is not displayed visually, but provides a descriptive name for accessibility features.

GuiElement.imageButton(
    Component.translatable("mymod.gui.camera.narration"),
    cameraImage,
    96,
    64,
    this::openCamera
);

Use meaningful narration text instead of generic names such as "Image button" whenever possible.

Dynamic images

SSGL also supports images that are created at runtime. This is particularly useful for like camera or screenshot mods.

Unlike resource images, dynamic images do not need to exist in your mod's resources directory.

Your mod is responsible for creating and registering the dynamic texture with Minecraft. SSGL handles displaying it.

Example

Assume your camera mod implementation already has:

  • A registered dynamic texture identifier
  • The original texture width and height
  • A method indicating whether a photo is available
  • A method for opening the photo

You can display it like this:

gui.add(
    GuiElement.dynamicImageButton(
        Component.translatable("mymod.gui.photo"),
        photoTexture,
        photoWidth,
        photoHeight,
        camera::hasPhoto,
        96,
        64,
        Component.translatable("mymod.gui.photo.tooltip"),
        camera::openPhoto
    )
);

Parameters

Parameter Description
narration Accessible description of the image button
image Identifier of the registered dynamic texture
imageWidth Original texture width
imageHeight Original texture height
imageAvailable Supplies whether the image should currently be displayed
buttonWidth Image button width
buttonHeight Image button height
tooltip Optional tooltip
onPress Action performed when clicked

Dynamic image dimensions are required because SSGL cannot infer the original size from the texture identifier.

Default-size dynamic buttons

Dynamic buttons also provide a 64 × 64 default-size overload:

GuiElement.dynamicImageButton(
    Component.literal("Photo"),
    photoTexture,
    photoWidth,
    photoHeight,
    camera::hasPhoto,
    camera::openPhoto
);

Updating images

The availability supplier is checked during rendering. When it returns false, SSGL displays the question-mark placeholder. When it returns true, SSGL displays the registered texture.

Your mod (i.e. camera) remains responsible for uploading new image data to the texture when a new image is captured.

SSGL does not create, register, update, or release dynamic textures for other mods.

Make sure the texture is registered before asking SSGL to render it.