Android XML To Compose Migration

XML to Compose Migration

A step-by-step guide for migrating Android XML layout screens and View-based UI to Jetpack Compose, covering layout equivalents, widget mapping, style migration, and a safe incremental strategy for production AAOS apps.

Standards baseline: Compose BOM 2024.x · Material Design 3.

When to Use This Skill

• Converting a specific XML layout file (fragment_*.xml, activity_*.xml, item_*.xml) to Compose.
• Planning an incremental Compose migration strategy for a legacy screen or module.
• Reviewing a completed migration for correctness and idiomatic patterns.
• Handling interop between existing XML Views and new Compose screens.

Migration Strategy

Recommended approach: Screen-by-screen (Strangler Fig)

Do not migrate the entire app at once. Use the interop layer to migrate one screen at a time:

Phase 1: Add ComposeView into existing XML Activity/Fragment
Phase 2: Migrate leaf screens (simple, no nested fragments) first
Phase 3: Migrate container screens (NavHostFragment → NavHost)
Phase 4: Remove XML layouts; Activity becomes a single ComposeView host

Migration readiness checklist per screen

• Identify all Views, listeners, and state sources.
• Identify which state comes from ViewModel (LiveData/StateFlow) vs View internal state.
• Map every XML View to a Compose equivalent (see tables below).
• Identify custom Views — migrate after standard views.

Layout Equivalents

Linear layouts

Layout attributes

Widget Equivalents

Style / Theme Migration

Colors

<!-- colors.xml (old) -->
<color name="primary">#6200EE</color>
<color name="on_primary">#FFFFFF</color>

// Compose Material 3 ColorScheme
val LightColorScheme = lightColorScheme(
    primary = Color(0xFF6200EE),
   
    secondary = Color(0xFF03DAC6),
    // ...
)

Text styles

<!-- themes.xml (old) -->
<style name="TextAppearance.MyApp.Title">
    <item name="android:textSize">20sp</item>
    <item name="android:fontFamily">@font/roboto_medium</item>
    <item name="android:textColor">@color/on_surface</item>
</style>

// Compose Typography
val MyTypography = Typography(
    titleLarge = TextStyle(
        fontFamily = RobotoFamily,
        fontWeight = FontWeight.Medium,
        fontSize = 20.sp,
    ),
)

// Usage
Text(text = "Hello", style = MaterialTheme.typography.titleLarge)

Dimensions (dimens.xml → Kotlin constants)

<!-- dimens.xml (old) -->
<dimen name="spacing_medium">16dp</dimen>
<dimen name="card_corner_radius">8dp</dimen>

// Compose design tokens (core:ui module)
object Dimens {
    val SpacingMedium = 16.dp
    val CardCornerRadius = 8.dp
}

// Usage
Modifier.padding(Dimens.SpacingMedium)

Typical Screen Migration Example

Before: XML Fragment

<!-- fragment_media_detail.xml -->
<LinearLayout vertical>
    <ImageView android:id="@+id/artwork" android:layout_width="match_parent" />
    <TextView android:id="@+id/title" style="@style/TitleText" />
    <TextView android:id="@+id/artist" />
    <Button android:id="@+id/play_button" android:text="@string/play" />
</LinearLayout>

// MediaDetailFragment.kt (old)
class MediaDetailFragment : Fragment(R.layout.fragment_media_detail) {
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        binding.artwork.load(viewModel.artworkUrl)
        binding.title.text = viewModel.title
        binding.playButton.setOnClickListener { viewModel.play() }
    }
}

After: Compose Screen

@Composable
fun MediaDetailScreen(
    uiState: MediaDetailUiState,
    onPlayClick: () -> Unit,
    modifier: Modifier = Modifier,
) {
    Column(modifier = modifier.fillMaxSize()) {
        AsyncImage(
            model = uiState.artworkUrl,
            contentDescription = null,
            modifier = Modifier.fillMaxWidth().aspectRatio(1f),
            contentScale = ContentScale.Crop,
        )
        Text(
            text = uiState.title,
            style = MaterialTheme.typography.titleLarge,
            modifier = Modifier.padding(horizontal = 16.dp, vertical = 8.dp),
        )
        Text(
            text = uiState.artist,
            style = MaterialTheme.typography.bodyMedium,
            modifier = Modifier.padding(horizontal = 16.dp),
        )
        Button(
           
            modifier = Modifier
                .fillMaxWidth()
                .padding(16.dp),
        ) {
            Text(stringResource(R.string.play))
        }
    }
}

// Fragment hosts the Compose screen during migration
class MediaDetailFragment : Fragment() {
    private val viewModel: MediaDetailViewModel by viewModels()

    override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?) =
        ComposeView(requireContext()).apply {
            setViewCompositionStrategy(ViewCompositionStrategy.DisposeOnViewTreeLifecycleDestroyed)
            setContent {
                MyAppTheme {
                    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
                    MediaDetailScreen(
                        uiState = uiState,
                       
                    )
                }
            }
        }
}

Interop Patterns

Using Compose inside XML (ComposeView)

// In a Fragment/Activity that still uses XML layout
binding.composeContainer.apply {  // ComposeView in layout XML
    setViewCompositionStrategy(ViewCompositionStrategy.DisposeOnViewTreeLifecycleDestroyed)
    setContent {
        MyAppTheme { NewComposableScreen() }
    }
}

Using XML View inside Compose (AndroidView)

// When a View has no Compose equivalent yet (e.g., MapView, custom SurfaceView)
AndroidView(
    factory = { context ->
        MyLegacyView(context).apply {
            // one-time initialization
        }
    },
    update = { view ->
        // called on recomposition — update view with new state
        view.setValue(currentValue)
    },
    modifier = Modifier.fillMaxWidth().height(200.dp),
)

Rules

• Always set ViewCompositionStrategy.DisposeOnViewTreeLifecycleDestroyed on ComposeView in Fragments — prevents memory leaks.
• AndroidView.update is called on every recomposition — keep it fast and idempotent.
• Avoid retaining Compose state inside AndroidView.factory lambda — use update for state sync.

RecyclerView → LazyColumn Migration

// Before: RecyclerView + Adapter + ViewHolder
class MediaAdapter(private val onClick: (MediaItem) -> Unit) :
    ListAdapter<MediaItem, MediaViewHolder>(DiffCallback) { ... }

// After: LazyColumn (no adapter, no ViewHolder, no DiffCallback)
@Composable
fun MediaList(
    items: List<MediaItem>,
    onItemClick: (String) -> Unit,
    modifier: Modifier = Modifier,
) {
    LazyColumn(modifier = modifier) {
        items(items = items, key = { it.id }) { item ->
            MediaItemRow(
                item = item,
                onItemClick(item.id) },
            )
        }
    }
}

Key differences

• No DiffCallback — Compose diffing is handled automatically with key.
• No ViewHolder — composables are reused by Compose runtime.
• No notifyDataSetChanged — just pass new list to items().

Common Pitfalls

Prerequisites

• Android Studio (Flamingo or newer) or AOSP build environment set up.
• Android SDK Platform-Tools installed (adb on PATH).
• Target device or emulator running Android 11+ (API 30+).
• For AOSP modules: repo tool, AOSP source synced, lunch target configured.

Step-by-Step Workflows

Step 1: Identify the screen to migrate

Start with leaf screens (no nested Fragments); defer screens with complex custom views.

Step 2: Map each XML view to a Compose equivalent

Use the Layout Equivalence and Widget Equivalence tables below.

Step 3: Introduce ComposeView or migrate the Fragment

Use ComposeView for incremental migration; fully replace Fragment for complete migration.

Step 4: Migrate the theme

Map XML styles/themes to MaterialTheme tokens; remove XML theme references from activities.

Step 5: Verify behavior and visual spec

Run existing Espresso tests (compatible with ComposeView); add Compose tests for new interactions.

Troubleshooting

• ComposeView inside RecyclerView causes performance issues — pre-allocate Compose views; use AbstractComposeView for better reuse.
• Theme mismatch (XML vs Compose) — wrap ComposeView with MaterialTheme { ... } to ensure consistent theming at the boundary.
• Espresso test fails after migration — ComposeView nodes are accessible from Espresso; check that testTags are correctly set.
• Navigation back stack broken — XML Fragment navigation and Compose NavHost must not overlap; pick one navigation system per screen.

Pre-Commit Checklist

• ComposeView in Fragment uses ViewCompositionStrategy.DisposeOnViewTreeLifecycleDestroyed.
• All colors/text styles from Compose screens use MaterialTheme tokens.
• LazyColumn items have key lambda.
• collectAsStateWithLifecycle() used (not collectAsState()).
• No duplicate theme wrapping in the composable hierarchy.
• XML layout file removed after full migration — not left as dead code.
• Strings still reference R.string.* — no hardcoded strings introduced during migration.

References

• Compose migration guide (official)
• Interoperability APIs
• ComposeView in Fragment
• Compose layout basics
• Material 3 migration