How to Create a GUI in Minecraft Bedrock Scripting
Building a custom graphical user interface (GUI) in Minecraft Bedrock Edition scripting is one of the more rewarding — and misunderstood — parts of the Bedrock Script API. Unlike Java Edition modding, where you have near-complete control over rendering, Bedrock takes a different approach. Understanding what's actually available, and how the system works under the hood, will save you hours of frustration.
What "GUI" Actually Means in Bedrock Scripting
In Bedrock Edition, you don't render custom UI elements directly onto the screen using JavaScript or TypeScript alone. Instead, Bedrock exposes a form-based UI system through the @minecraft/server-ui module. This module lets you display structured dialog boxes — not pixel-level custom interfaces, but functional, interactive screens that players can interact with in-game.
There are three core form types available:
| Form Type | Use Case | Input Options |
|---|---|---|
| ActionFormData | Menus with buttons | Buttons only |
| MessageFormData | Simple dialogs | Two buttons (confirm/cancel style) |
| ModalFormData | Data collection | Text fields, dropdowns, sliders, toggles |
Each of these is a class you instantiate, configure, and then display to a specific player. They're not floating HUDs or custom overlays — they're modal screens, meaning gameplay pauses while the player interacts with them.
Setting Up Your Scripting Environment
Before writing a single line of UI code, your environment needs to be correctly configured. Bedrock scripting runs inside a behavior pack, and your manifest.json must declare the correct dependencies.
You'll need two modules referenced in your manifest:
- @minecraft/server — the core scripting API
- @minecraft/server-ui — the UI forms module
Your manifest dependencies block should reference both with compatible API versions. As of recent stable releases, these modules use a versioning system (e.g., 1.x.x format), and mismatched versions between your manifest and your import statements are one of the most common reasons scripts silently fail.
Your folder structure should look roughly like this:
If you're using TypeScript, you'll also need a build step using the Minecraft scripting toolchain (@minecraft/vanilla-data, esbuild or tsc, etc.). Pure JavaScript works without compilation but loses type safety.
Building a Basic GUI with ActionFormData
Here's a minimal working example of a button-based menu: