TextLabel
A TextLabel renders a rectangle, like a Frame, with styled text. The rectangle can be used to define text boundaries, text scaling (TextLabel.TextScaled) and wrapping (TextLabel.TextWrapped, TextLabel.TextXAlignment, TextLabel.TextYAlignment).
This class contains properties that control the display of the text, such as TextLabel.Font and TextLabel.TextColor3. All text rendered by a single text label will have the same visual properties; multiple TextLabel objects must be used in order to render multiple styles of text. To display only text and hide the rectangle, set GuiObject.BackgroundTransparency to 1.
TextService:GetTextSize() can be used to get the size (bounds) of text that would be rendered in a TextLabel given a font size, font, and frame size.
A UITextSizeConstraint object can be used to constrain the size of text with TextLabel.TextScaled enabled. It is recommended that the size of text is no lower than 9, otherwise it may not be visible to most users.
Code Samples
-- Place this code in a LocalScript within a TextLabel/TextButton
local textLabel = script.Parent
-- Some colors we'll use with TextColor3
local colorNormal = Color3.new(0, 0, 0) -- black
local colorSoon = Color3.new(1, 0.5, 0.5) -- red
local colorDone = Color3.new(0.5, 1, 0.5) -- green
-- Loop infinitely
while true do
-- Count backwards from 10 to 1
for i = 10, 1, -1 do
-- Set the text
textLabel.Text = "Time: " .. i
-- Set the color based on how much time is left
if i > 3 then
textLabel.TextColor3 = colorNormal
else
textLabel.TextColor3 = colorSoon
end
task.wait(1)
end
textLabel.Text = "GO!"
textLabel.TextColor3 = colorDone
task.wait(2)
end
local ReplicatedStorage = game:GetService("ReplicatedStorage")
-- Place a StringValue called "GameState" in the ReplicatedStorage
local vGameState = ReplicatedStorage:WaitForChild("GameState")
-- Place this code in a TextLabel
local textLabel = script.Parent
-- Some colors we'll use with TextColor3
local colorNormal = Color3.new(0, 0, 0) -- black
local colorCountdown = Color3.new(1, 0.5, 0) -- orange
local colorRound = Color3.new(0.25, 0.25, 1) -- blue
-- We'll run this function to update the TextLabel as the state of the
-- game changes.
local function update()
-- Update the text
textLabel.Text = "State: " .. vGameState.Value
-- Set the color of the text based on the current game state
if vGameState.Value == "Countdown" then
textLabel.TextColor3 = colorCountdown
elseif vGameState.Value == "Round" then
textLabel.TextColor3 = colorRound
else
textLabel.TextColor3 = colorNormal
end
end
-- Pattern: update once when we start and also when vGameState changes
-- We should always see the most updated GameState.
update()
vGameState.Changed:Connect(update)
Summary
Properties
A copy of TextLabel.Text that contains exactly what is being rendered by the TextLabel.
Determines the font used to render text.
Determines the font used to render text.
Scales the spacing between lines of text in the TextLabel.
Sets whether a TextLabel should be GuiBase2d.Localize or not.
The maximum number of graphemes the TextLabel can show.
Determines whether the TextLabel renders the TextLabel.Text string using rich text formatting.
Determines the string rendered by the UI element.
The size of a UI element's text in offsets.
This property determines the color of rendered text.
Enables when rendered text content does not fit within the UI element's space.
Determines whether text in a UI element is scaled to fill the UI element.
Determine the line height of text in offsets.
Determines the color of the text stroke (outline).
Determines the transparency of the text stroke (outline).
Determines the transparency of rendered text.
Controls the truncation of the text displayed in this TextLabel.
Determines if text wraps to multiple lines within the GUI element space, truncating excess text.
Determines the horizontal alignment of rendered text.
Determines the vertical alignment of rendered text.
Determines whether this UI element sinks input.
Determines the origin point of a GuiObject, relative to its absolute size.
Determines whether resizing occurs based on child content.
Determines the GuiObject background color.
Determines the transparency of the GuiObject background and border.
Determines the color of the GuiObject border.
Determines in what manner the GuiObject border is laid out relative to its dimensions.
Determines the pixel width of the GuiObject border.
Determines if descendant GuiObjects outside of the bounds of a parent GUI element should render.
Determines whether the player's mouse is being actively pressed on the GuiObject or not.
Determines whether the GuiButton can be interacted with or not, or if the GuiState of the GuiObject is changing or not.
Controls the sort order of the GuiObject when used with a UIGridStyleLayout.
Sets the GuiObject which will be selected when the gamepad selector is moved downward.
Sets the GuiObject which will be selected when the gamepad selector is moved to the left.
Sets the GuiObject which will be selected when the gamepad selector is moved to the right.
Sets the GuiObject which will be selected when the gamepad selector is moved upward.
Determines the pixel and scalar position of the GuiObject.
Determines the number of degrees by which the GuiObject is rotated.
Determine whether the GUI can be selected by a gamepad.
Overrides the default selection adornment used for gamepads.
The order of GuiObjects selected by the gamepad UI selection.
Determines the pixel and scalar size of the GuiObject.
Sets the Size axes that the GuiObject will be based on, relative to the size of its parent.
A mixed property of BackgroundTransparency and TextTransparency.
Determines whether the GuiObject and its descendants will be rendered.
Determines the order in which a GuiObject renders relative to others.
Describes the actual screen position of a UI element, in pixels.
Describes the actual screen rotation of a UI element, in degrees.
Describes the actual screen size of a UI element, in pixels.
When set to true, localization will be applied to this GuiBase2d and its descendants.
A reference to a LocalizationTable to be used to apply automated localization to this GuiBase2d and its descendants.
Customizes gamepad selection behavior in the down direction.
Customizes gamepad selection behavior in the left direction.
Customizes gamepad selection behavior in the right direction.
Customizes gamepad selection behavior in the up direction.
Allows customization of gamepad selection movement.
Methods
Methods inherited from GuiObject- TweenPosition(endPosition : UDim2,easingDirection : Enum.EasingDirection,easingStyle : Enum.EasingStyle,time : number,override : bool,callback : function):bool
Smoothly moves a GUI to a new UDim2.
- TweenSize(endSize : UDim2,easingDirection : Enum.EasingDirection,easingStyle : Enum.EasingStyle,time : number,override : bool,callback : function):bool
Smoothly resizes a GUI to a new UDim2.
- TweenSizeAndPosition(endSize : UDim2,endPosition : UDim2,easingDirection : Enum.EasingDirection,easingStyle : Enum.EasingStyle,time : number,override : bool,callback : function):bool
Smoothly moves a GUI to a new size and position.
Events
Events inherited from GuiObjectFired when a user begins interacting via a Human-Computer Interface device (Mouse button down, touch begin, keyboard button down, etc).
Fired when a user changes how they're interacting via a Human-Computer Interface device (Mouse button down, touch begin, keyboard button down, etc).
Fired when a user stops interacting via a Human-Computer Interface device (Mouse button down, touch begin, keyboard button down, etc).
Fires when a user moves their mouse into a GUI element.
Fires when a user moves their mouse out of a GUI element.
Fires whenever a user moves their mouse while it is inside a GUI element.
Fires when a user scrolls their mouse wheel back when the mouse is over a GUI element.
Fires when a user scrolls their mouse wheel forward when the mouse is over a GUI element.
Fired when the GuiObject is being focused on with the Gamepad selector.
Fired when the Gamepad selector stops focusing on the GuiObject.
Fires when the player starts, continues and stops long-pressing the UI element.
- TouchPan(touchPositions : Array,totalTranslation : Vector2,velocity : Vector2,state : Enum.UserInputState):RBXScriptSignal
Fires when the player moves their finger on the UI element.
- TouchPinch(touchPositions : Array,scale : number,velocity : number,state : Enum.UserInputState):RBXScriptSignal
Fires when the player performs a pinch or pull gesture using two fingers on the UI element.
- TouchRotate(touchPositions : Array,rotation : number,velocity : number,state : Enum.UserInputState):RBXScriptSignal
Fires when the player performs a rotation gesture using two fingers on the UI element.
Fires when the player performs a swipe gesture on the UI element.
Fires when the player performs a tap gesture on the UI element.
- SelectionChanged(amISelected : bool,previousSelection : GuiObject,newSelection : GuiObject):RBXScriptSignal
Fires when the gamepad selection moves to, leaves, or changes within the connected GuiBase2d or any descendant GuiObjects.
Properties
ContentText
This property provides a copy of TextLabel.Text that contains exactly what is being rendered by the TextLabel. This is useful for eliminating style tags used for rich text.
Example
When TextLabel.RichText is enabled, the TextLabel.ContentText property shows the text as it appears to the player.
RichText | Text | ContentText |
---|---|---|
false | <b>Hello,<br/> world!</b> | <b>Hello,<br/> world!</b> |
true | <b>Hello,<br/> world!</b> | Hello, world! |
Font
The Font property selects one of several pre-defined fonts with which the UI element will render its text. Some fonts have bold, italic and/or light variants (as there is no font-weight or font-style properties).
With the exception of the "Legacy" font, each font will render text with the line height equal to the TextLabel.TextSize property. The "Code" font is the only monospace font. It has the unique property that each character has the exact same width and height ratio of 1:2. The width of each character is approximately half the TextLabel.TextSize property.
This property is kept in sync with the TextLabel.FontFace property. When setting Font, the FontFace will be set to Font.fromEnum(value).
Code Samples
local textLabel = script.Parent
while true do
-- Iterate over all the different fonts
for _, font in pairs(Enum.Font:GetEnumItems()) do
textLabel.Font = font
textLabel.Text = font.Name
task.wait(1)
end
end
local frame = script.Parent
-- Create a TextLabel displaying each font
for _, font in pairs(Enum.Font:GetEnumItems()) do
local textLabel = Instance.new("TextLabel")
textLabel.Name = font.Name
-- Set the text properties
textLabel.Text = font.Name
textLabel.Font = font
-- Some rendering properties
textLabel.TextSize = 24
textLabel.TextXAlignment = Enum.TextXAlignment.Left
-- Size the frame equal to the height of the text
textLabel.Size = UDim2.new(1, 0, 0, textLabel.TextSize)
-- Add to the parent frame
textLabel.Parent = frame
end
-- Layout the frames in a list (if they aren't already)
if not frame:FindFirstChildOfClass("UIListLayout") then
local uiListLayout = Instance.new("UIListLayout")
uiListLayout.Parent = frame
end
FontFace
The FontFace property is similar to the Font property, but allows setting fonts that don't exist in the Font enum.
This property is kept in sync with the TextLabel.Font property. When setting FontFace, the Font is set to the corresponding enum value, or to Enum.Font.Unknown if there are no matches.
LineHeight
Controls the height of lines, as a multiple of the font's em square size, by scaling the spacing between lines of text in the TextLabel. Valid values range from 1.0 to 3.0, defaulting to 1.0.
MaxVisibleGraphemes
This property controls the maximum number of graphemes (or units of text) that are shown on the TextLabel. It is primarily provided as an easy way to create a "typewriter effect" where the characters appear one at a time.
Changing the property does not change the position or size of the visible graphemes - the layout will be calculated as if all graphemes are visible.
Setting the property to -1 disables the limit and shows the entirety of the TextLabel.Text.
Code Samples
local TweenService = game:GetService("TweenService")
local textObject = script.Parent
local tweenInfo = TweenInfo.new(
4, -- it takes 4 seconds for the effect to complete
Enum.EasingStyle.Sine, -- typing starts fast and slows near the end
Enum.EasingDirection.Out
)
local tween = TweenService:Create(textObject, tweenInfo, {
-- Final value should be the total grapheme count
MaxVisibleGraphemes = utf8.len(textObject.ContentText),
})
tween:Play()
tween.Completed:Wait()
-- Reset the value so it can be tweened again
textObject.MaxVisibleGraphemes = -1
OpenTypeFeatures
OpenTypeFeaturesError
RichText
This property determines whether the TextLabel renders the TextLabel.Text string using rich text formatting. Rich text uses simple markup tags to style sections of the string in bold, italics, specific colors, and more.
To use rich text, simply include formatting tags in the TextLabel.Text string.
Text
The Text property determines the content rendered by the UI element. The visual properties of the string rendered to the screen is determined by TextLabel.TextColor3, TextLabel.TextTransparency, TextLabel.TextSize, TextLabel.Font, TextLabel.TextScaled, TextLabel.TextWrapped, TextLabel.TextXAlignment and TextLabel.TextYAlignment.
It is possible to render emoji (for example, 😃) and other symbols. These special symbols aren't affected by the TextLabel.TextColor3 property. These can be pasted into Script and LocalScript objects, as well as the field within the Properties window.
This property may contain newline characters, however, it is not possible to type newline characters within the Properties window. Similarly, this property may contain a tab character, but it will render as a space instead.
Code Samples
local TweenService = game:GetService("TweenService")
local textLabel = script.Parent
local content = {
"Welcome to my game!",
"Be sure to have fun!",
"Please give suggestions!",
"Be nice to other players!",
"Don't grief other players!",
"Check out the shop!",
"Tip: Don't die!",
}
local tweenInfo = TweenInfo.new(1, Enum.EasingStyle.Sine, Enum.EasingDirection.InOut)
local RNG = Random.new()
local fadeIn = TweenService:Create(textLabel, tweenInfo, {
TextTransparency = 0,
})
local fadeOut = TweenService:Create(textLabel, tweenInfo, {
TextTransparency = 1,
})
local lastIndex
while true do
-- Step 0: Fade out before doing anything
fadeOut:Play()
task.wait(tweenInfo.Time)
-- Step 1: pick content that wasn't the last displayed
local index
repeat
index = RNG:NextInteger(1, #content)
until lastIndex ~= index
-- Make sure we don't show the same thing next time
lastIndex = index
-- Step 2: show the content
textLabel.Text = content[index]
fadeIn:Play()
task.wait(tweenInfo.Time + 1)
end
local textLabel = script.Parent
textLabel.Text = "Kaboom!"
while true do
for size = 5, 100, 5 do
textLabel.TextSize = size
textLabel.TextTransparency = size / 100
task.wait()
end
task.wait(1)
end
local frame = script.Parent
-- Create a TextLabel displaying each font
for _, font in pairs(Enum.Font:GetEnumItems()) do
local textLabel = Instance.new("TextLabel")
textLabel.Name = font.Name
-- Set the text properties
textLabel.Text = font.Name
textLabel.Font = font
-- Some rendering properties
textLabel.TextSize = 24
textLabel.TextXAlignment = Enum.TextXAlignment.Left
-- Size the frame equal to the height of the text
textLabel.Size = UDim2.new(1, 0, 0, textLabel.TextSize)
-- Add to the parent frame
textLabel.Parent = frame
end
-- Layout the frames in a list (if they aren't already)
if not frame:FindFirstChildOfClass("UIListLayout") then
local uiListLayout = Instance.new("UIListLayout")
uiListLayout.Parent = frame
end
local textLabel = script.Parent
-- This text wrapping demo is best shown on a 200x50 px rectangle
textLabel.Size = UDim2.new(0, 200, 0, 50)
-- Some content to spell out
local content = "Here's a long string of words that will "
.. "eventually exceed the UI element's width "
.. "and form line breaks. Useful for paragraphs "
.. "that are really long."
-- A function that will spell text out two characters at a time
local function spellTheText()
-- Iterate from 1 to the length of our content
for i = 1, content:len() do
-- Get a substring of our content: 1 to i
textLabel.Text = content:sub(1, i)
-- Color the text if it doesn't fit in our box
if textLabel.TextFits then
textLabel.TextColor3 = Color3.new(0, 0, 0) -- Black
else
textLabel.TextColor3 = Color3.new(1, 0, 0) -- Red
end
-- Wait a brief moment on even lengths
if i % 2 == 0 then
task.wait()
end
end
end
while true do
-- Spell the text with scale/wrap off
textLabel.TextWrapped = false
textLabel.TextScaled = false
spellTheText()
task.wait(1)
-- Spell the text with wrap on
textLabel.TextWrapped = true
textLabel.TextScaled = false
spellTheText()
task.wait(1)
-- Spell the text with text scaling on
-- Note: Text turns red (TextFits = false) once text has to be
-- scaled down in order to fit within the UI element.
textLabel.TextScaled = true
-- Note: TextWrapped is enabled implicitly when TextScaled = true
--textLabel.TextWrapped = true
spellTheText()
task.wait(1)
end
local textLabel = script.Parent
local moods = {
["happy"] = "😃",
["sad"] = "😢",
["neutral"] = "😐",
["tired"] = "😫",
}
while true do
for mood, face in pairs(moods) do
textLabel.Text = "I am feeling " .. mood .. "! " .. face
task.wait(1)
end
end
TextBounds
The read-only property TextBounds reflects the absolute size of rendered text in offsets. In other words, if you were to try to fit text into a rectangle, this property would reflect the minimum dimensions of the rectangle you would need in order to fit the text.
Using TextService:GetTextSize(), you can predict what TextBounds will be on a TextLabel given a string, TextLabel.Font, TextLabel.TextSize and frame size.
Code Samples
local textBox = script.Parent
-- The smallest the TextBox will go
local minWidth, minHeight = 10, 10
-- Set alignment so our text doesn't wobble a bit while we type
textBox.TextXAlignment = Enum.TextXAlignment.Left
textBox.TextYAlignment = Enum.TextYAlignment.Top
local function updateSize()
textBox.Size = UDim2.new(0, math.max(minWidth, textBox.TextBounds.X), 0, math.max(minHeight, textBox.TextBounds.Y))
end
textBox:GetPropertyChangedSignal("TextBounds"):Connect(updateSize)
TextColor3
This property determines the color of all the text rendered by a GUI element. This property along with TextLabel.Font, TextLabel.TextSize and TextLabel.TextTransparency will determine the visual properties of text. Text is rendered after the text stroke (TextLabel.TextStrokeColor3).
It's important that text is easily read by players! Be sure to choose colors with little-to-no saturation, like white, grey, or black. Make sure the color of your text is contrasted by the TextLabel.BackgroundColor3 of the GUI element. If the element has a transparent background, try applying a black TextLabel.TextStrokeColor3 to help contrast the text with the 3D world behind it.
Code Samples
local textBox = script.Parent
local function hasVowels(str)
return str:lower():find("[aeiou]")
end
local function onTextChanged()
local text = textBox.Text
-- Check for vowels
if hasVowels(text) then
textBox.TextColor3 = Color3.new(0, 0, 0) -- Black
else
textBox.TextColor3 = Color3.new(1, 0, 0) -- Red
end
end
textBox:GetPropertyChangedSignal("Text"):Connect(onTextChanged)
-- Place this code in a LocalScript inside a TextBox
local textBox = script.Parent
local secretWord = "roblox"
local colorNormal = Color3.new(1, 1, 1) -- white
local colorWrong = Color3.new(1, 0, 0) -- red
local colorCorrect = Color3.new(0, 1, 0) -- green
-- Initialize the state of the textBox
textBox.ClearTextOnFocus = true
textBox.Text = ""
textBox.Font = Enum.Font.Code
textBox.PlaceholderText = "What is the secret word?"
textBox.BackgroundColor3 = colorNormal
local function onFocused()
textBox.BackgroundColor3 = colorNormal
end
local function onFocusLost(enterPressed, _inputObject)
if enterPressed then
local guess = textBox.Text
if guess == secretWord then
textBox.Text = "ACCESS GRANTED"
textBox.BackgroundColor3 = colorCorrect
else
textBox.Text = "ACCESS DENIED"
textBox.BackgroundColor3 = colorWrong
end
else
-- The player stopped editing without pressing Enter
textBox.Text = ""
textBox.BackgroundColor3 = colorNormal
end
end
textBox.FocusLost:Connect(onFocusLost)
textBox.Focused:Connect(onFocused)
-- Place this code in a LocalScript within a TextLabel/TextButton
local textLabel = script.Parent
-- Some colors we'll use with TextColor3
local colorNormal = Color3.new(0, 0, 0) -- black
local colorSoon = Color3.new(1, 0.5, 0.5) -- red
local colorDone = Color3.new(0.5, 1, 0.5) -- green
-- Loop infinitely
while true do
-- Count backwards from 10 to 1
for i = 10, 1, -1 do
-- Set the text
textLabel.Text = "Time: " .. i
-- Set the color based on how much time is left
if i > 3 then
textLabel.TextColor3 = colorNormal
else
textLabel.TextColor3 = colorSoon
end
task.wait(1)
end
textLabel.Text = "GO!"
textLabel.TextColor3 = colorDone
task.wait(2)
end
local ReplicatedStorage = game:GetService("ReplicatedStorage")
-- Place a StringValue called "GameState" in the ReplicatedStorage
local vGameState = ReplicatedStorage:WaitForChild("GameState")
-- Place this code in a TextLabel
local textLabel = script.Parent
-- Some colors we'll use with TextColor3
local colorNormal = Color3.new(0, 0, 0) -- black
local colorCountdown = Color3.new(1, 0.5, 0) -- orange
local colorRound = Color3.new(0.25, 0.25, 1) -- blue
-- We'll run this function to update the TextLabel as the state of the
-- game changes.
local function update()
-- Update the text
textLabel.Text = "State: " .. vGameState.Value
-- Set the color of the text based on the current game state
if vGameState.Value == "Countdown" then
textLabel.TextColor3 = colorCountdown
elseif vGameState.Value == "Round" then
textLabel.TextColor3 = colorRound
else
textLabel.TextColor3 = colorNormal
end
end
-- Pattern: update once when we start and also when vGameState changes
-- We should always see the most updated GameState.
update()
vGameState.Changed:Connect(update)
TextDirection
TextFits
The TextFits is a read-only property that is false if TextLabel.Text content does not fit within the GuiBase2d.AbsoluteSize when rendered. If TextLabel.TextWrapped is true, a false value indicates that some text is truncated and not rendering. Otherwise, it indicates if the line of text is rendering outside the UI element's rectangle. If TextLabel.TextScaled is enabled, this property will be disabled when text must be scaled down in order to fit.
Code Samples
local textLabel = script.Parent
-- This text wrapping demo is best shown on a 200x50 px rectangle
textLabel.Size = UDim2.new(0, 200, 0, 50)
-- Some content to spell out
local content = "Here's a long string of words that will "
.. "eventually exceed the UI element's width "
.. "and form line breaks. Useful for paragraphs "
.. "that are really long."
-- A function that will spell text out two characters at a time
local function spellTheText()
-- Iterate from 1 to the length of our content
for i = 1, content:len() do
-- Get a substring of our content: 1 to i
textLabel.Text = content:sub(1, i)
-- Color the text if it doesn't fit in our box
if textLabel.TextFits then
textLabel.TextColor3 = Color3.new(0, 0, 0) -- Black
else
textLabel.TextColor3 = Color3.new(1, 0, 0) -- Red
end
-- Wait a brief moment on even lengths
if i % 2 == 0 then
task.wait()
end
end
end
while true do
-- Spell the text with scale/wrap off
textLabel.TextWrapped = false
textLabel.TextScaled = false
spellTheText()
task.wait(1)
-- Spell the text with wrap on
textLabel.TextWrapped = true
textLabel.TextScaled = false
spellTheText()
task.wait(1)
-- Spell the text with text scaling on
-- Note: Text turns red (TextFits = false) once text has to be
-- scaled down in order to fit within the UI element.
textLabel.TextScaled = true
-- Note: TextWrapped is enabled implicitly when TextScaled = true
--textLabel.TextWrapped = true
spellTheText()
task.wait(1)
end
TextScaled
Rather than using TextScaled, we recommend you consider using AutomaticSize, a new method to dynamically size UI that will give you the best visual result possible.
The TextScaled property determines whether text is scaled so that it fills the entire UI element's space. When this is enabled, TextLabel.TextSize is ignored and TextLabel.TextWrapped is automatically enabled. This property is useful for text-rendering UI elements within BillboardGuis.
When this property is used for screen-space UI, it may be desirable to use a UITextSizeConstraint to restrict the range of possible text sizes.
TextScaled and AutomaticSize
It's recommended that developers avoid usage of TextScaled and adjust UI to take advantage of the AutomaticSize property instead. Here are the core differences between the two properties:
- TextScaled scales the content (text) to accommodate the UI. Without careful consideration, some text may become unreadable if scaled too small.
- AutomaticSize resizes the UI to accommodate content.
With AutomaticSize, you're able to adjust your UI to accommodate the content (text) while maintaining a consistent font size. For more information on how to use automatic sizing, see the UI Automatic Size article.
We suggest that you don't apply both TextScaled and AutomaticSize on the same UI object. If you apply both properties:
- AutomaticSize determines the maximum amount of available space that a GuiObject can use (in this case, text)
- TextScaled uses the available space determined by AutomaticSize, to scale the font size to fit the available space, which will expand up to the maximum font size (100), if there are no size constraints
- The end result will be: text goes to 100 font size and the UI object will expand to fit that text
Using both AutomaticSize and TextScaled at the same time can result in significant scaling differences than when AutomaticSize is off.
Code Samples
local textLabel = script.Parent
-- This text wrapping demo is best shown on a 200x50 px rectangle
textLabel.Size = UDim2.new(0, 200, 0, 50)
-- Some content to spell out
local content = "Here's a long string of words that will "
.. "eventually exceed the UI element's width "
.. "and form line breaks. Useful for paragraphs "
.. "that are really long."
-- A function that will spell text out two characters at a time
local function spellTheText()
-- Iterate from 1 to the length of our content
for i = 1, content:len() do
-- Get a substring of our content: 1 to i
textLabel.Text = content:sub(1, i)
-- Color the text if it doesn't fit in our box
if textLabel.TextFits then
textLabel.TextColor3 = Color3.new(0, 0, 0) -- Black
else
textLabel.TextColor3 = Color3.new(1, 0, 0) -- Red
end
-- Wait a brief moment on even lengths
if i % 2 == 0 then
task.wait()
end
end
end
while true do
-- Spell the text with scale/wrap off
textLabel.TextWrapped = false
textLabel.TextScaled = false
spellTheText()
task.wait(1)
-- Spell the text with wrap on
textLabel.TextWrapped = true
textLabel.TextScaled = false
spellTheText()
task.wait(1)
-- Spell the text with text scaling on
-- Note: Text turns red (TextFits = false) once text has to be
-- scaled down in order to fit within the UI element.
textLabel.TextScaled = true
-- Note: TextWrapped is enabled implicitly when TextScaled = true
--textLabel.TextWrapped = true
spellTheText()
task.wait(1)
end
TextSize
The TextSize property determines the height in offsets of one line of rendered text. The unit is in offsets, not points (which is used in most document editing programs). It's worth noting that the "Legacy" font's line height behaves differently, and won't match this property exactly.
This property and TextLabel.TextColor3, TextLabel.TextTransparency, TextLabel.TextStrokeColor3 and TextLabel.TextStrokeTransparency each influence the way text is rendered.
This property supersedes TextLabel.FontSize since it is a number and not an enum. Internally, Roblox uses several sets of pre-rendered character images for each size of each font. It chooses the closest size to TextSize, then scales that set of character images to render text. Before the introduction of this property, you could only pick from the pre-rendered sizes, which were listed by the Enum.FontSize enum.
Code Samples
local textLabel = script.Parent
textLabel.Text = "Kaboom!"
while true do
for size = 5, 100, 5 do
textLabel.TextSize = size
textLabel.TextTransparency = size / 100
task.wait()
end
task.wait(1)
end
TextStrokeColor3
The TextStrokeColor3 property sets the color of the stroke, or outline, of rendered text. This property and TextLabel.TextStrokeTransparency determine the visual properties of the text stroke.
Text stroke is rendered before normal text and is simply 4 renderings of the same text in +/- 1 pixel offsets in each direction. Text stroke rendering works independently and identically to TextLabel.TextColor3 and TextLabel.TextTransparency.
Code Samples
local textLabel = script.Parent
-- How fast the highlight ought to blink
local freq = 2
-- Set to yellow highlight color
textLabel.TextStrokeColor3 = Color3.new(1, 1, 0)
while true do
-- math.sin oscillates from -1 to 1, so we change the range to 0 to 1:
local transparency = math.sin(workspace.DistributedGameTime * math.pi * freq) * 0.5 + 0.5
textLabel.TextStrokeTransparency = transparency
task.wait()
end
TextStrokeTransparency
The TextStrokeTransparency property sets the transparency of the stroke, or outline, of rendered text. This property and TextLabel.TextStrokeColor3 determine the visual properties of the text stroke.
Text stroke is rendered before normal text and is simply 4 renderings of the same text in +/- 1 pixel offsets in each direction. Text stroke rendering works independently and identically to TextLabel.TextColor3 and TextLabel.TextTransparency. Since text stroke is simply multiple renderings of the same transparency, this property is essentially multiplicative on itself four times over (e.g. a TextStrokeTransparency of 0.5 appears about the same as TextTransparency of 0.0625, or 0.5^4). Therefore, it's recommended to set TextStrokeTransparency to a value in the range of 0.75 to 1 for more a more subtle effect.
Code Samples
local textLabel = script.Parent
-- How fast the highlight ought to blink
local freq = 2
-- Set to yellow highlight color
textLabel.TextStrokeColor3 = Color3.new(1, 1, 0)
while true do
-- math.sin oscillates from -1 to 1, so we change the range to 0 to 1:
local transparency = math.sin(workspace.DistributedGameTime * math.pi * freq) * 0.5 + 0.5
textLabel.TextStrokeTransparency = transparency
task.wait()
end
TextTransparency
The TextColor3 property determines the transparency of all the text rendered by a UI element. This property along with TextLabel.Font, TextLabel.TextSize and TextLabel.TextColor3 will determine the visual properties of text. Text is rendered after the text stroke (TextLabel.TextStrokeTransparency).
Fading text in using a numeric for-loop is a fantastic way to draw a player's attention to text appearing on screen.
-- Count backwards from 1 to 0, decrementing by 0.1for i = 1, 0, -0.1 dotextLabel.TextTransparency = itask.wait(0.1)end
Code Samples
local TweenService = game:GetService("TweenService")
local textLabel = script.Parent
local content = {
"Welcome to my game!",
"Be sure to have fun!",
"Please give suggestions!",
"Be nice to other players!",
"Don't grief other players!",
"Check out the shop!",
"Tip: Don't die!",
}
local tweenInfo = TweenInfo.new(1, Enum.EasingStyle.Sine, Enum.EasingDirection.InOut)
local RNG = Random.new()
local fadeIn = TweenService:Create(textLabel, tweenInfo, {
TextTransparency = 0,
})
local fadeOut = TweenService:Create(textLabel, tweenInfo, {
TextTransparency = 1,
})
local lastIndex
while true do
-- Step 0: Fade out before doing anything
fadeOut:Play()
task.wait(tweenInfo.Time)
-- Step 1: pick content that wasn't the last displayed
local index
repeat
index = RNG:NextInteger(1, #content)
until lastIndex ~= index
-- Make sure we don't show the same thing next time
lastIndex = index
-- Step 2: show the content
textLabel.Text = content[index]
fadeIn:Play()
task.wait(tweenInfo.Time + 1)
end
local textLabel = script.Parent
textLabel.Text = "Kaboom!"
while true do
for size = 5, 100, 5 do
textLabel.TextSize = size
textLabel.TextTransparency = size / 100
task.wait()
end
task.wait(1)
end
TextWrapped
When enabled, this property will render text on multiple lines within a GUI element's space so that TextLabel.TextBounds will never exceed the GuiBase2d.AbsoluteSize of the UI element.
This is achieved by breaking long lines of text into multiple lines. Line breaks will prefer whitespace; should a long unbroken word exceed the width of the element, that word will be broken into multiple lines.
If further line breaks would cause the vertical height of the text (the Y component of TextLabel.TextBounds) to exceed the vertical height of the element (the Y component of GuiBase2d.AbsoluteSize), then that line will not be rendered at all.
Code Samples
local textLabel = script.Parent
-- This text wrapping demo is best shown on a 200x50 px rectangle
textLabel.Size = UDim2.new(0, 200, 0, 50)
-- Some content to spell out
local content = "Here's a long string of words that will "
.. "eventually exceed the UI element's width "
.. "and form line breaks. Useful for paragraphs "
.. "that are really long."
-- A function that will spell text out two characters at a time
local function spellTheText()
-- Iterate from 1 to the length of our content
for i = 1, content:len() do
-- Get a substring of our content: 1 to i
textLabel.Text = content:sub(1, i)
-- Color the text if it doesn't fit in our box
if textLabel.TextFits then
textLabel.TextColor3 = Color3.new(0, 0, 0) -- Black
else
textLabel.TextColor3 = Color3.new(1, 0, 0) -- Red
end
-- Wait a brief moment on even lengths
if i % 2 == 0 then
task.wait()
end
end
end
while true do
-- Spell the text with scale/wrap off
textLabel.TextWrapped = false
textLabel.TextScaled = false
spellTheText()
task.wait(1)
-- Spell the text with wrap on
textLabel.TextWrapped = true
textLabel.TextScaled = false
spellTheText()
task.wait(1)
-- Spell the text with text scaling on
-- Note: Text turns red (TextFits = false) once text has to be
-- scaled down in order to fit within the UI element.
textLabel.TextScaled = true
-- Note: TextWrapped is enabled implicitly when TextScaled = true
--textLabel.TextWrapped = true
spellTheText()
task.wait(1)
end
TextXAlignment
TextXAlignment determines the horizontal alignment (X-axis) of text rendered within a UI element's space. It functions similarly to the CSS text-align property, with left, right and center values (there is no justify option). For Left and Right, text is rendered such that the left/right text bounds just touch the edge of the UI element rectangle. For Center, each line of text is centered on the very center of the UI element rectangle.
This property is used in conjunction with TextLabel.TextYAlignment to fully determine text alignment on both axes. This property won't affect the read-only properties TextLabel.TextBounds and TextLabel.TextFits.
Code Samples
-- Paste this in a LocalScript within a TextLabel/TextButton/TextBox
local textLabel = script.Parent
local function setAlignment(xAlign, yAlign)
textLabel.TextXAlignment = xAlign
textLabel.TextYAlignment = yAlign
textLabel.Text = xAlign.Name .. " + " .. yAlign.Name
end
while true do
-- Iterate over both TextXAlignment and TextYAlignment enum items
for _, yAlign in pairs(Enum.TextYAlignment:GetEnumItems()) do
for _, xAlign in pairs(Enum.TextXAlignment:GetEnumItems()) do
setAlignment(xAlign, yAlign)
task.wait(1)
end
end
end
TextYAlignment
TextYAlignment determines the vertical alignment (Y-axis) of text rendered within a UI element's space. For Top and Bottom, text is rendered such that the top/bottom text bounds just touch the edge of the UI element rectangle. For Center, text is rendered such that there is an equal space from the top bounds of the text to the top of the element and the bottom bounds of the text to the bottom of the element.
This property is used in conjunction with TextLabel.TextXAlignment to fully determine text alignment on both axes. This property won't affect the read-only properties TextLabel.TextBounds and TextLabel.TextFits.
Code Samples
-- Paste this in a LocalScript within a TextLabel/TextButton/TextBox
local textLabel = script.Parent
local function setAlignment(xAlign, yAlign)
textLabel.TextXAlignment = xAlign
textLabel.TextYAlignment = yAlign
textLabel.Text = xAlign.Name .. " + " .. yAlign.Name
end
while true do
-- Iterate over both TextXAlignment and TextYAlignment enum items
for _, yAlign in pairs(Enum.TextYAlignment:GetEnumItems()) do
for _, xAlign in pairs(Enum.TextXAlignment:GetEnumItems()) do
setAlignment(xAlign, yAlign)
task.wait(1)
end
end
end