TextScaled

Property of: TextBox

Value Type: bool

Description:

Note

Rather than using TextScaled, we recommend you consider using GuiObject/AutomaticSize|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, TextBox/TextSize is ignored and TextBox/TextWrapped is automatically enabled. This property is useful for text-rendering UI elements within BillboardGui|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. Here is an example of an automatically sized TextLabel (with no minimum size) that has TextScaled enabled:

TextScaled Demo

Note how automatic size changes the TextLabel’s size relative to the parent frame’s size. Subsequently, as the TextLabel is resized, the TextScaled property scales the text to the maximum amount of space available by the automatically sized TextLabel.

Code Samples

Long Text Wrapping

This code sample demonstrates TextWrap by spelling out a long chunk of text progressively. If the text doesn’t fit, it turns a different color.

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 wait() end
	end
end

while true do
	-- Spell the text with scale/wrap off
	textLabel.TextWrapped = false
	textLabel.TextScaled = false
	spellTheText()
	wait(1)
	-- Spell the text with wrap on
	textLabel.TextWrapped = true
	textLabel.TextScaled = false
	spellTheText()
	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()
	wait(1)
end