Skip to main content
The Essential GUI API provides powerful tools for creating modern, user-friendly interfaces in Minecraft mods using the Elementa framework.

​
Features

​
Core Components

Notifications

Display Windows 10-style notifications to users

Components

Reusable UI components like emulated players and modals

EssentialGUI

Pre-styled base screen with Essential theming

Elementa

Modern declarative UI framework integration

​
Quick Start

​
Creating a Custom GUI

Extend EssentialGUI to create a styled screen: 
import gg.essential.api.gui.EssentialGUI
import gg.essential.elementa.ElementaVersion
import gg.essential.elementa.components.UIText
import gg.essential.elementa.dsl.*

class MyModGUI : EssentialGUI(
    ElementaVersion.V5,
    "My Mod Settings"
) {
    init {
        // Add components to the content container
        UIText("Hello, Essential!").constrain {
            x = 10.pixels
            y = 10.pixels
        } childOf content
    }
}

​
Displaying the GUI

import gg.essential.api.EssentialAPI

// Display your GUI
EssentialAPI.getGuiUtil().openScreen(MyModGUI())

​
EssentialGUI Class

The EssentialGUI class provides a styled base screen with Essential’s dark theme and layout.

​
Constructor Parameters

ParameterTypeDescription
versionElementaVersionElementa version for improved behavior
guiTitleStringTitle displayed in the title bar
newGuiScaleIntGUI scale to use (default: current scale)
restorePreviousGuiOnCloseBooleanRestore previous screen on close
discordActivityDescriptionString?Discord Rich Presence description

​
Key Components

The EssentialGUI provides several pre-configured components: 
class MyGUI : EssentialGUI(ElementaVersion.V5, "My GUI") {
    init {
        // titleBar - The top bar with the title
        // titleText - The title text component
        // content - Main content container (add your UI here)
        // scissorBox - Container for scissoring/clipping
        
        // Add your content
        MyComponent() childOf content
    }
}

​
Customization

Override color methods to customize the theme: 
class CustomThemedGUI : EssentialGUI(ElementaVersion.V5, "Custom") {
    override fun getBackgroundColor() = Color(0x1a1a1a)
    override fun getTitleBackgroundColor() = Color(0x2d2d2d)
    override fun getTextHighlightColor() = Color(0xffffff)
}

​
Back Button

Control the back button visibility: 
backButtonVisible = false // Hide the back button
Override back button behavior: 
override fun backButtonPressed() {
    // Custom logic before closing
    println("Back button pressed!")
    super.backButtonPressed()
}

​
Setting Title Dynamically

setTitle("New Title")

​
GuiRequiresTOS

Implement this interface to require TOS acceptance before opening: 
class MyGUI : EssentialGUI(ElementaVersion.V5, "My GUI"), GuiRequiresTOS {
    // This GUI will only open if the user has accepted the TOS
}

​
Best Practices

Always specify ElementaVersion.V5 (or latest) for improved behavior and bug fixes.
EssentialGUI(ElementaVersion.V5, "My GUI")
Always add your UI components to the content container, not the window or other containers.
MyComponent() childOf content
Use EssentialAPI.getGuiUtil().openScreen() to display screens for proper handling.
EssentialAPI.getGuiUtil().openScreen(MyGUI())
Let users control GUI scale. Use the default scale parameter.
EssentialGUI(
    ElementaVersion.V5,
    newGuiScale = EssentialAPI.getGuiUtil().getGuiScale()
)

​
Next Steps

Notifications

Learn how to display notifications

Components

Use pre-built UI components

Elementa Guide

Learn the Elementa framework

GuiUtil

Explore GUI utilities

Build docs developers (and LLMs) love

Get started for freeTalk to us