# This file is automatically generated. Please don't edit it manually.
# To submit a bug report on the content, see
# https://devforum.roblox.com/c/bug-reports/documentation-issues/72

name: TextLabel
type: class
memory_category: Gui
summary: |
  A 2D user interface element that displays non-interactive text.
description: |
  A `Class.TextLabel` renders a rectangle, like a `Class.Frame`, with styled
  text. The rectangle can be used to define text boundaries, text scaling
  (`Class.TextLabel.TextScaled|TextScaled`), wrapping
  (`Class.TextLabel.TextWrapped|TextWrapped`), and alignment
  (`Class.TextLabel.TextXAlignment|TextXAlignment` and/or
  `Class.TextLabel.TextYAlignment|TextYAlignment`).

  This class contains properties that control the display of the text, such as
  `Class.TextLabel.Font|Font` and `Class.TextLabel.TextColor3|TextColor3`. To
  display only text and hide the background rectangle, set
  `Class.TextLabel.BackgroundTransparency|BackgroundTransparency` to `1`.

  A `Class.UITextSizeConstraint` object can be used to constrain the size of
  text with `Class.TextLabel.TextScaled|TextScaled` enabled. It is recommended
  that the size of text is no lower than `9`, otherwise it may not be visible to
  many users.
code_samples: []
inherits:
  - GuiLabel
descendants: []
tags: []
deprecation_message: ''
properties:
  - name: TextLabel.ContentText
    summary: |
      A copy of `Class.TextLabel.Text` that contains exactly what is being
      rendered by the `Class.TextLabel`.
    description: |
      This property provides a copy of `Class.TextLabel.Text|Text` that contains
      exactly what is being rendered by the `Class.TextLabel`. This is useful
      for eliminating style tags used for [rich text](../../../ui/rich-text.md)
      markup; for example, when `Class.TextLabel.RichText|RichText` is enabled,
      the `Class.TextLabel.ContentText|ContentText` property shows the text as
      it appears to the user.

      <table>
          <thead>
              <tr>
                  <th>RichText</th>
                  <th>Text</th>
                  <th>ContentText</th>
              </tr>
          </thead>
          <tbody>
              <tr>
                  <td><code>false</code></td>
                  <td>&lt;b&gt;Hello,&lt;br/&gt; world!&lt;/b&gt;</td>
                  <td>&lt;b&gt;Hello,&lt;br/&gt; world!&lt;/b&gt;</td>
              </tr>
              <tr>
                  <td><code>true</code></td>
                  <td>&lt;b&gt;Hello,&lt;br/&gt; world!&lt;/b&gt;</td>
                  <td>Hello,<br/> world!</td>
              </tr>
          </tbody>
        </table>
    code_samples: []
    type: string
    tags:
      - ReadOnly
      - NotReplicated
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Text
    serialization:
      can_load: false
      can_save: false
    capabilities:
      - UI
  - name: TextLabel.Font
    summary: |
      Determines the font used to render text.
    description: |
      This property selects one of several pre-defined fonts with which the
      `Class.TextLabel` will render its text. Some fonts have bold, italic
      and/or light variants.

      With the exception of the `Enum.Font.Legacy` font, each font will render
      text with the line height equal to the `Class.TextLabel.TextSize|TextSize`
      property.

      The `Enum.Font.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, where the width of each character is approximately half the
      `Class.TextLabel.TextSize|TextSize` property.

      This property is kept in sync with the `Class.TextLabel.FontFace|FontFace`
      property.
    code_samples:
      - Show-All-Fonts
    type: Enum.Font
    tags:
      - Hidden
      - NotReplicated
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Text
    serialization:
      can_load: true
      can_save: false
    capabilities:
      - UI
  - name: TextLabel.FontFace
    summary: |
      Determines the font used to render text.
    description: |
      This property is similar to the `Class.TextLabel.Font|Font` property but
      allows setting fonts that don't exist in `Enum.Font`.

      This property is kept in sync with the `Class.TextLabel.Font|Font`
      property, such that when setting `Class.TextLabel.FontFace|FontFace`, the
      font is set to the corresponding `Enum.Font` value or to
      `Enum.Font.Unknown` if there are no matches.
    code_samples: []
    type: Datatype.Font
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Text
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: TextLabel.FontSize
    summary: |
      Determines the font size to be used.
    description: |
      This property determines the font size to be used.
    code_samples: []
    type: FontSize
    tags:
      - NotReplicated
      - Deprecated
    deprecation_message: |
      This property is deprecated in favor of `Class.TextLabel|TextSize` which
      is an integer and not an enum and thus offers far more options for sizes.
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Text
    serialization:
      can_load: true
      can_save: false
    capabilities:
      - UI
  - name: TextLabel.LineHeight
    summary: |
      Scales the spacing between lines of text in the `Class.TextLabel`.
    description: |
      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 `Class.TextLabel`.
      Valid values range from `1.0` to `3.0`, defaulting to `1.0`.
    code_samples: []
    type: float
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Text
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: TextLabel.LocalizedText
    summary: |
      Sets whether a `Class.TextLabel` should be `Class.GuiBase2d.Localize` or
      not.
    description: |
      This property sets whether a `Class.TextLabel` should regard
      `Class.GuiBase2d.Localize` or not.
    code_samples: []
    type: string
    tags:
      - Hidden
      - ReadOnly
      - NotReplicated
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: false
      can_save: true
    capabilities:
      - UI
  - name: TextLabel.MaxVisibleGraphemes
    summary: |
      The maximum number of graphemes the `Class.TextLabel` can show.
    description: |
      This property controls the maximum number of graphemes (or units of text)
      that are shown on the `Class.TextLabel`. It is primarily provided as an
      easy way to create a
      [typewriter effect](../../../ui/animation.md#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 `Class.TextLabel.Text|Text`.
    code_samples: []
    type: int
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Text
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: TextLabel.OpenTypeFeatures
    summary: ''
    description: ''
    code_samples: []
    type: string
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Text
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: TextLabel.OpenTypeFeaturesError
    summary: ''
    description: ''
    code_samples: []
    type: string
    tags:
      - ReadOnly
      - NotReplicated
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Text
    serialization:
      can_load: false
      can_save: true
    capabilities:
      - UI
  - name: TextLabel.RichText
    summary: |
      Determines whether the `Class.TextLabel` renders its text using rich text
      formatting.
    description: |
      This property determines whether the `Class.TextLabel` renders its text
      using [rich text](../../../ui/rich-text.md) markup to style sections of
      the string in bold, italics, specific colors, and more.

      To use rich text, simply include rich text formatting tags in the
      `Class.TextLabel.Text|Text` string.
    code_samples: []
    type: boolean
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Text
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: TextLabel.Text
    summary: |
      Determines the string rendered by the `Class.TextLabel`.
    description: |
      This property determines the text content rendered by the
      `Class.TextLabel`. The visual properties of the string rendered to the
      screen is determined by `Class.TextLabel.TextColor3|TextColor3`,
      `Class.TextLabel.TextTransparency|TextTransparency`,
      `Class.TextLabel.TextSize|TextSize`, `Class.TextLabel.Font|Font`,
      `Class.TextLabel.TextScaled|TextScaled`,
      `Class.TextLabel.TextWrapped|TextWrapped`,
      `Class.TextLabel.TextXAlignment|TextXAlignment` and
      `Class.TextLabel.TextYAlignment|TextYAlignment`.

      It is possible to render emoji such as 🔒 and other symbols which aren't
      affected by the `Class.TextLabel.TextColor3|TextColor3` property. These
      can be pasted into `Class.Script` and `Class.LocalScript` objects, as well
      as the field within the [Properties](../../../studio/properties.md)
      window.

      This property may contain newline characters. Similarly, this property may
      contain a tab character, but it will render as a space instead.
    code_samples:
      - Fading-Banner
      - Emoji-in-Text
    type: string
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Text
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: TextLabel.TextBounds
    summary: |
      Read-only property which reflects the absolute size of rendered text in
      offsets.
    description: |
      This read-only property reflects the absolute size of rendered text in
      offsets, meaning that if you try to fit text into a rectangle, this
      property would reflect the minimum dimensions of the rectangle you'd need
      in order to fit the text.

      Using `Class.TextService:GetTextSize()`, you can predict what
      `Class.TextLabel.TextBounds|TextBounds` will be given a string,
      `Class.TextLabel.Font|Font`, `Class.TextLabel.TextSize|TextSize`, and
      frame size.
    code_samples: []
    type: Vector2
    tags:
      - ReadOnly
      - NotReplicated
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Text
    serialization:
      can_load: false
      can_save: false
    capabilities:
      - UI
  - name: TextLabel.TextColor
    summary: |
      Determines the color of text.
    description: |
      This property determines the color of text.
    code_samples: []
    type: BrickColor
    tags:
      - Hidden
      - NotReplicated
      - Deprecated
    deprecation_message: |
      This item has been superseded by `Class.TextLabel.TextColor3` which should
      be used in all new work.
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Text
    serialization:
      can_load: true
      can_save: false
    capabilities:
      - UI
  - name: TextLabel.TextColor3
    summary: |
      Determines the color of rendered text.
    description: |
      This property determines the color of all the text rendered by the
      `Class.TextLabel` element.
    code_samples:
      - Countdown-Text
    type: Color3
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Text
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: TextLabel.TextDirection
    summary: |
      Direction in which the text is rendered.
    description: |
      `Enum.TextDirection` in which the text is rendered.
    code_samples: []
    type: TextDirection
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Text
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: TextLabel.TextFits
    summary: |
      A boolean representation of whether the label's text fits within the size
      of it.
    description: |
      A boolean representation of whether the label's text fits within the size
      of it.
    code_samples: []
    type: boolean
    tags:
      - ReadOnly
      - NotReplicated
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Text
    serialization:
      can_load: false
      can_save: false
    capabilities:
      - UI
  - name: TextLabel.TextScaled
    summary: |
      Changes whether text is resized to fit within the `Class.TextLabel`.
    description: |
      This property determines whether text is scaled so that it fills the
      label's entire space. When enabled, `Class.TextLabel.TextSize|TextSize` is
      ignored and `Class.TextLabel.TextWrapped|TextWrapped` is automatically
      enabled. This property is useful for rendering text elements within
      `Class.BillboardGui|BillboardGuis`. When this property is used for
      [on-screen UI](../../../ui/on-screen-containers.md), it may be helpful to
      use a `Class.UITextSizeConstraint` to restrict the range of possible text
      sizes.

      ##### Automatic Sizing

      It's recommended that you avoid usage of
      `Class.TextLabel.TextScaled|TextScaled` and adjust UI to take advantage of
      the `Class.GuiObject.AutomaticSize|AutomaticSize` property instead. Here
      are the core differences between the two properties:

      - `Class.TextLabel.TextScaled|TextScaled` scales the content (text) to
        accommodate the UI. Without careful consideration, some text may become
        unreadable if scaled too small.

      - `Class.GuiObject.AutomaticSize|AutomaticSize` resizes the UI to
        accommodate content while maintaining a consistent font size. For more
        information, see [here](../../../ui/size-modifiers.md#automatic-sizing).

      Additionally, it's recommended that you avoid applying both
      `Class.GuiObject.AutomaticSize|AutomaticSize` and
      `Class.TextLabel.TextScaled|TextScaled` and to the same `Class.TextLabel`.
      `Class.GuiObject.AutomaticSize|AutomaticSize` determines the maximum
      amount of available space that a `Class.GuiObject` can use (in this case,
      text), while `Class.TextLabel.TextScaled|TextScaled` uses the available
      space determined by `Class.GuiObject.AutomaticSize|AutomaticSize` to scale
      the font size up to the maximum font size (100) if there are no size
      constraints.
    code_samples: []
    type: boolean
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Text
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: TextLabel.TextSize
    summary: |
      Determines the line height of text in offsets.
    description: |
      This property determines the height of one line of rendered text. The unit
      is in offsets, not points (which is used in most document editing
      programs). The `Enum.Font.Legacy` font does not hold this property.
    code_samples: []
    type: float
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Text
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: TextLabel.TextStrokeColor3
    summary: |
      Determines the color of the text stroke (outline).
    description: |
      This property sets the color of the stroke, or outline, of rendered text.
      Along with
      `Class.TextLabel.TextStrokeTransparency|TextStrokeTransparency`, it
      determines the final visual appearance of the text stroke.

      As a powerful alternative which supports color gradients, see
      `Class.UIStroke`.
    code_samples: []
    type: Color3
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Text
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: TextLabel.TextStrokeTransparency
    summary: |
      Determines the transparency of the text stroke (outline).
    description: |
      This property sets the transparency of the stroke, or outline, of rendered
      text. Along with `Class.TextLabel.TextStrokeColor3|TextStrokeColor3`, it
      determines the final visual appearance of the text stroke.

      Note that text stroke is multiple renderings of the same transparency, so
      this property is essentially multiplicative on itself four times over.
      Therefore, it's recommended to set
      `Class.TextLabel.TextStrokeTransparency|TextStrokeTransparency` to a value
      in the range of `0.75` to `1` for more a more subtle effect.

      As a powerful alternative which supports color gradients, see
      `Class.UIStroke`.
    code_samples: []
    type: float
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Text
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: TextLabel.TextTransparency
    summary: |
      Determines the transparency of rendered text.
    description: |
      This property determines the transparency of all the text rendered by the
      `Class.TextLabel`.
    code_samples: []
    type: float
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Text
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: TextLabel.TextTruncate
    summary: |
      Controls the truncation of the text displayed in the `Class.TextLabel`.
    description: |
      Controls the truncation of the text displayed in the `Class.TextLabel`.
    code_samples: []
    type: TextTruncate
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Text
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: TextLabel.TextWrap
    summary: |
      Determines whether or not text should wrap at the edges of the
      `Class.TextLabel` element's space.
    description: |
      This property determines whether or not text should wrap at the edges of
      the `Class.TextLabel` element's space.
    code_samples: []
    type: boolean
    tags:
      - NotReplicated
      - Deprecated
    deprecation_message: |
      This property is simply an alias for `Class.TextLabel|TextWrapped`. Use
      the past-tense version instead.
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Text
    serialization:
      can_load: true
      can_save: false
    capabilities:
      - UI
  - name: TextLabel.TextWrapped
    summary: |
      Determines if text wraps to multiple lines within the `Class.TextLabel`
      element's space, truncating excess text.
    description: |
      When enabled, this property will render text on multiple lines within a
      `Class.TextLabel` element's space so that
      `Class.TextLabel.TextBounds|TextBounds` will never exceed the
      `Class.GuiBase2d.AbsoluteSize` of the 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 `Class.TextLabel.TextBounds|TextBounds`) to exceed the
      vertical height of the element (the **Y** component of
      `Class.GuiBase2d.AbsoluteSize`), then that line will not be rendered at
      all.
    code_samples: []
    type: boolean
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Text
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: TextLabel.TextXAlignment
    summary: |
      Determines the horizontal alignment of rendered text.
    description: |
      This property determines the horizontal alignment of text rendered within
      the object's space. It is used in conjunction with
      `Class.TextLabel.TextYAlignment|TextYAlignment` to fully determine text
      alignment on both axes.

      Note that this property won't affect the read-only properties
      `Class.TextLabel.TextBounds|TextBounds` and
      `Class.TextLabel.TextFits|TextFits`.
    code_samples: []
    type: TextXAlignment
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Text
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
  - name: TextLabel.TextYAlignment
    summary: |
      Determines the vertical alignment of rendered text.
    description: |
      This property determines the vertical alignment of text rendered within
      the object's space. It is used in conjunction with
      `Class.TextLabel.TextXAlignment|TextXAlignment` to fully determine text
      alignment on both axes.

      Note that this property won't affect the read-only properties
      `Class.TextLabel.TextBounds|TextBounds` and
      `Class.TextLabel.TextFits|TextFits`.
    code_samples: []
    type: TextYAlignment
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Text
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - UI
methods: []
events: []
callbacks: []