Build apps faster with our new App builder! Check it out →

Text

Common

Component in Material 3 Compose

High level element that displays text and provides semantics / accessibility information.

The default [style] uses the [LocalTextStyle] provided by the [MaterialTheme] / components. If you are setting your own style, you may want to consider first retrieving [LocalTextStyle], and using [TextStyle.copy] to keep any theme defined attributes, only modifying the specific attributes you want to override.

For ease of use, commonly used parameters from [TextStyle] are also present here. The order of precedence is as follows:

  • If a parameter is explicitly set here (i.e, it is not null or [TextUnit.Unspecified]), then this parameter will always be used.
  • If a parameter is not set, (null or [TextUnit.Unspecified]), then the corresponding value from [style] will be used instead.

Additionally, for [color], if [color] is not set, and [style] does not have a color, then [LocalContentColor] will be used.

Last updated:

Installation

dependencies {
   implementation("androidx.compose.material3:material3:1.4.0-alpha02")
}

Overloads

@Composable
fun Text(
    text: String,
    modifier: Modifier = Modifier,
    color: Color = Color.Unspecified,
    fontSize: TextUnit = TextUnit.Unspecified,
    fontStyle: FontStyle? = null,
    fontWeight: FontWeight? = null,
    fontFamily: FontFamily? = null,
    letterSpacing: TextUnit = TextUnit.Unspecified,
    textDecoration: TextDecoration? = null,
    textAlign: TextAlign? = null,
    lineHeight: TextUnit = TextUnit.Unspecified,
    overflow: TextOverflow = TextOverflow.Clip,
    softWrap: Boolean = true,
    maxLines: Int = Int.MAX_VALUE,
    minLines: Int = 1,
    onTextLayout: ((TextLayoutResult) -> Unit)? = null,
    style: TextStyle = LocalTextStyle.current
)

Parameters

namedescription
textthe text to be displayed
modifierthe [Modifier] to be applied to this layout node
color[Color] to apply to the text. If [Color.Unspecified], and [style] has no color set, this will be [LocalContentColor].
fontSizethe size of glyphs to use when painting the text. See [TextStyle.fontSize].
fontStylethe typeface variant to use when drawing the letters (e.g., italic). See [TextStyle.fontStyle].
fontWeightthe typeface thickness to use when painting the text (e.g., [FontWeight.Bold]).
fontFamilythe font family to be used when rendering the text. See [TextStyle.fontFamily].
letterSpacingthe amount of space to add between each letter. See [TextStyle.letterSpacing].
textDecorationthe decorations to paint on the text (e.g., an underline). See [TextStyle.textDecoration].
textAlignthe alignment of the text within the lines of the paragraph. See [TextStyle.textAlign].
lineHeightline height for the [Paragraph] in [TextUnit] unit, e.g. SP or EM. See [TextStyle.lineHeight].
overflowhow visual overflow should be handled.
softWrapwhether the text should break at soft line breaks. If false, the glyphs in the text will be positioned as if there was unlimited horizontal space. If [softWrap] is false, [overflow] and TextAlign may have unexpected effects.
maxLinesAn optional maximum number of lines for the text to span, wrapping if necessary. If the text exceeds the given number of lines, it will be truncated according to [overflow] and [softWrap]. It is required that 1 {'<='} [minLines] {'<='} [maxLines].
minLinesThe minimum height in terms of minimum number of visible lines. It is required that 1 {'<='} [minLines] {'<='} [maxLines].
onTextLayoutcallback that is executed when a new text layout is calculated. A [TextLayoutResult] object that callback provides contains paragraph information, size of the text, baselines and other details. The callback can be used to add additional decoration or functionality to the text. For example, to draw selection around the text.
stylestyle configuration for the text such as color, font, line height etc.
@Deprecated(
    "Maintained for binary compatibility. Use version with minLines instead",
    level = DeprecationLevel.HIDDEN
)
@Composable
fun Text(
    text: String,
    modifier: Modifier = Modifier,
    color: Color = Color.Unspecified,
    fontSize: TextUnit = TextUnit.Unspecified,
    fontStyle: FontStyle? = null,
    fontWeight: FontWeight? = null,
    fontFamily: FontFamily? = null,
    letterSpacing: TextUnit = TextUnit.Unspecified,
    textDecoration: TextDecoration? = null,
    textAlign: TextAlign? = null,
    lineHeight: TextUnit = TextUnit.Unspecified,
    overflow: TextOverflow = TextOverflow.Clip,
    softWrap: Boolean = true,
    maxLines: Int = Int.MAX_VALUE,
    onTextLayout: (TextLayoutResult) -> Unit = {},
    style: TextStyle = LocalTextStyle.current
)

@Composable
fun Text(
    text: AnnotatedString,
    modifier: Modifier = Modifier,
    color: Color = Color.Unspecified,
    fontSize: TextUnit = TextUnit.Unspecified,
    fontStyle: FontStyle? = null,
    fontWeight: FontWeight? = null,
    fontFamily: FontFamily? = null,
    letterSpacing: TextUnit = TextUnit.Unspecified,
    textDecoration: TextDecoration? = null,
    textAlign: TextAlign? = null,
    lineHeight: TextUnit = TextUnit.Unspecified,
    overflow: TextOverflow = TextOverflow.Clip,
    softWrap: Boolean = true,
    maxLines: Int = Int.MAX_VALUE,
    minLines: Int = 1,
    inlineContent: Map<String, InlineTextContent> = mapOf(),
    onTextLayout: (TextLayoutResult) -> Unit = {},
    style: TextStyle = LocalTextStyle.current
)

Parameters

namedescription
textthe text to be displayed
modifierthe [Modifier] to be applied to this layout node
color[Color] to apply to the text. If [Color.Unspecified], and [style] has no color set, this will be [LocalContentColor].
fontSizethe size of glyphs to use when painting the text. See [TextStyle.fontSize].
fontStylethe typeface variant to use when drawing the letters (e.g., italic). See [TextStyle.fontStyle].
fontWeightthe typeface thickness to use when painting the text (e.g., [FontWeight.Bold]).
fontFamilythe font family to be used when rendering the text. See [TextStyle.fontFamily].
letterSpacingthe amount of space to add between each letter. See [TextStyle.letterSpacing].
textDecorationthe decorations to paint on the text (e.g., an underline). See [TextStyle.textDecoration].
textAlignthe alignment of the text within the lines of the paragraph. See [TextStyle.textAlign].
lineHeightline height for the [Paragraph] in [TextUnit] unit, e.g. SP or EM. See [TextStyle.lineHeight].
overflowhow visual overflow should be handled.
softWrapwhether the text should break at soft line breaks. If false, the glyphs in the text will be positioned as if there was unlimited horizontal space. If [softWrap] is false, [overflow] and TextAlign may have unexpected effects.
maxLinesAn optional maximum number of lines for the text to span, wrapping if necessary. If the text exceeds the given number of lines, it will be truncated according to [overflow] and [softWrap]. It is required that 1 {'<='} [minLines] {'<='} [maxLines].
minLinesThe minimum height in terms of minimum number of visible lines. It is required that 1 {'<='} [minLines] {'<='} [maxLines].
inlineContenta map storing composables that replaces certain ranges of the text, used to insert composables into text layout. See [InlineTextContent].
onTextLayoutcallback that is executed when a new text layout is calculated. A [TextLayoutResult] object that callback provides contains paragraph information, size of the text, baselines and other details. The callback can be used to add additional decoration or functionality to the text. For example, to draw selection around the text.
stylestyle configuration for the text such as color, font, line height etc.
@Deprecated(
    "Maintained for binary compatibility. Use version with minLines instead",
    level = DeprecationLevel.HIDDEN
)
@Composable
fun Text(
    text: AnnotatedString,
    modifier: Modifier = Modifier,
    color: Color = Color.Unspecified,
    fontSize: TextUnit = TextUnit.Unspecified,
    fontStyle: FontStyle? = null,
    fontWeight: FontWeight? = null,
    fontFamily: FontFamily? = null,
    letterSpacing: TextUnit = TextUnit.Unspecified,
    textDecoration: TextDecoration? = null,
    textAlign: TextAlign? = null,
    lineHeight: TextUnit = TextUnit.Unspecified,
    overflow: TextOverflow = TextOverflow.Clip,
    softWrap: Boolean = true,
    maxLines: Int = Int.MAX_VALUE,
    inlineContent: Map<String, InlineTextContent> = mapOf(),
    onTextLayout: (TextLayoutResult) -> Unit = {},
    style: TextStyle = LocalTextStyle.current
)

Code Example

@Preview(showBackground = true)
@Composable
fun TextWithLinks() {
    val url = "https://developer.android.com/jetpack/compose"

    val linkColor = MaterialTheme.colorScheme.primary
    val linkStyle = SpanStyle(color = linkColor, textDecoration = TextDecoration.Underline)

    val annotatedString = buildAnnotatedString {
        append("Build better apps faster with ")
        withLink(LinkAnnotation.Url(url = url, styles = TextLinkStyles(style = linkStyle))) {
            append("Jetpack Compose")
        }
    }
    // Note that if your string is defined in resources, you can pass the same link style object
    // when constructing the AnnotatedString using the AnnotatedString.fromHtml method.
    Text(annotatedString)
}
by @alexstyl