TextButton

Show Deprecated

A TextButton behaves similarly to TextLabel in regards to rendering with the additional behaviors of a GuiButton. It defines the same text-rendering properties as a TextLabel does.

You can disable text rendering by setting TextButton.TextTransparency to 1. This will leave you with a plain rectangle that can be used as a button.

Code Samples

Click Counter

1-- Place this code in a LocalScript in a TextButton
2local textButton = script.Parent
3
4local counter = 0
5textButton.Text = "Click me!"
6
7local function onActivated()
8 counter = counter + 1
9 textButton.Text = "Clicks: " .. counter
10end
11
12textButton.Activated:Connect(onActivated)

Summary

Properties

A copy of TextButton.Text that contains exactly what is being rendered by the TextButton.

READ ONLY
NOT REPLICATED

Determines the font used to render text.

HIDDEN

Determines the font used to render text.

Scales the spacing between lines of text in the TextButton.

Sets whether a TextButton should be GuiBase2d.Localize or not.

HIDDEN
READ ONLY
NOT REPLICATED

The maximum number of graphemes the TextButton can show.

Determines whether the TextButton renders the TextButton.Text string using rich text formatting.

Determines the string rendered by the UI element.

The size of a UI element's text in offsets.

READ ONLY
NOT REPLICATED

Determines the color of rendered text.

A boolean representation of whether the TextButton's text fits within the size of it.

READ ONLY
NOT REPLICATED

Changes whether text is resized to fit within the TextButton.

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 TextButton.

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.

Events

Methods

SetTextFromInput(text: string): voidΒ Β 


Properties

ContentText

Read Only
Not Replicated

This property provides a copy of TextButton.Text that contains exactly what is being rendered by the TextButton. This is useful for eliminating style tags used for rich text.

Example

When TextButton.RichText is enabled, the TextButton.ContentText property shows the text as it appears to the player.

RichTextTextContentText
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 TextButton.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 TextButton.TextSize property.

This property is kept in sync with the TextButton.FontFace property. When setting Font, the FontFace is set to Font.fromEnum().

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 TextButton.Font property. When setting FontFace, the Font is set to the corresponding enum value, or to 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 TextButton. Valid values range from 1.0 to 3.0, defaulting to 1.0.

LocalizedText

Hidden
Read Only
Not Replicated

This property sets whether a TextButton should be GuiBase2d.Localize or not.

MaxVisibleGraphemes

This property controls the maximum number of graphemes (or units of text) that are shown on the TextButton. 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 TextButton.Text.

RichText

This property determines whether the TextButton renders the TextButton.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 TextButton.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 TextButton.TextColor3, TextButton.TextTransparency, TextButton.TextSize, TextButton.Font, TextButton.TextScaled, TextButton.TextWrapped, TextButton.TextXAlignment and TextButton.TextYAlignment.

It is possible to render emoji (for example, πŸ˜ƒ) and other symbols. These special symbols aren't affected by the TextButton.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.

TextBounds

Read Only
Not Replicated

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, TextButton.Font, TextButton.TextSize and frame size.

TextColor3

This property determines the color of all the text rendered by a GUI element. This property along with TextButton.Font, TextButton.TextSize and TextButton.TextTransparency will determine the visual properties of text. Text is rendered after the text stroke (TextButton.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 TextButton.BackgroundColor3 of the UI element. If the element has a transparent background, try applying a black TextButton.TextStrokeColor3 to help contrast the text with the 3D world behind it.

TextFits

Read Only
Not Replicated

A boolean representation of whether the TextButton's text fits within the size of it.

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, TextButton.TextSize is ignored and TextButton.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. 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.

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). The "Legacy" font does not hold this property.

TextStrokeColor3

The TextStrokeColor3 property sets the color of the stroke, or outline, of rendered text. This property and TextButton.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 TextButton.TextColor3 and TextButton.TextTransparency.

TextStrokeTransparency

The TextStrokeTransparency property sets the transparency of the stroke, or outline, of rendered text. This property and TextButton.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 TextButton.TextColor3 and TextButton.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.

TextTransparency

The TextColor3 property determines the transparency of all the text rendered by a UI element. This property along with TextButton.Font, TextButton.TextSize and TextButton.TextColor3 will determine the visual properties of text. Text is rendered after the text stroke (TextButton.TextStrokeTransparency).

Fading text in using a numeric for-loop is a fantastic way to draw a player's attention to text appearing on screen.


1-- Count backwards from 1 to 0, decrementing by 0.1
2for i = 1, 0, -.1 do
3 textLabel.TextTransparency = i
4 wait(.1)
5end
6

TextTruncate

Controls the truncation of the text displayed in this TextButton.

TextWrapped

When enabled, this property will render text on multiple lines within a GUI element's space so that TextButton.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 TextButton.TextBounds) to exceed the vertical height of the element (the Y component of GuiBase2d.AbsoluteSize), then that line will not be rendered at all.

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 TextButton.TextYAlignment to fully determine text alignment on both axes. This property won't affect the read-only properties TextButton.TextBounds and TextButton.TextFits.

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 TextButton.TextXAlignment to fully determine text alignment on both axes. This property won't affect the read-only properties TextButton.TextBounds and TextButton.TextFits.

Events

Methods

SetTextFromInput

void
Roblox Script Security

Parameters

text: string

Returns

void