Text and typography

The composable you will write most often

Text is the most-used composable in Android, by a distance. You have already used it a dozen times in the plainest possible way:

Text(text = "DICE DUEL")

That gives you 16sp of near-black in the phone's default face. Perfectly readable, and completely flat — a screen made only of that looks like a spreadsheet, because nothing tells the eye where to start.

This lesson is about the parameters that fix it.

The parameters worth knowing

1Text(
2    text = "DICE DUEL",
3    color = Color(0xFF5B3FD6),
4    fontSize = 40.sp,
5    fontWeight = FontWeight.Black,
6    letterSpacing = 6.sp
7)

Two of those have traps in them, so they get their own sections.

sp, never dp, for text

Sizes on screen use dp. Text uses sp, and the difference is not cosmetic.

sp means scale-independent pixel. It starts out identical to dp, but it also multiplies by whatever text size the user chose in their phone's accessibility settings. Someone who has set their font to Large gets larger text in your app, automatically, without you writing anything.

Set your text in dp and you have quietly overruled that person's eyesight. It is one of the easiest accessibility failures to commit and one of the easiest to avoid: if it is text, it is sp.

1fontSize = 15.sp   // right
2fontSize = 15.dp   // wrong, and will not compile

letterSpacing and lineHeight take sp too, for the same reason — they have to grow with the letters or the line falls apart.

overflow: what happens when it does not fit

By default, long text wraps onto as many lines as it needs, and if there is no room it is simply clipped mid-letter. That looks broken. The standard fix is two parameters together:

1Text(
2    text = note.title,
3    maxLines = 1,
4    overflow = TextOverflow.Ellipsis
5)

maxLines = 1 stops it wrapping; TextOverflow.Ellipsis puts a … at the cut. Neither works properly without the other — overflow has nothing to do unless something is limiting the lines. You will use this pair constantly in Pocket Notes, where note titles are whatever length the user felt like.

The type scale: stop inventing numbers

Setting fontSize by hand on every Text works, and it does not scale. Twenty screens later your headings are 40, 38, 40 and 42sp, and nobody knows which is right.

Material 3 ships a type scale: fifteen named, pre-designed text styles, sitting in your theme. You pick a role, not a number:

1Text(
2    text = "DICE DUEL",
3    style = MaterialTheme.typography.displaySmall
4)
5Text(
6    text = "First to 30 wins the duel",
7    style = MaterialTheme.typography.bodyMedium
8)

The five families, biggest to smallest, each in Large, Medium and Small:

Text with no style uses bodyLarge, which is why plain text comes out at 16sp.

To bend one of them without abandoning the scale, use .copy():

1Text(
2    text = "PLAYER 1",
3    style = MaterialTheme.typography.labelLarge.copy(
4        letterSpacing = 2.sp
5    )
6)

You get the scale's size, weight and line height, with one thing changed. Lesson 3.11 shows how to replace the whole scale with your own fonts.

A real title block

This is Dice Duel's, with the theme colours written out as literals for now — Lesson 3.11 replaces them with proper roles.

1@Composable
2fun TitleBlock() {
3    Column {
4        Text(
5            text = "DICE DUEL",
6            color = Color(0xFF5B3FD6),
7            fontSize = 40.sp,
8            fontWeight = FontWeight.Black,
9            letterSpacing = 6.sp
10        )
11        Spacer(Modifier.height(2.dp))
12        Text(
13            text = "First to 30 wins the duel",
14            color = Color(0xFF4A4463),
15            fontSize = 15.sp,
16            fontWeight = FontWeight.Medium,
17            letterSpacing = 1.sp
18        )
19    }
20}

Styling one word inside a sentence

Sometimes you need part of a line to look different — a bold number in a sentence, a coloured name. You cannot do it with two Text composables, because they would not wrap together as one paragraph.

The answer is an annotated string:

1val line = buildAnnotatedString {
2    append("First to ")
3    withStyle(
4        SpanStyle(fontWeight = FontWeight.Black)
5    ) {
6        append("30")
7    }
8    append(" wins")
9}
10
11Text(text = line)

buildAnnotatedString gives you a little builder: append adds plain text, and withStyle applies a SpanStyle to everything appended inside it. The result is one piece of text that wraps, aligns and truncates as a single unit.

You will use this properly in Pocket Notes to highlight the matched part of a search result.