TextScaled
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:
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