wear-compose-m3

---

name: wear-compose-m3 description: Guidance for Wear OS Compose Material3 (Wear Compose Material 3 / Wear Compose Material3) watch and wearable apps. Covers creating, updating, and migrating projects (Material 2.5 and Horologist migration) using androidx.wear.compose.material3, androidx.wear.compose.foundation, and androidx.wear.compose.navigation3, including AppScaffold, ScreenScaffold, TransformingLazyColumn, ambient mode, and previews. license: Complete terms in LICENSE.txt metadata: author: Google LLC last-updated: '2026-09-24' keywords:

• Wear OS
• Compose
• Material3
• Horologist
• TransformingLazyColumn
• ScalingLazyColumn
• AppScaffold
• ScreenScaffold
• EdgeButton
• SwipeDismissableSceneStrategy
• Material 2.5
• ambient mode

---

Prerequisites and compatibility

1. Current Wear OS Compose version in-use: To find the installed library version, read gradle/libs.versions.toml or build.gradle.kts directly. Don't run ./gradlew dependencies or other shell commands to resolve versions.
2. Wear OS Compose Material3 version: If an internal tool is available to establish the latest stable version {VERSION} of androidx.wear.compose:compose-material3, use that tool.
   • Otherwise, fetch the official Maven metadata XML to identify {VERSION} (highest number, ignoring -alpha, -beta, or -rc).
3. Strict compliance: If a version is listed as stable, you MUST use it, unless overridden by the user. Do not downgrade based on initial "Unresolved reference" errors in the editor or outdated web search results.
4. Kotlin & Compose compiler: Use Kotlin 2.0.0+ with the org.jetbrains.kotlin.plugin.compose Gradle plugin.
5. Min SDK: Ensure minSdk is at least 25.
6. Compile SDK & AGP: Ensure compileSdk and AGP meet the library's AAR metadata floors (compileSdk >= 35 and AGP >= 8.6.0 for 1.6.x; compileSdk >= 37 and AGP >= 9.1.0 for 1.7.x).

Gotchas

1. Mandatory sync and validation: After updating versions in libs.versions.toml or build.gradle.kts, perform a Gradle sync (or ./gradlew assembleDebug) before refactoring, and run ./gradlew assembleDebug after refactoring to verify the build.
2. Prohibition of guessing (error protocol): If you encounter an 'Unresolved Reference' or API mismatch after a successful sync, do not attempt to 'fix' it by downgrading the library version.

Capabilities and tools

Capability 1: Migration, updates, and adding features

Use this guidance when migrating from an older version of Wear OS Compose or Horologist, updating an existing Wear Compose Material3 project, or adding features.

1. Unless otherwise indicated by the developer, use the latest stable version of Wear Compose Material3 from {VERSION} (superseding any literal version strings in the migration guide).
2. When migrating from Material 2.5 or Horologist, read the migration guide and use its official component mappings.
3. Before refactoring any component (for example, Chip -> Button), check the parameter names, slot types, and "Expressive" design tokens.
4. Do not use the Horologist Composables, Compose Layout, or Compose Material libraries; replace Horologist components with Wear Compose M3 equivalents (AppScaffold -> M3 AppScaffold, ScreenScaffold -> M3 ScreenScaffold, ScalingLazyColumn -> TransformingLazyColumn, ResponsiveListHeader -> ListHeader, PagerScreen -> HorizontalPagerScaffold, Chip -> Button, Confirmation -> ConfirmationDialog).
5. Always check against the component guidance in Capability 3.
6. Expect screenshot tests to fail when migrating or updating components: expected defaults for padding and positioning will have changed. Do not seek to artificially match the previous screenshot, but give preference to the Material3 defaults.

Capability 2: Component samples

Use this table of reference to find canonical samples for Wear Compose components. When working with a Wear Compose component, you must use the samples linked from the table to ensure you know how to correctly use it.

Important: Symbols marked with [alpha], [beta], or [rc] are only available in that pre-release track and are not in stable {VERSION}. Do not use them unless the project explicitly targets that pre-release version.

Material 3 components in androidx.wear.compose.material3.*

Component / Symbol	Reference Samples
AlertDialog, AlertDialogDefaults	AlertDialogSample
AnimatedPage, HorizontalPagerScaffold, VerticalPagerScaffold	OneHandedGestureSamples, PageIndicatorSample, PagerScaffoldSample
AnimatedText, rememberAnimatedTextFontRegistry	AnimatedTextSample
AppCard	CardSample
AppScaffold	ListHeaderSample, PagerScaffoldSample, ScaffoldSample, SurfaceTransformationSample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample
ArcProgressIndicator, ArcProgressIndicatorDefaults, CircularProgressIndicator, CircularProgressIndicatorDefaults, ProgressIndicatorDefaults, SegmentedCircularProgressIndicator, drawCircularProgressIndicator	ProgressIndicatorSample
Button	AlertDialogSample, AnimatedTextSample, ButtonGroupSample, ButtonSample, DatePickerSample, DynamicColorSchemeSample, FadingExpandingLabelSample, ListHeaderSample, OneHandedGestureSamples, PageIndicatorSample, PagerScaffoldSample, PickerSample, ScaffoldSample, ScrollIndicatorSample, StepperSample, SurfaceTransformationSample, SwipeDismissableSceneStrategySample, SwipeToRevealSample, TimePickerSample, TransformationSpecSample, TransformingLazyColumnSample, TransformingLazyColumnSample
ButtonDefaults	ButtonSample, CurvedTextSamples, DynamicColorSchemeSample, EdgeButtonSample, ListHeaderSample, OneHandedGestureSamples, PlaceholderSample, ScaffoldSample, ScrollAwaySample, ScrollIndicatorSample, SurfaceTransformationSample, TextButtonSample, TransformationSpecSample, TransformingLazyColumnSample, TransformingLazyColumnSample
ButtonGroup	ButtonGroupSample, TransformationSpecSample
Card	CardSample, SwipeDismissableSceneStrategySample, SwipeToRevealSample, TransformingLazyColumnSample
CardDefaults	CardSample, SurfaceTransformationSample, SwipeToRevealSample, TransformingLazyColumnSample, TransformingLazyColumnSample
CheckboxButton	CheckboxButtonSample, SwipeToDismissBoxSample
ChildButton, OutlinedButton	ButtonSample
ColorScheme, dynamicColorScheme	DynamicColorSchemeSample
CompactButton, CompactButtonDefaults	ButtonSample, TransformingLazyColumnSample
ConfirmationDialog, ConfirmationDialogDefaults, FailureConfirmationDialog, SuccessConfirmationDialog, confirmationDialogCurvedText	ConfirmationDialogSample
CurvedTextDefaults	CurvedTextSamples
DatePicker, DatePickerType	DatePickerSample
EdgeButton	EdgeButtonSample, OneHandedGestureSamples, ScaffoldSample, SwipeDismissableSceneStrategySample, TransformingLazyColumnSample
EdgeButtonSize	EdgeButtonSample
FadingExpandingLabel	FadingExpandingLabelSample
FilledIconButton, FilledTonalIconButton, IconButtonColors, IconButtonShapes, OutlinedIconButton	IconButtonSample
FilledTonalButton	AlertDialogSample, ButtonSample, ConfirmationDialogSample, OpenOnPhoneDialogSample, PlaceholderSample, ScrollAwaySample, SwipeToDismissBoxSample
HorizontalPageIndicator, VerticalPageIndicator	PageIndicatorSample
Icon	AlertDialogSample, ButtonSample, CardSample, CheckboxButtonSample, ConfirmationDialogSample, CurvedTextSamples, DatePickerSample, EdgeButtonSample, IconButtonSample, ListHeaderSample, PlaceholderSample, ProgressIndicatorSample, RadioButtonSample, SwipeToRevealSample, SwitchButtonSample, TimePickerSample
IconButton	IconButtonSample, LevelIndicatorSample, ProgressIndicatorSample
IconButtonDefaults	IconButtonSample, ProgressIndicatorSample
IconToggleButton, IconToggleButtonDefaults	IconToggleButtonSample
LevelIndicator	LevelIndicatorSample
LinearProgressIndicator	LinearProgressIndicatorSample
ListHeader	ListHeaderSample, ScrollAwaySample, SwipeDismissableSceneStrategySample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample
ListHeaderDefaults	ListHeaderSample, ScrollAwaySample, TransformingLazyColumnSample
ListSubHeader	ListHeaderSample
LocalOneHandedGestureEnabled [rc], OneHandedGestureDefaults [rc], OneHandedGestureHorizontalPageIndicator [rc], OneHandedGesturePageIndicatorState [rc], OneHandedGesturePriority [rc], OneHandedGestureScrollIndicator [rc], OneHandedGestureScrollIndicatorState [rc], OneHandedGestureVerticalPageIndicator [rc]	OneHandedGestureSamples
MaterialTheme	AlertDialogSample, ButtonSample, CardSample, CurvedTextSamples, DynamicColorSchemeSample, LinearProgressIndicatorSample, PagerScaffoldSample, ProgressIndicatorSample, SwipeToDismissBoxSample, TimeTextSample, TransformingLazyColumnNotificationsSample
OneHandedGestureAction [rc], OneHandedGestureClickIndicator [rc], OneHandedGestureClickIndicatorState [rc], oneHandedGesture [rc], rememberOneHandedGestureConfiguration [rc]	ButtonSample, CardSample, OneHandedGestureSamples
OpenOnPhoneDialog, OpenOnPhoneDialogDefaults, openOnPhoneDialogCurvedText	OpenOnPhoneDialogSample
OutlinedCard	CardSample, TransformingLazyColumnSample
PagerScaffoldDefaults	PageIndicatorSample, PagerScaffoldSample
Picker	PickerSample
PickerGroup	PickerGroupSample
RadioButton, SplitRadioButton	RadioButtonSample
ResponsiveTransformationSpec, TransformationVariableSpec	SurfaceTransformationSample, TransformationSpecSample
RevealValue, SwipeToReveal, SwipeToRevealDefaults, rememberRevealState	SwipeToRevealSample
ScreenScaffold	ListHeaderSample, OneHandedGestureSamples, PagerScaffoldSample, ScaffoldSample, SurfaceTransformationSample, SwipeDismissableSceneStrategySample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample
ScreenScaffoldDefaults, ScrollIndicator	ScrollIndicatorSample
ScreenStage, scrollAway	ScrollAwaySample
Slider, SliderDefaults	SliderSample
SplitCheckboxButton	CheckboxButtonSample
SplitSwitchButton	SwitchButtonSample
Stepper, StepperLevelIndicator, rangeSemantics	StepperSample
StepperDefaults	LevelIndicatorSample, StepperSample
SurfaceTransformation	AlertDialogSample, DynamicColorSchemeSample, ListHeaderSample, ScaffoldSample, SurfaceTransformationSample, SwipeDismissableSceneStrategySample, TransformationSpecSample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample, TransformingLazyColumnSample
SwipeToDismissBox	SwipeToDismissBoxSample
SwitchButton	AlertDialogSample, OneHandedGestureSamples, SwitchButtonSample
Text	AlertDialogSample, AnimatedTextSample, ButtonGroupSample, ButtonSample, CardSample, CheckboxButtonSample, ConfirmationDialogSample, DatePickerSample, DynamicColorSchemeSample, EdgeButtonSample, ListHeaderSample, OneHandedGestureSamples, OpenOnPhoneDialogSample, PageIndicatorSample, PagerScaffoldSample, PickerGroupSample, PickerSample, PlaceholderSample, RadioButtonSample, ScaffoldSample, ScrollAwaySample, ScrollIndicatorSample, StepperSample, SurfaceTransformationSample, SwipeDismissableSceneStrategySample, SwipeToDismissBoxSample, SwipeToRevealSample, SwitchButtonSample, TextButtonSample, TextToggleButtonSample, TimePickerSample, TransformationSpecSample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample
TextButton	TextButtonSample
TextButtonDefaults	TextButtonSample, TextToggleButtonSample
TextToggleButton, TextToggleButtonDefaults, touchTargetAwareSize	TextToggleButtonSample
TimePicker, TimePickerType	TimePickerSample
TimeText	ScrollAwaySample, ScrollIndicatorSample, TimeTextSample
TimeTextDefaults, timeTextCurvedText	TimeTextSample
TitleCard	CardSample, SurfaceTransformationSample, SwipeDismissableSceneStrategySample, SwipeToRevealSample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample
TransformationSpec	TransformationSpecSample
curvedText	CurvedTextSamples, ScrollAwaySample, TimeTextSample
firstVisibleItemLayoutItemInfo [rc], layoutItemInfoOf [rc], rememberTransformingLazyColumnFirstLayoutItemProvider [rc]	TransformingLazyColumnSample
placeholder, placeholderShimmer, rememberPlaceholderState	PlaceholderSample
rememberPickerState	PickerGroupSample, PickerSample
rememberTransformationSpec, transformedHeight	AlertDialogSample, DynamicColorSchemeSample, ListHeaderSample, ScaffoldSample, SurfaceTransformationSample, SwipeDismissableSceneStrategySample, SwipeToRevealSample, TransformationSpecSample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample, TransformingLazyColumnSample
timeTextSeparator	ScrollAwaySample, TimeTextSample

Foundation components in androidx.wear.compose.foundation.*

Component / Symbol	Reference Samples
AmbientMode, LocalAmbientModeManager, rememberAmbientModeManager	AmbientModeSample, OneHandedGestureSamples
AmbientTickEffect	AmbientModeSample
BasicSwipeToDismissBox	SwipeToDismissBoxSample
CurvedAlignment, CurvedTextStyle, angularGradientBackground, angularSize, basicCurvedText, clearAndSetSemantics, curvedColumn, padding, radialGradientBackground, radialSize, semantics, size	CurvedWorldSample
CurvedDirection, CurvedLayout, angularSizeDp, background, curvedBox, curvedComposable, curvedRow	CurvedTextSamples, CurvedWorldSample
CurvedModifier	CurvedTextSamples, CurvedWorldSample, TimeTextSample
HorizontalPager, VerticalPager, rememberPagerState	OneHandedGestureSamples, PageIndicatorSample, PagerSamples, PagerScaffoldSample
PagerDefaults	PagerScaffoldSample
RotaryScrollableDefaults	PagerScaffoldSample, RotarySamples, TransformingLazyColumnSample
RotarySnapLayoutInfoProvider, rotaryScrollable	RotarySamples
ScrollInfoProvider	ScrollAwaySample
SwipeToDismissValue, edgeSwipeToDismiss, rememberSwipeToDismissBoxState	SwipeToDismissBoxSample, SwipeToDismissBoxSample
TransformingLazyColumn	DynamicColorSchemeSample, ListHeaderSample, OneHandedGestureSamples, ScaffoldSample, ScrollAwaySample, ScrollIndicatorSample, SurfaceTransformationSample, SwipeDismissableSceneStrategySample, SwipeToRevealSample, TransformationSpecSample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample, TransformingLazyColumnSample
TransformingLazyColumnDefaults	TransformingLazyColumnSample
TransformingLazyColumnItemScrollProgress	TransformationSpecSample
expandableButton, expandableItem, expandableItems, rememberExpandableState	ExpandableSample
hierarchicalFocusGroup	HierarchicalFocusSample
items	SwipeDismissableSceneStrategySample, SwipeToRevealSample, TransformingLazyColumnNotificationsSample
itemsIndexed	TransformingLazyColumnSample
rememberTransformingLazyColumnState	ListHeaderSample, OneHandedGestureSamples, ScaffoldSample, ScrollAwaySample, ScrollIndicatorSample, SurfaceTransformationSample, SwipeDismissableSceneStrategySample, SwipeToRevealSample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample, TransformingLazyColumnSample
requestFocusOnHierarchyActive	HierarchicalFocusSample, RotarySamples
weight	CurvedWorldSample, TimeTextSample

Navigation 3 components in androidx.wear.compose.navigation3.*

Component / Symbol	Reference Samples
rememberSwipeDismissableSceneStrategy	SwipeDismissableSceneStrategySample

Capability 3: Component guidance

Mandatory: Use this capability as a checklist against any component use. It provides more holistic guidance on how to use each component in practice, beyond the component syntax.

1. AppScaffold and ScreenScaffold

   • [ ] Use AppScaffold as the outer container, with ScreenScaffold children.
   • [ ] Use only ONE AppScaffold and any number of ScreenScaffold.

2. ScalingLazyColumn - Use TransformingLazyColumn instead.

3. TransformingLazyColumn - You will need the following imports:

   import androidx.wear.compose.foundation.lazy.TransformingLazyColumn
   import androidx.wear.compose.foundation.lazy.TransformingLazyColumnDefaults
   import androidx.wear.compose.foundation.lazy.rememberTransformingLazyColumnState
   // ...
   import androidx.wear.compose.material3.lazy.rememberTransformationSpec
   import androidx.wear.compose.material3.lazy.transformedHeight
   

   Canonical example:

   val columnState = rememberTransformingLazyColumnState()
   val transformationSpec = rememberTransformationSpec()
   ScreenScaffold(
       scrollState = columnState
   ) { contentPadding ->
       TransformingLazyColumn(
           state = columnState,
           contentPadding = contentPadding
       ) {
           item {
               ListHeader(
                   modifier = Modifier
                       .fillMaxWidth()
                       .transformedHeight(this, transformationSpec)
                       .minimumVerticalContentPadding(ListHeaderDefaults.minimumTopListContentPadding),
                   transformation = SurfaceTransformation(transformationSpec)
               ) {
                   Text(text = "Header")
               }
           }
           // ... other items
           item {
               Button(
                   modifier = Modifier
                       .fillMaxWidth()
                       .transformedHeight(this, transformationSpec)
                       .minimumVerticalContentPadding(ButtonDefaults.minimumVerticalListContentPadding),
                   transformation = SurfaceTransformation(transformationSpec),
                   onClick = { /* ... */ },
                   icon = {
                       Icon(
                           imageVector = Icons.Default.Build,
                           contentDescription = "build",
                       )
                   },
               ) {
                   Text(
                       text = "Build",
                       maxLines = 1,
                       overflow = TextOverflow.Ellipsis,
                   )
               }
           }
       }
   }
   

   • [ ] Use TransformingLazyColumn instead of ScalingLazyColumn.
   • [ ] You must pass the contentPadding parameter from ScreenScaffold to the TransformingLazyColumn.
   • [ ] Use the minimumVerticalContentPadding modifier to achieve required padding top and bottom.
     • This expects a value from defaults, such as ButtonDefaults, CardDefaults, ListHeaderDefaults.
     • Note: This is a scoped modifier available within TransformingLazyColumnItemScope.
   • [ ] Ensure items morph and scale (apply to components within TransformingLazyColumn, not the list itself):
     • [ ] Use Modifier.transformedHeight(this, transformationSpec).
     • [ ] Use transformation = SurfaceTransformation(transformationSpec).
   • [ ] If configuring a list for snapping, use flingBehavior and rotaryScrollableBehavior together:

   val columnState = rememberTransformingLazyColumnState()
   ScreenScaffold(scrollState = columnState) { contentPadding ->
       TransformingLazyColumn(
           state = columnState,
           flingBehavior = TransformingLazyColumnDefaults.snapFlingBehavior(columnState),
           rotaryScrollableBehavior = RotaryScrollableDefaults.snapBehavior(columnState)
       ) {
           // ...
           // ...
       }
   }
   

4. ScreenScaffold

   • [ ] Guard the scrollIndicator with !LocalScrollCaptureInProgress.current (androidx.compose.ui.platform).

5. EdgeButton

   • [ ] Do NOT use as the final item within a TransformingLazyColumn. Instead, use the slot in ScreenScaffold.
   • [ ] When used in a TransformingLazyColumn, add the required overscroll behavior:

   val columnState = rememberTransformingLazyColumnState()
   ScreenScaffold(
       scrollState = columnState,
       edgeButton = {
           EdgeButton(
               onClick = { /* TODO */ },
               modifier = Modifier.scrollable(
                   columnState,
                   orientation = Orientation.Vertical,
                   reverseDirection = true,
                   // Apply overscroll to the EdgeButton for proper scrolling behavior.
                   overscrollEffect = rememberOverscrollEffect(),
               )
           ) {
               Text("More")
           }
       }
   ) { contentPadding ->
       TransformingLazyColumn(
           contentPadding = contentPadding,
           state = columnState,
       ) {
           // ...
           // ...
       }
   }
   

6. Column

   • [ ] USE as a direct child of ScreenScaffold if the screen will never scroll, even with the largest system font.
   • [ ] Use TransformingLazyColumn instead for all other cases.

7. Styles

   • [ ] Do NOT hard-code text sizes, use typography from MaterialTheme.
   • [ ] Do NOT hard-code colors, use colorScheme from MaterialTheme.

8. Use component defaults:

   • [ ] Components such as Button have a corresponding ButtonDefaults object.
   • [ ] Check for and use the *Defaults object for any component when working with padding and styling values, in preference to hard-coded values.

9. Use Wear-specific preview annotations (androidx.wear.compose.ui.tooling.preview):

   • [ ] @WearPreviewDevices
   • [ ] @WearPreviewFontScales
   • [ ] Ensure the androidx.wear.compose:compose-ui-tooling dependency is included.

10. Ambient mode

    • [ ] Use LocalAmbientModeManager (provided by CompositionLocalProvider and rememberAmbientModeManager()) instead of AmbientLifecycleObserver.

11. Navigation

    • [ ] When adding navigation fresh, use Navigation3 (androidx.wear.compose:compose-navigation3).
    • [ ] Use rememberSwipeDismissableSceneStrategy() / SwipeDismissableSceneStrategy (androidx.wear.compose.navigation3).

12. Comments

    • [ ] Where any Kotlin file has been modified, ensure that the existing comments are up to date and accurately reflect any changes to the implementation.

13. HorizontalPager or VerticalPager

    • [ ] Use the Composable hierarchy in this order: AppScaffold, HorizontalPagerScaffold, HorizontalPager, AnimatedPage, ScreenScaffold. Or similarly for VerticalPager.