iOS to Android: Declarative UI Layouts (SwiftUI to Jetpack Compose)

This guide provides a comprehensive, production-grade mapping from iOS SwiftUI declarative layouts and view hierarchies to modern Jetpack Compose (Material 3).


1. Core Layout Container Primitives

SwiftUI Primitive Jetpack Compose Equivalent Android Import Key Parameters / Notes
VStack(alignment:spacing:) Column(verticalArrangement:, horizontalAlignment:) androidx.compose.foundation.layout.Column Arranges children vertically.
HStack(alignment:spacing:) Row(horizontalArrangement:, verticalAlignment:) androidx.compose.foundation.layout.Row Arranges children horizontally.
ZStack(alignment:) Box(contentAlignment:) androidx.compose.foundation.layout.Box Stacks children in Z-order.
Spacer() Spacer(modifier = Modifier.weight(1f)) androidx.compose.foundation.layout.Spacer Expands to fill available space inside Column/Row.
Divider() HorizontalDivider() androidx.compose.material3.HorizontalDivider Visual separator line.
GeometryReader BoxWithConstraints androidx.compose.foundation.layout.BoxWithConstraints Exposes maxWidth, maxHeight constraints.

THE INVARIANT — apply to every Row you write, without exception: Whenever a horizontal Row contains flexible content (a title/description Text or Column) beside one or more fixed-intent elements (a Button, price Text, metric badge, streak pill, FilterChip, SegmentedButton, IconButton, or Switch), apply Modifier.weight(1f) to the flexible side and maxLines = 1 to every fixed-intent element's Text. Without an explicit weight, Compose gives the flexible child its full intrinsic width and squeezes the fixed-intent sibling to its minimum, wrapping text one character per line (B / u / y) on a typical phone width (roughly 360–411dp).

Detection heuristic: A Row with two or more children where none carries Modifier.weight(...) is unsafe — assign the weight before moving on. Arrangement.SpaceBetween does NOT substitute for a weight.

  1. Trailing action buttons: A banner or card-header Column beside a Button (e.g. "Continue", "Upgrade", "Retry") must give the Column Modifier.weight(1f) and the button label maxLines = 1.
  2. Trailing prices & badges: In any Row containing a title/subtitle Column on the left and a price/metric Text (such as a price, distance, rating or timestamp) or count badge ("3 new") on the right, give the left Column Modifier.weight(1f) and the right Text softWrap = false, maxLines = 1.
  3. Full-Width Segmented Controls & Multi-Option Chips: When porting a SwiftUI Picker(..., .segmented) or a preference row (e.g., a theme, sort-order or map-type selector with three or more options), NEVER place a Row of FilterChips or SegmentedButtons on the same horizontal Row beside a section label. Always stack the section title above in a Column, and place the selector below in its own full-width Row(modifier = Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.spacedBy(8.dp)) where each chip/button uses Modifier.weight(1f) and Text(..., maxLines = 1, overflow = TextOverflow.Ellipsis).

2. Scrollable Containers & Dynamic Lists

A. Dynamic Lists (List / ForEach ➡️ LazyColumn)

In SwiftUI, List provides lazy recycling of rows. In Android Jetpack Compose, you MUST use LazyColumn with typed items():

// Android Jetpack Compose
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier

@Composable
fun ItemListScreen(
    items: List<ItemModel>,
    onItemClick: (ItemModel) -> Unit,
    modifier: Modifier = Modifier
) {
    LazyColumn(
        modifier = modifier.fillMaxSize(),
        contentPadding = PaddingValues(16.dp),
        verticalArrangement = Arrangement.spacedBy(12.dp)
    ) {
        items(
            items = items,
            key = { item -> item.id }
        ) { item ->
            ItemCard(item = item, onClick = { onItemClick(item) })
        }
    }
}

B. Vertical Scrollable Screen (ScrollView ➡️ verticalScroll)

For static content that needs vertical scrolling (forms, detail pages):

// Android Jetpack Compose
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.verticalScroll
import androidx.compose.foundation.layout.Column

@Composable
fun DetailOverviewScreen(modifier: Modifier = Modifier) {
    val scrollState = rememberScrollState()

    Column(
        modifier = modifier
            .fillMaxSize()
            .verticalScroll(scrollState)
            .padding(16.dp),
        verticalArrangement = Arrangement.spacedBy(16.dp)
    ) {
        // Scrollable content
    }
}

C. Horizontal Carousels (ScrollView(.horizontal) ➡️ LazyRow)

// Android Jetpack Compose
import androidx.compose.foundation.lazy.LazyRow
import androidx.compose.foundation.lazy.items

LazyRow(
    horizontalArrangement = Arrangement.spacedBy(8.dp),
    contentPadding = PaddingValues(horizontal = 16.dp)
) {
    items(carouselItems, key = { it.id }) { item ->
        ItemChip(item = item)
    }
}

3. Structural App Components (Material 3)

SwiftUI Component Jetpack Compose (Material 3)
TabView / tabItem Scaffold + NavigationBar + NavigationBarItem
NavigationView / NavigationStack NavHost / rememberNavController()
NavigationView Toolbar / Title TopAppBar / CenterAlignedTopAppBar / MediumTopAppBar
Card / rounded visual box Card / OutlinedCard / ElevatedCard
Button Button, OutlinedButton, FilledTonalButton, TextButton, IconButton
Text with styling Text(stringResource(R.string.title), style = MaterialTheme.typography.titleLarge)
Text("Literal"), Button("Literal"), Label("Literal", systemImage:), .navigationTitle("…"), .alert("…"), TextField("Placeholder", …) stringResource(R.string.key) for the text / label / title / placeholder. SwiftUI string literals are implicit LocalizedStringKey lookups; Compose literals are not, so never port them as Text("Literal").
String(localized:) / NSLocalizedString / generated accessors (SwiftGen L10n.key, R.swift) stringResource(R.string.key) in composables; context.getString(R.string.key) outside composition
Text("Hello \(name)") (interpolation) stringResource(R.string.greeting, name) with <string name="greeting">Hello %1$s</string>
.accessibilityLabel("…") Modifier.semantics { contentDescription = … } or contentDescription = stringResource(R.string.key)
ProgressView CircularProgressIndicator / LinearProgressIndicator
Toggle / Toggle(isOn:) Switch(checked = ..., onCheckedChange = ...)
TextField OutlinedTextField(value = ..., onValueChange = ...)

4. State Connection & Observation in Compose

Always collect state from ViewModels using collectAsStateWithLifecycle() to maintain lifecycle safety:

import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.lifecycle.compose.collectAsStateWithLifecycle

@Composable
fun FeatureScreen(
    viewModel: FeatureViewModel,
    modifier: Modifier = Modifier
) {
    val uiState by viewModel.uiState.collectAsStateWithLifecycle()

    when (val state = uiState) {
        is FeatureUiState.Loading -> LoadingView()
        is FeatureUiState.Success -> ContentList(items = state.items)
        is FeatureUiState.Error -> ErrorMessage(message = state.message)
    }
}

5. Anti-Premature-Exit & Completeness Mandate

  • Never stub layouts with empty placeholders: Author the complete composables (LazyColumn, Cards, metrics, buttons) representing the source SwiftUI screens.
  • Never yield on background compilations: If ./gradlew assembleDebug runs in the background, wait for completion synchronously (WaitMsBeforeAsync: 10000) or monitor until finished. Do not output text-only waiting messages before authoring target files.