Text fields and user input

The field that will not type

Add a text field. Run the app. Tap it, the keyboard slides up, you type your name — and the field stays completely empty.

1OutlinedTextField(
2    value = "",
3    onValueChange = { }
4)

Nothing is broken. That field is doing precisely what you told it to: always show an empty string. Your keystrokes arrive, they are handed to onValueChange, and onValueChange throws them away.

This trips up nearly everyone, because every text box you have ever met in any other toolkit remembers what you typed. A Compose text field does not. Once you see why, the whole design clicks — and it is the same idea you will meet again as state hoisting in Part 4.

The pattern, in three lines

1var name by remember { mutableStateOf("") }
2
3OutlinedTextField(
4    value = name,
5    onValueChange = { name = it }
6)

• value is what the field displays. It is read from your state, every recomposition.
• onValueChange is called on every keystroke, and it is the whole new text — not the single character that was typed. Deleting a letter calls it too, with the shorter string.

The moment you write name = it, the loop closes: keystroke → state → recomposition → field shows the new value. It happens in well under a frame, so it feels exactly like a normal text box.

Why go to the trouble? Because now there is only one copy of the text, and it is yours. You can read it, clear it, pre-fill it from a database, or copy it into a second field, with no special API and nothing to keep in sync. That is the same promise Lesson 3.1 made about the whole of Compose, applied to the one component where people expect an exception.

1onValueChange = { new ->
2    if (new.all { it.isDigit() }) {
3        target = new
4    }
5}

A real form

1@Composable
2fun PlayerNames() {
3    var p1 by rememberSaveable { mutableStateOf("") }
4    var target by rememberSaveable {
5        mutableStateOf("30")
6    }
7    val tooShort =
8        p1.isNotEmpty() && p1.trim().length < 2
9
10    Column(
11        modifier = Modifier
12            .fillMaxWidth()
13            .padding(20.dp),
14        verticalArrangement =
15            Arrangement.spacedBy(14.dp)
16    ) {
17        OutlinedTextField(
18            value = p1,
19            onValueChange = { p1 = it },
20            label = { Text(text = "Player 1 name") },
21            placeholder = { Text(text = "Ada") },
22            singleLine = true,
23            isError = tooShort,
24            supportingText = {
25                if (tooShort) {
26                    Text(text = "At least 2 letters")
27                }
28            },
29            modifier = Modifier.fillMaxWidth()
30        )
31        OutlinedTextField(
32            value = target,
33            onValueChange = { new ->
34                if (new.all { it.isDigit() }) {
35                    target = new
36                }
37            },
38            label = { Text(text = "Target score") },
39            singleLine = true,
40            keyboardOptions = KeyboardOptions(
41                keyboardType = KeyboardType.Number,
42                imeAction = ImeAction.Done
43            ),
44            modifier = Modifier.fillMaxWidth()
45        )
46    }
47}

Choosing the right keyboard

Nothing says "amateur app" like a full QWERTY keyboard for a field that only accepts numbers.

1keyboardOptions = KeyboardOptions(
2    keyboardType = KeyboardType.Number,
3    imeAction = ImeAction.Done
4)

imeAction changes the bottom-right key on the keyboard: Done, Next, Search, Send. Set it to Next on every field but the last one in a form and people can tab straight through.

TextField or OutlinedTextField?

Both take identical parameters.

• OutlinedTextField draws a box around itself. Better on busy or coloured backgrounds, and easier to see as a target. Use it by default.
• TextField is filled with a tinted background and underlined. Slightly more compact; good for dense forms and search bars.

Pick one and use it everywhere in an app. Mixing them looks like an accident.

The keyboard covering the field

The moment you have a text field near the bottom of a screen, the keyboard will slide up over it. Compose has a modifier for that:

1Column(
2    modifier = Modifier
3        .fillMaxSize()
4        .imePadding()
5        .padding(20.dp)
6) {
7    // fields
8}

Modifier.imePadding() adds bottom padding equal to the height of the on-screen keyboard, so your content slides up out of the way. Pocket Notes uses it on the editor screen, and Lesson 5.9 puts it in properly.