Text

Text is a themed wrapper around Roblox's native TextLabel. It resolves its font, size, weight, line height, and color from the active Clean UI theme, and automatically sizes itself to fit its content.

Import

import { Text } from "@rbxts/react-clean-ui";

Basic usage

text is the only required prop. Without a variant, the text renders using the theme's body typography style.

Variants

Use variant to select a typography style from the active theme's typography scale.

<Text text="Display" variant="display" />
<Text text="Title" variant="title" />
<Text text="Heading" variant="heading" />
<Text text="Body" variant="body" />
<Text text="Label" variant="label" />
<Text text="Caption" variant="caption" />

Each variant defines its own font, size, weight, and line height. When variant is omitted, "body" is used.

Font weight

Use weight to override the font weight defined by the variant.

<Text text="Bold text" weight="bold" />
<Text text="Extra bold text" weight={Enum.FontWeight.ExtraBold} />

The string "bold" is a shorthand for Enum.FontWeight.Bold. Without weight, the variant's own weight is used, falling back to Enum.FontWeight.Regular.

Color

Use TextColor3 to override the text color.

<Text
    text="Custom color"
    TextColor3={Color3.fromHex("#3B72E6")}
/>

By default, the text color comes from theme.colors.intents.primary.default.textColor.

Alignment

Use align to control horizontal text alignment.

<Text text="Left aligned" align="Left" />
<Text text="Center aligned" align="Center" />
<Text text="Right aligned" align="Right" />

align defaults to "Left".

Text wrapping

Long text wraps across multiple lines by default.

<Text text="Long paragraphs wrap across multiple lines by default so body copy stays readable inside narrow containers." />

Set TextWrap={false} to keep the text on a single line.

<Text
    text="This text will not wrap."
    TextWrap={false}
/>

Custom typography

Use typography to supply a complete typography style, bypassing variant entirely.

<Text
    text="Custom typography"
    typography={{
        font: Enum.Font.Gotham,
        size: Enum.FontSize.Size24,
        weight: Enum.FontWeight.Bold,
        lineHeight: 1.3,
    }}
/>

When typography is provided, variant is ignored.

Native properties

Text extends React.InstanceProps<TextLabel>, so native Roblox TextLabel properties can be passed directly to it.

<Text
    text="Custom label"
    Position={UDim2.fromScale(0.5, 0.5)}
    ZIndex={2}
    TextTransparency={0.25}
    Event={{
        MouseEnter: () => {
            print("Hovering text");
        },
    }}
/>

Some properties are managed internally by the component, including:

• FontFace and FontSize, fully derived from variant/typography and weight. They cannot be set independently, even though React.InstanceProps<TextLabel> includes them.
• Text, set from text.
• TextXAlignment, set from align.
• Size and AutomaticSize, used to auto-size the label to its content.

Props

Text-specific props

Shared props

The text label also supports props inherited from the following interface.

All other compatible native TextLabel properties, such as AnchorPoint, Visible, Rotation, TextStrokeColor3, TextTransparency, and TextTruncate, are also accepted—see Native properties above.

Behaviour

• The label automatically sizes itself to fit its content (AutomaticSize.XY).
• Setting either TextWrap={false} or the native TextWrapped={false} disables wrapping; both must be non-false for wrapping to stay enabled.
• FontFace and FontSize are always derived from variant/typography and weight, and cannot be overridden directly, even though they are technically part of React.InstanceProps<TextLabel>.
• Without variant or typography, the theme's body typography style is used.
• The background is fully transparent by default (BackgroundTransparency={1}).
• When a nonzero letterSpacing is set (directly or via the typography style), Roblox has no native letter-spacing property, so the text is instead split into one TextLabel per character laid out in a UIListLayout row. In this mode, RichText is forced off (markup can't survive being split apart), wrapping/truncation don't apply since each character auto-sizes to itself, and native properties other than TextColor3, TextStrokeColor3, TextStrokeTransparency, and TextTransparency — including Change and Event — are not forwarded to the underlying instances.

Theme values

Text reads from the active theme for:

• theme.typography.<variant> — the font, size, weight, lineHeight, and letterSpacing for each of display, title, heading, body, label, and caption.
• theme.colors.intents.primary.default.textColor — the default text color when TextColor3 is not provided.

These values can be changed by providing a custom Clean UI theme.