xml-to-compose-migration

--- name: xml-to-compose-migration description: Convert Android XML layouts to Jetpack Compose. Use when asked to migrate Views to Compose, convert XML to Composables, or modernize UI from View system to Compose. ---

# XML to Compose Migration

## Overview

Systematically convert Android XML layouts to idiomatic Jetpack Compose, preserving functionality while embracing Compose patterns. This skill covers layout mapping, state migration, and incremental adoption strategies.

## Workflow

### 1. Analyze the XML Layout

- Identify the root layout type (`ConstraintLayout`, `LinearLayout`, `FrameLayout`, etc.). - List all View widgets and their key attributes. - Map data binding expressions (`@{}`) or view binding references. - Identify custom views that need special handling. - Note any `include`, `merge`, or `ViewStub` usage.

### 2. Plan the Migration

- Decide: **Full rewrite** or **incremental migration** (using `ComposeView`/`AndroidView`). - Identify state sources (ViewModel, LiveData, savedInstanceState). - List reusable components to extract as separate Composables. - Plan navigation integration if using Navigation component.

### 3. Convert Layouts

Apply the layout mapping table below to convert each View to its Compose equivalent.

### 4. Migrate State

- Convert `LiveData` observation to `StateFlow` collection or `observeAsState()`. - Replace `findViewById` / ViewBinding with Compose state. - Convert click listeners to lambda parameters.

### 5. Test and Verify

- Compare visual output between XML and Compose versions. - Test accessibility (content descriptions, touch targets). - Verify state preservation across configuration changes.

---

## Layout Mapping Reference

### Container Layouts

| XML Layout | Compose Equivalent | Notes | |------------|-------------------|-------| | `LinearLayout (vertical)` | `Column` | Use `Arrangement` and `Alignment` | | `LinearLayout (horizontal)` | `Row` | Use `Arrangement` and `Alignment` | | `FrameLayout` | `Box` | Children stack on top of each other | | `ConstraintLayout` | `ConstraintLayout` (Compose) | Use `createRefs()` and `constrainAs` | | `RelativeLayout` | `Box` or `ConstraintLayout` | Prefer Box for simple overlap | | `ScrollView` | `Column` + `Modifier.verticalScroll()` | Or use `LazyColumn` for lists | | `HorizontalScrollView` | `Row` + `Modifier.horizontalScroll()` | Or use `LazyRow` for lists | | `RecyclerView` | `LazyColumn` / `LazyRow` / `LazyGrid` | Most common migration | | `ViewPager2` | `HorizontalPager` | From accompanist or Compose Foundation | | `CoordinatorLayout` | Custom + `Scaffold` | Use `TopAppBar` with scroll behavior | | `NestedScrollView` | `Column` + `Modifier.verticalScroll()` | Prefer Lazy variants |

### Common Widgets

| XML Widget | Compose Equivalent | Notes | |------------|-------------------|-------| | `TextView` | `Text` | Use `style` → `TextStyle` | | `EditText` | `TextField` / `OutlinedTextField` | Requires state hoisting | | `Button` | `Button` | Use `onClick` lambda | | `ImageView` | `Image` | Use `painterResource()` or Coil | | `ImageButton` | `IconButton` | Use `Icon` inside | | `CheckBox` | `Checkbox` | Requires `checked` + `onCheckedChange` | | `RadioButton` | `RadioButton` | Use with `Row` for groups | | `Switch` | `Switch` | Requires state hoisting | | `ProgressBar (circular)` | `CircularProgressIndicator` | | | `ProgressBar (horizontal)` | `LinearProgressIndicator` | | | `SeekBar` | `Slider` | Requires state hoisting | | `Spinner` | `DropdownMenu` + `ExposedDropdownMenuBox` | More complex pattern | | `CardView` | `Card` | From Material 3 | | `Toolbar` | `TopAppBar` | Use inside `Scaffold` | | `BottomNavigationView` | `NavigationBar` | Material 3 | | `FloatingActionButton` | `FloatingActionButton` | Use inside `Scaffold` | | `Divider` | `HorizontalDivider` / `VerticalDivider` | | | `Space` | `Spacer` | Use `Modifier.size()` |

### Attribute Mapping

| XML Attribute | Compose Modifier/Property | |---------------|--------------------------| | `android:layout_width="match_parent"` | `Modifier.fillMaxWidth()` | | `android:layout_height="match_parent"` | `Modifier.fillMaxHeight()` | | `android:layout_width="wrap_content"` | `Modifier.wrapContentWidth()` (usually implicit) | | `android:layout_weight` | `Modifier.weight(1f)` | | `android:padding` | `Modifier.padding()` | | `android:layout_margin` | `Modifier.padding()` on parent, or use `Arrangement.spacedBy()` | | `android:background` | `Modifier.background()` | | `android:visibility="gone"` | Conditional composition (don't emit) | | `android:visibility="invisible"` | `Modifier.alpha(0f)` (keeps space) | | `android:clickable` | `Modifier.clickable { }` | | `android:contentDescription` | `Modifier.semantics { contentDescription = "" }` | | `android:elevation` | `Modifier.shadow()` or component's `elevation` param | | `android:alpha` | `Modifier.alpha()` | | `android:rotation` | `Modifier.rotate()` | | `android:scaleX/Y` | `Modifier.scale()` | | `android:gravity` | `Alignment` parameter or `Arrangement` | | `android:layout_gravity` | `Modifier.align()` |

---

## Common Patterns

### LinearLayout with Weights

```xml <!-- XML --> <LinearLayout android:orientation="horizontal"> <View android:layout_weight="1" /> <View android:layout_weight="2" /> </LinearLayout> ```

```kotlin // Compose Row(modifier = Modifier.fillMaxWidth()) { Box(modifier = Modifier.weight(1f)) Box(modifier = Modifier.weight(2f)) } ```

### RecyclerView to LazyColumn

```xml <!-- XML --> <androidx.recyclerview.widget.RecyclerView android:id="@+id/recyclerView" android:layout_width="match_parent" android:layout_height="match_parent" /> ```

```kotlin // Compose LazyColumn(modifier = Modifier.fillMaxSize()) { items(items, key = { it.id }) { item -> ItemRow(item = item, onClick = { onItemClick(item) }) } } ```

### EditText with Two-Way Binding

```xml <!-- XML with Data Binding --> <EditText android:text="@={viewModel.username}" android:hint="@string/username_hint" /> ```

```kotlin // Compose val username by viewModel.username.collectAsState()

OutlinedTextField( value = username, onValueChange = { viewModel.updateUsername(it) }, label = { Text(stringResource(R.string.username_hint)) }, modifier = Modifier.fillMaxWidth() ) ```

### ConstraintLayout Migration

```xml <!-- XML --> <androidx.constraintlayout.widget.ConstraintLayout> <TextView android:id="@+id/title" app:layout_constraintTop_toTopOf="parent" app:layout_constraintStart_toStartOf="parent" /> <TextView android:id="@+id/subtitle" app:layout_constraintTop_toBottomOf="@id/title" app:layout_constraintStart_toStartOf="@id/title" /> </androidx.constraintlayout.widget.ConstraintLayout> ```

```kotlin // Compose ConstraintLayout(modifier = Modifier.fillMaxWidth()) { val (title, subtitle) = createRefs() Text( text = "Title", modifier = Modifier.constrainAs(title) { top.linkTo(parent.top) start.linkTo(parent.start) } ) Text( text = "Subtitle", modifier = Modifier.constrainAs(subtitle) { top.linkTo(title.bottom) start.linkTo(title.start) } ) } ```

### Include / Merge → Extract Composable

```xml <!-- XML: layout_header.xml --> <merge> <ImageView android:id="@+id/avatar" /> <TextView android:id="@+id/name" /> </merge>

<!-- Usage --> <include layout="@layout/layout_header" /> ```

```kotlin // Compose: Extract as a reusable Composable @Composable fun HeaderSection( avatarUrl: String, name: String, modifier: Modifier = Modifier ) { Row(modifier = modifier) { AsyncImage(model = avatarUrl, contentDescription = null) Text(text = name) } }

// Usage HeaderSection(avatarUrl = user.avatar, name = user.name) ```

---

## Incremental Migration (Interop)

### Embedding Compose in XML

```xml <!-- In your XML layout --> <androidx.compose.ui.platform.ComposeView android:id="@+id/compose_view" android:layout_width="match_parent" android:layout_height="wrap_content" /> ```

```kotlin // In Fragment/Activity binding.composeView.setContent { MaterialTheme { MyComposable() } } ```

### Embedding XML Views in Compose

```kotlin // Use AndroidView for Views that don't have Compose equivalents @Composable fun MapViewComposable(modifier: Modifier = Modifier) { AndroidView( factory = { context -> MapView(context).apply { // Initialize the view } }, update = { mapView -> // Update the view when state changes }, modifier = modifier ) } ```

---

## State Migration

### LiveData to Compose

```kotlin // Before: Observing in Fragment viewModel.uiState.observe(viewLifecycleOwner) { state -> binding.title.text = state.title }

// After: Collecting in Compose @Composable fun MyScreen(viewModel: MyViewModel = hiltViewModel()) { val uiState by viewModel.uiState.collectAsStateWithLifecycle() Text(text = uiState.title) } ```

### Click Listeners

```kotlin // Before: XML + setOnClickListener binding.submitButton.setOnClickListener { viewModel.submit() }

// After: Lambda in Compose Button(onClick = { viewModel.submit() }) { Text("Submit") } ```

---

## Checklist

- [ ] All layouts converted (no `include` or `merge` left) - [ ] State hoisted properly (no internal mutable state for user input) - [ ] Click handlers converted to lambdas - [ ] RecyclerView adapters removed (using LazyColumn/LazyRow) - [ ] ViewBinding/DataBinding removed - [ ] Navigation integrated (NavHost or interop) - [ ] Theming applied (MaterialTheme) - [ ] Accessibility preserved (content descriptions, touch targets) - [ ] Preview annotations added for development - [ ] Old XML files deleted

## References

- [Interoperability APIs](https://developer.android.com/develop/ui/compose/migrate/interoperability-apis) - [Migration Strategy](https://developer.android.com/develop/ui/compose/migrate/strategy) - [Compose and Views side by side](https://developer.android.com/develop/ui/compose/migrate)