Gui example

An example of a GUI.

Welcome to the Absolute Beginners Guide to GUIs. This guide will guide you through several crash courses on creating GUIs and understanding the words behind all of it. GUI stands for Graphical User Interface. GUIs on Roblox are shapes, text, images and other 2D items on your screen that are a part of your Roblox gameplay. An example would be your health bar to the right.

GUIs are easy to make, but to make them interactive requires basic scripting knowledge. It is highly recommended you read some tutorials on scripting in Roblox Lua before you read about GUIs, as they are pretty advanced. However, if this did not discourage you, then I wish you luck in your quest to master GUIs!

You should have the Explorer window and the Properties window open at all times when working with GUIs.

  • To open the Explorer window, go to View > Explorer.
  • To open the Properties window, go to View > Properties.

GUI Instances

In Roblox, each GUI object has an object (like a Part, SpawnLocation, Model, or Humanoid). In fact, there are many objects to make it easy for you to create a GUI for your game. Here are the basic things that are put on your screen. Reading this information is not totally necessary for your success in the tutorial. It helps to know this when creating your own GUI, though.


A ScreenGui is a container for all GUI Instances. ScreenGuis are put into PlayerGuis (to be shown to a specific player) or into the StarterGui, which copies its contents into the PlayerGui of a spawning player (StarterGui is similar to StarterPack). ScreenGuis can be compared to Models. All GUI objects need to be in a ScreenGui to show properly. ScreenGuis are a newer version of GuiMains. ScreenGuis were added in a GUI update to replace (but not delete) GuiMains. It is better to use ScreenGuis, as they are not depreciated.


Frames are simple boxes or lines on your screen. An example of a frame is the salmon-colored box in the image to the top right of this article. Frames can be used to contain other GUI objects. Frames support many properties, including Size, Position, BackgroundColor3, BorderColor3, ZIndex, and more. Be warned - the Size and Position properties are UDim2-type properties and are different from normal properties. You can read more about UDim2 type properties later. BackgroundColor3 and BorderColor3 properties are both Color3 type properties. They are similar to Part's Color property. It also has a BackgroundTransparency property, which functions just like the Transparency of Parts ("0" is visible, "1" is invisible).


A TextLabel is like a Frame, only it can contain text. It has all the properties of Frames, and more. It has a Text property, a TextColor3 property (self-explanatory?), and several Text Alignment and Wrapping properties. To enable Text Wrapping, have the TextWrap property set to true (or checked in the properties window). TextWrap will make the text break to the next line if it does not fit inside the TextLabel itself. If you make the BackgroundTransparency property "1" and set the Size property accordingly, you can wrap the text without much difficulty. An example of a TextLabel is the words "This is a simple GUI!" in the image to the top right of the article.


TextButtons are clones of TextLabels, only there are added events that scripters love to use in their scripts. TextButtons support more mouse interactivity without using HopperBins or Tools. Some new Events are MouseButton1Click, MouseButton1Down, MouseButton1Up, MouseEnter, and MouseLeave. See the TextButton entry in the Object Browser to learn more about the TextButtons properties and events.


An ImageLabel is like a mix of a Decal and a Frame. It shows an image on the user's screen. There is a small drawback to using ImageLabels, though. The image is stretched to the size of the ImageLabel, so if you have a 100 by 100 image on a 200 by 200 ImageLabel, you will notice a loss in quality of the image. The image shown on an ImageLabel is noted by its Image property and functions exactly like the Texture property of Decals. It is recommended that you copy and paste the Texture property of a Decal into an ImageLabel's Image property (using the Properties window). An example of an ImageLabel is the light bulb picture in the image at the top right of this article.


ImageButtons and ImageLabels are just like TextButtons and TextLabels. ImageButtons are just ImageLabel clones with more Events and functionality. There is not much to say about them except to see their entry in the Object Browser and see all of their Events.

Crash Course of UDim2


This shows how the Properties window shows UDim2 properties.

UDim2 is a strange name for a strange concept. There are two main properties that are UDim2 properties: Size and Position. They hold four values: XScale, XOffset, YScale, and YOffset. The image to the right shows how the Properties window displays UDim2 type properties. This is called "brace notation". Note that the braces notation is NOT how you define UDim2 values in scripting! For that, one would use the,xoffset,yscale,yoffset) function! If you use the braces and commas, your script will not work.


When writing about UDim2 type data, you denote UDim2 values by using the braces and commas, as shown to the right as the Properties window does. However, if you know how to script, it is encouraged you to write UDim2 data by stating the Roblox Lua function So, if you did not know scripting but knew about UDim2, you would say {0,150},{0,50}. However, if you did know how to script GUIs, you should state,150,0,50). This is meant to help you practice typing UDim2 values in scripting. Either notation is fine, though!


Scale is a unit that changes as the GUI object's parent changes. If the object is in a ScreenGui, a Scale can be thought of as a "Screen". If you have an object's position as {0.5,0}, {0.5,0}, it's top left corner will be in the dead center of the screen. If an object is inside another GUI object, "1" on the XScale becomes the parent object's width and on the YScale becomes the parent object's height.


Offset is just that - a pixel offset. If an object's position is {0,100}, {0,150}, it will be placed 100 pixels from the left of the screen and 150 pixels from the top of the screen. Using XOffset and YOffset in Size will size the object by pixels. It is recommended you Size objects via XOffset and YOffset, however, using scale can make your GUIs more screen dynamic.

Examples of Common UDim2 Values

Name in Brace Notation in Function Notation
Top Left of Screen {0,0},{0,0},0,0,0)

Middle of Screen {0.5,0},{0.5,0},0,0.5,0)

Bottom Right of Screen {1,0},{1,0},0,1,0)

Top Center of Screen {0.5,0},{0,0},0,0,0)

Tutorial 1: Your first simple GUI

Gui heiarchy

An example hierarchy of a simple GUI.

Okay - you've read about all the lingo on GUIs, it's time to start creating them from scratch. This simple guide will walk you through creating a simple, non-interactive GUI. If you get lost in the hierarchy, use the reference to the right.

Step 1: ScreenGui

Your first step is to make a ScreenGui contain your new GUI. In the Explorer window, find your player GUI. Select it, then go to Insert > Object.. > ScreenGui. You should now have a ScreenGui in your PlayerGui. This is where you will put all your GUI objects. There is nothing to configure with ScreenGuis unless you want to change the Name property to keep you from confusing it with other ScreenGuis (we will only have one ScreenGui, though).

Step 2: Frame

Now, this is where it gets a little more complicated. Select the ScreenGui, and go to Insert > Object... > Frame. A Frame should have been put into your ScreenGui. By default, the default Frame Size and Position is {0,0},{0,0}, so you should not see anything (yet). Look in the Properties window and find the Position field. Note how it can be expanded. Click the little plus sign to the left of the word "Position". The X and Y fields should have popped up. These also can be expanded. In each, it has a Scale and Offset field. We will position this Frame in the center of the screen, so set the XScale and YScale both to 0.5. You still will not see anything, as the Frame's Size is still {0,0},{0,0}. Change the Frame's XOffset to 300 and the YOffset to 250. If you've done everything correctly, you will now see a grey box! However, it is still not in the dead center. Only its top left corner is. To center it exactly, change the Position to {0.5,-150},{0.5,-125}. (XOffset to -150, YOffset to -125). This will subtract half of its width and height from the position, so it will look like it is in the dead center of your screen. Before you go on, try resizing the Roblox window and seeing what's happening to the box. It is good to resize your window to make sure your GUI can be displayed on multiple screen sizes.

Step 3: Coloring the Frame

Coloring the frame is really simple. In the Properties window and with the Frame selected, click the BackgroundColor3 property. A standard color picker dialog should pop up. Pick a lighter color (Salmon was used in the example at the beginning of this tutorial), then click OK. Make sure you pick a color that you can read on! If you want to give the Frame a border color, you can do so.

Step 4: ImageLabel

Now, we will put an image in the Frame. With the Frame selected, go to Insert > Object... > ImageLabel. Nothing should appear, as there is no default image for ImageLabels. Now, you'll need to give the ImageLabel an image to display. For example at the beginning, was used. However, you probably want to use your own image. Put in a dummy brick (just a plain, temporary brick) into your place, nearby. Put a decal of the image you want to put on it. Double click the Decal to select it. In the Properties window, copy its Texture field. Now re-select the ImageLabel. Paste the link of the image into the Image field. Now delete your dummy brick, as you don't need it anymore. Now, if you know the dimensions of your image that you inserted (the example one is 100 by 100), change the size of your ImageLabel to {0,x},{0,y}, where x is the width of the image and y is the height of the image. If you don't know your image's dimensions, play around with the Size until it looks correct. There is a bug that if you have an ImageLabel's Size set to {0,0},{0,0}, it will show the image up-side-down. It fixes as soon as you size it. Now, play around with the XOffset and YOffset of the Position property until the ImageLabel is where you want it. Leave space to add some text.

Step 5: TextLabel

Lastly, you'll be putting some Text on the Frame. Select the Frame, go to Insert > Object.. > TextLabel. Since the default Position of TextLabels is {0,0},{0,0}, and the Text property is "Label", you'll see the word "Label" at the top left corner of your Frame. Change the Text property of the TextLabel to your choosing, as this is what will be displayed. In TextLabels, you can't go to the next line without making another TextLabel (unless you use the Text Wrapping feature, which is too advanced for right now). Keep the text small enough so you can fit it in the Frame. Play around with the Position property until it is positioned where you like.

Step 6: StarterGui

Now, if you don't see a StarterGui in the Explorer window, go to Insert > Service > Starter Gui. Now, copy your ScreenGui by selecting it, then hitting CTRL + V. Right-click the StarterGui and choose "Paste Into". Now kill your player so you respawn (jump off a cliff, use a reset tool, explosions, as long as you respawn). If you did everything correctly, when you respawn you should have your GUI shown to you, and anyone else who visits your place.

If you can see your new GUI, congratulations! You have completed the tutorial.

The GUI you have created in this tutorial is used for Tutorial 4: Show/Hide GUIs.

Tutorial 2: Your first interactive GUI

Gui button hierarchy

An example hierarchy of a button GUI.

Now, having just a GUI is boring. After you read or look at everything on a GUI, it becomes useless unless there is some interactivity on it. For this tutorial, you will make a simple Reset Button in the form of a GUI. This is similar to creating a killing brick and is a lot simpler than making a reset tool. If you get confused about the hierarchy, use the example to the right.

You might want to have the Output window open if you are writing your own script and not copying and pasting the given script.

Note that you will be making an interactive GUI - so this includes some basic skills for working with scripts (writing, running, debugging, etc.).

Step 1: ScreenGui

Insert a ScreenGui into your PlayerGui. If you don't know-how, see Step 1 of the "Your first Simple GUI" heading above. It should be pretty simple to do and remember.

Step 2: TextButton

To make the button, we need to have an object that can display text and have mouse interactivity. This calls for a TextButton, so select your ScreenGui and go to Insert > Object... > TextButton. Position the TextButton to about {0,50},{0,150}. Make sure that you have enough room at the top, as in Online mode the Chat will be there. Size the TextButton to {0,50},{0,25}. Change the TextButton's Text to "Reset" or some other descriptive word. Change it's BackgroundColor3, BorderColor3, and TextColor3. You should now have something that looks like a button. Put your mouse over it and try clicking it. It should have an automatic color change built into it by Roblox. However, you can turn this effect off by switching the AutoButtonColor property to false in the Properties window. Nothing happens when you click it, though.

Step 3: Script

Now, select your TextButton and insert Script into it (Select it, then go to Insert > Object... > Script). For the code, use the following:

button = script.Parent
player = button.Parent.Parent.Parent

function onClick()


Let's examine that code. Line 1 defines the "button" variable as the TextButton. Line 2 defines the "player" variable as the Player object (the object that holds your Backpack, PlayerGui, leaderstats, etc.) Lines 4 to 6 define the onClick function, which does nothing but kills the player by breaking its joints and display the text "Reseted!" into the Output (if you have that window open). Remember that the Player object has an unchanging Character property that points right to the Character it controls. The last line simply connects the MouseButton1Click event to the function onClick so that it kills the player when the button is clicked.

Before you click your button, copy the ScreenGui and put a copy of it into your StarterGui. If your button works and you die, that's good, but your PlayerGui is cleared and you will lose your work! Make sure you save it by putting a copy into the StarterGui so you can spawn with your exact same work. Dying while working on a GUI is a great way to lose all of your work. Now you may click your button.

If you died, you have successfully completed this tutorial!

Tutorial 3: Disco GUI!

This will be very similar to the disco brick script you may have learned when learning scripting. Believe it or not, there are many more colors you can make for GUIs than Parts, as Parts are limited to BrickColor values, which there are not as many. GUIs use Color3, so you can make many more colors.

Warning: If you do use this in your game, you should put a warning in your game's description of flashing lights that can cause epilepsy. If you'd rather not do this, you must make your GUI not flash as fast.

Step 1: ScreenGui

Create a ScreenGui as you did in the last two tutorials. If you need help, see Step 1 in Tutorial 1: Your first simple GUI. This should now be a standard task for you, ask every time you make a GUI you will do this.

Step 2: Frame

For this Disco GUI, we will have a transparent Frame cover the entire screen and change colors. With your ScreenGui selected, go to Insert > Object... > Frame. For this frame, set it's Size to {1,0},{1,0}. This will make your entire screen grey, as the Frame's default color is a non-transparent grey color (Yuck). Change the Frame's BackgroundTransparency property to 0.75, as we want them to see through it. We don't need a border on the Frame so change the BorderSizePixel property to "0".

Step 3: Script

Insert a Script into your frame. Use the following code for your script.

frame = script.Parent

while true do
     local color =, math.random(), math.random())
     frame.BackgroundColor3 = color

Let's again examine this script. Line 1 defines the "frame" variable as the Frame we created (the script's parent). Lines 3 to 7 are a continuous loop. Line 4 waits for a half-second (you may change this to be faster or slower). Line 5 defines a temporary variable called "color" to a random color. Line 6 sets the frame's BackgroundColor3 to the random color gotten in line 5. The script would then repeat back to line 4.

Run the script. If you see that the color is changing, congratulations! You have successfully completed this tutorial.

Tutorial 4: Show/Hide GUIs

Gui showhide hierarchy

An example hierarchy of the show/hide GUI.

For this tutorial, you will need a pre-made GUI, such as the one made in Tutorial 1: Your first simple GUI. In this tutorial, you will learn how to show and hide a GUI. It helps to have the Output window open if you are writing the code and not copying and pasting. Use the reference to the right if you get confused with the hierarchy. The image to the right uses the GUI created in Tutorial 1: Your first simple GUI.

Step 1: Renaming

Instead of making a new GUI, we will take your old GUI and add on to it. Take your GUI you already have and change the Frame's name to "Container". This name is more descriptive than just "Frame", and it won't confuse you.

Step 2: TextButton

Select the ScreenGui and go to Insert > Object... > TextButton. Position the TextButton slightly under your other GUI. Change the Text property to "Show/Hide". Size it to about {0,60},{0,25} and color it as you please by changing the BackgroundColor3, BorderColor3 and TextColor3 properties. Make sure you can click it and that you think it looks good before continuing.

Step 3: Script

Add a script by selecting your TextButton and going to Insert > Object... > Script. Use the following code for the Script.

button = script.Parent
container = button.Parent.Container

function onClick()
     container.Visible = not container.Visible


Let's analyze this script. Line 1 defines the "button" variable as the TextButton, and line 2 does define the "container" variable as the Frame that Contains your GUI stuff. If the Visible property of a GUI object is false, that object and all of its children are not shown. Lines 4 to 6 define the "onClick" function. All that the function does is toggle the Visible property of your container. Note how the "not" keyword will change true values to false and false values back to true. Line 8 simply connects the MouseButton1Click event of the TextButton to the onClick function.

Click your button several times. If your GUI flashes on and off your screen, congratulations! You have successfully completed the tutorial!

Community content is available under CC-BY-SA unless otherwise noted.