Your first composable

The smallest unit of a screen

In Compose there is no "screen object" and no "view object". There is a function.

You already know how to write functions — you spent Part 1 doing it. A composable is that same thing with one extra label stuck on the front, and one different job: instead of returning a value, it describes a piece of screen.

Here is a complete, real one:

1@Composable
2fun Greeting() {
3    Text(text = "Hello from Compose")
4}

That is not a simplified teaching example. That is a genuine composable, and you could ship it.

What @Composable actually is

@Composable is an annotation — a label attached to your code that some tool reads. This one is read by the Compose compiler, a plugin that runs as part of your build. Your project turns it on with a single line in the build file:

1plugins {
2    alias(libs.plugins.android.application)
3    alias(libs.plugins.kotlin.android)
4    alias(libs.plugins.kotlin.compose)
5}

That third line is the whole setup. When the Compose compiler sees @Composable, it rewrites your function behind the scenes so it can be tracked, skipped and re-run intelligently. You never see the rewritten version, and you never need to.

The label buys the function two powers:

1. It may call other composables. Text, Column, Button — all composables. Only a composable can call one.
2. It may read state and be re-run automatically when that state changes. That is Lesson 3.5 and 3.6.

And it comes with one restriction, which follows from those powers: a composable can only be called from another composable. Try it from an ordinary function and the compiler stops you immediately. That error is in the Error Doctor below, and you will meet it for real.

Three rules for writing one

• Name it like a thing, not an action. PlayerPanel, not drawPlayerPanel. Composables are named in PascalCase with a capital first letter, unlike every other Kotlin function you have written. This is deliberate: a capital tells you at a glance that a call puts something on screen.
• Return nothing. A composable's return type is Unit, which is Kotlin's way of saying "no useful value". It does not hand you a screen. It emits one, as a side effect of running.
• Take parameters for everything that varies. That is what turns one function into a piece you use in ten places.

Making it appear

A composable does nothing on its own. Something has to call it, and the first call comes from your Activity:

1package com.yourname.composelab
2
3import android.os.Bundle
4import androidx.activity.ComponentActivity
5import androidx.activity.compose.setContent
6import androidx.compose.material3.Text
7import androidx.compose.runtime.Composable
8
9class MainActivity : ComponentActivity() {
10    override fun onCreate(state: Bundle?) {
11        super.onCreate(state)
12        setContent {
13            Greeting()
14        }
15    }
16}
17
18@Composable
19fun Greeting() {
20    Text(text = "Hello from Compose")
21}

Press Run and there it is: black text in the top-left corner of a white screen, with no padding and no styling, because you have not asked for any. Compose gives you exactly what you described and nothing else.

Parameters turn one stamp into many

A Greeting that always says the same thing is not much use. Add a parameter and the same function serves every case:

1@Composable
2fun PlayerLine(name: String, score: Int) {
3    Text(text = "$name: $score")
4}

Now call it twice with different arguments:

1@Composable
2fun DuelScreen() {
3    Column(modifier = Modifier.padding(24.dp)) {
4        Text(text = "DICE DUEL")
5        PlayerLine(name = "Player 1", score = 12)
6        PlayerLine(name = "Player 2", score = 9)
7    }
8}

That is the whole model. Your composables call other composables, which call other composables, until eventually everything bottoms out in the handful that Compose knows how to actually draw. The result is a tree, and the tree is your screen.

Seeing it without running the app

Building and installing an APK takes a few seconds even on a fast phone. When you are nudging a number back and forth, that adds up. So Compose has previews:

1@Preview(showBackground = true)
2@Composable
3private fun DuelScreenPreview() {
4    DuelScreen()
5}

Two labels: @Preview says "render this without launching the app", and @Composable because it is still a composable. Mark it private — nothing else should ever call it.

A preview function must take no parameters, which is why you write a tiny wrapper that supplies fixed values rather than previewing PlayerLine directly. Notice how easy that is here: because PlayerLine takes its data as parameters, you can preview it with any values you like, including ones that would be awkward to reach in the real app — a score of 999, an empty name, a player called Bartholomew-Fitzgerald. Designing for the preview quietly makes your code better.