Wear Compose

API Reference
androidx.wear.compose.material

Write Jetpack Compose applications for Wearable devices by providing functionality to support wearable specific devices, sizes, shapes and navigation gestures.

Latest Update	Current Stable Release	Next Release Candidate	Beta Release	Alpha Release
January 26, 2022	-	-	-	1.0.0-alpha15

Declaring dependencies

To add a dependency on Wear, you must add the Google Maven repository to your project. Read Google's Maven repository for more information.

Add the dependencies for the artifacts you need in the build.gradle file for your app or module:

Groovy

dependencies {
    implementation "androidx.wear.compose:compose-foundation:1.0.0-alpha15"

    // For Wear Material Design UX guidelines and specifications
    implementation "androidx.wear.compose:compose-material:1.0.0-alpha15"

    // For integration between Wear Compose and Androidx Navigation libraries
    implementation "androidx.wear.compose:compose-navigation:1.0.0-alpha15"

    // NOTE: DO NOT INCLUDE a dependency on androidx.compose.material:material.
    // androidx.wear.compose:compose-material is designed as a replacement
    // not an addition to androidx.compose.material:material.
    // If there are features from that you feel are missing from
    // androidx.wear.compose:compose-material please raise a bug to let us know.
}

Kotlin

dependencies {
    implementation("androidx.wear.compose:compose-foundation:1.0.0-alpha15")

    // For Wear Material Design UX guidelines and specifications
    implementation("androidx.wear.compose:compose-material:1.0.0-alpha15")

    // For integration between Wear Compose and Androidx Navigation libraries
    implementation("androidx.wear.compose:compose-navigation:1.0.0-alpha15")

    // NOTE: DO NOT INCLUDE a dependency on androidx.compose.material:material.
    // androidx.wear.compose:compose-material is designed as a replacement
    // not an addition to androidx.compose.material:material.
    // If there are features from that you feel are missing from
    // androidx.wear.compose:compose-material please raise a bug to let us know.
}

For more information about dependencies, see Add build dependencies.

Feedback

Your feedback helps make Jetpack better. Let us know if you discover new issues or have ideas for improving this library. Please take a look at the existing issues in this library before you create a new one. You can add your vote to an existing issue by clicking the star button.

Create a new issue

See the Issue Tracker documentation for more information.

Version 1.0

Version 1.0.0-alpha15

January 26, 2022

androidx.wear.compose:compose-foundation:1.0.0-alpha15, androidx.wear.compose:compose-material:1.0.0-alpha15, and androidx.wear.compose:compose-navigation:1.0.0-alpha15 are released. Version 1.0.0-alpha15 contains these commits.

API Changes

We have added a new property autoCentering to the ScalingLazyColumn. When true (the default) this will ensure that all items including the first and last can be scrolled so that they are visible in the center of the lists viewport. Note that if using auto-centering you will probably want to set vertical content padding to 0.dp. If both autoCentering and vertical content padding are provided then they will both result in additional space being available before the first and after the last list items allowing them to be scrolled even further. (I2a282, b/214922490)
We have added a Dialog component that enables any composable to trigger a full screen dialog that sits on top of other content. When shown, the dialog supports swipe-to-dismiss and will show its parent's content in the background during the swipe gesture. The dialog content is expected to be Alert or Confirmation (renamed from earlier components AlertDialog and ConfirmationDialog) - Alert, Confirmation and Dialog are all in the androidx.wear.compose.material.dialog package. Alert and Confirmation can be used as navigation destinations. Also, added ColumnScope to Alert and Confirmation parameters as necessary. (Ia9014)
We have removed onSurfaceVariant2 from the Compose for WearOS Material Theme Colors and replaced uses in the library with onSurfaceVariant. (Icd592)
Added a method to programmatically select an option on the PickerState, the initially selected option can now also be specified when creating a PickerState. (I92bdf)
We have added support for customizing the fling behavior of the ScalingLazyColumn. (I1ad2e, b/208842968)
We have added NavController.currentBackStackEntryAsState() to the Wear.Compose.Navigation library. (If9028, b/212739653)
Added Modifier.onRotaryScrollEvent() and Modifier.onPreRotaryScrollEvent() for Wear devices with a rotating side button.(I18bf5, b/210748686)

Version 1.0.0-alpha14

January 12, 2022

androidx.wear.compose:compose-foundation:1.0.0-alpha14, androidx.wear.compose:compose-material:1.0.0-alpha14, and androidx.wear.compose:compose-navigation:1.0.0-alpha14 are released. Version 1.0.0-alpha14 contains these commits.

New Features

We have added a number of methods to ScalingLazyListState to allow developer control over scrolling to specific list items and also setting the initial list item and offset.

As part of this change we have also modified the ScalingLazyList so that it is oriented around the center of the viewport of the ScalingLazyList rather than the start of the viewport.

A new property anchorType: ScalingLazyListAnchorType = ScalingLazyListAnchorType.ItemCenter has been added to the ScalingLazyList to control whether the center (ScalingLazyListAnchorType.ItemCenter) or Edge (ScalingLazyListAnchorType.ItemStart) should be aligned to the viewport's centerline.

As a result the ScalingLazyListItemInfo.offset and ScalingLazyListItemInfo.adjustedOffset have changed and will now reflect the offset of the item with respect to both the position of the list item and the anchorType of the list. E.g. for a ScalingLazyColumn with anchorType of ItemCenter and an list item positioned with its center on the centerline of the viewport the offset would be 0.

The new methods are scrollTo, animatedScrollTo, centerItemIndex, and centerItemOffset. (I61b61)
We have added a back button handler to SwipeDismissableNavHost, so that pressing back navigates to the previous level in the navigation hierarchy. (I5b086, b/210205624)

Version 1.0.0-alpha13

December 15, 2021

androidx.wear.compose:compose-foundation:1.0.0-alpha13, androidx.wear.compose:compose-material:1.0.0-alpha13, and androidx.wear.compose:compose-navigation:1.0.0-alpha13 are released. Version 1.0.0-alpha13 contains these commits.

API Changes

We have made RangeIcons internal (referenced internally by InlineSlider and Stepper). (I927ec)

Bug Fixes

Fixed an issue where SwipeDismissableNavHost would add a destination to the Compose hierarchy before it has reached the CREATED Lifecycle state, resulting in an IllegalStateException. This fix was a prerequisite to updating dependency on navigation-compose to 2.4.0-beta02 and beyond. (I40a2b, b/207328687)
Added a Drawables enum class for getting drawable resources within the Wear Compose library, so that reflection is no longer needed. This fixes a bug where library drawables were removed when minifyEnabled=true or shrinkResources=true). (Ib2a98)
Added tests for Stepper in Wear Compose (I2d03a)
Added samples for SwipeDismissableNavHost in Wear Compose Navigation. (I85f06)

Version 1.0.0-alpha12

December 1, 2021

androidx.wear.compose:compose-foundation:1.0.0-alpha12, androidx.wear.compose:compose-material:1.0.0-alpha12, and androidx.wear.compose:compose-navigation:1.0.0-alpha12 are released. Version 1.0.0-alpha12 contains these commits.

New Features

We have added a Stepper component which allows users to make a selection from a range of values. Stepper is a full-screen control with increase and decrease buttons at the top and bottom, and a slot in the middle (expected to take either a Chip or Text). The button icons can be customized if required. (I625fe)
We have added 2 new composables for displaying dialogs: AlertDialog waits for a response from the user and displays a title, icon, message and either a) two buttons for simple positive/negative choices or b) vertically stacked chips or toggle chips for more flexible choices, ConfirmationDialog displays an acknowledgement with a timeout. This simple dialog has slots for a title and an (animated) icon. (Ic2cf8)

API Changes

Add units (millis) to suggested dialog duration values. (I09b48)

Version 1.0.0-alpha11

November 17, 2021

androidx.wear.compose:compose-foundation:1.0.0-alpha11, androidx.wear.compose:compose-material:1.0.0-alpha11, and androidx.wear.compose:compose-navigation:1.0.0-alpha11 are released. Version 1.0.0-alpha11 contains these commits.

New Features

We have added a picker component that lets the user select an item from a scrolling list. By default, the list of selectable items is repeated 'infinitely' in both directions, to give the impression of a rotating cylinder seen from the side. Two features will be added in later releases: snapping to a value after a swipe/fling; adding a function to PickerState to set/scroll to the current value. (I6461b)

API Changes

Added a ScalingLazyItemScope and some new modifiers fillParentMaxSize/fillParentMaxWidth/fillParentMaxHeight to allow list items to be sized based on the size of the parent container. Items can be set to fill all or a fraction of the parent’s size. This exposes functionality already available in the LazyRow/Column (I4612f)
Added support to ScalingLazyColumn to allow items to have a key. Also added convenience methods to allow adding of items from Arrays and Lists. (Ic1f89)

Bug Fixes

Additional examples for TimeText (I8cb64)

Version 1.0.0-alpha10

November 3, 2021

androidx.wear.compose:compose-foundation:1.0.0-alpha10, androidx.wear.compose:compose-material:1.0.0-alpha10, and androidx.wear.compose:compose-navigation:1.0.0-alpha10 are released. Version 1.0.0-alpha10 contains these commits.

New Features

Added an InlineSlider for wear compose. InlineSlider allows users to make a selection from a range of values. The range of selections is shown as a bar between the minimum and maximum values of the range, from which users may select a single value. (If0148)
Check out the new Compose for WearOS Codelab!

API Changes

Macrobenchmark now has a minSdkVersion of 23. (If2655)

Bug Fixes

Update transition handling in SwipeDismissableNavHost in a SideEffect (I04994, b/202863359)
Update transition handling in SwipeDismissableNavHost (I1cbe0, b/202863359)

Version 1.0.0-alpha09

October 27, 2021

androidx.wear.compose:compose-foundation:1.0.0-alpha09, androidx.wear.compose:compose-material:1.0.0-alpha09, and androidx.wear.compose:compose-navigation:1.0.0-alpha09 are released. Version 1.0.0-alpha09 contains these commits.

New Features

We have launched the Developer Preview of Compose on Wear OS - see our blog post which reviews the main composables and links to further resources to starting using them.

API Changes

We have added support for developers to be able to customize all of the colors in the Wear Material Design Color theme. (I4759b, b/199754668)

Bug Fixes

Added SwipeToDismissBox samples that persist state (Ibaffe)
Added links to developer.android.com guides from KDocs for CurvedText, TimeText and SwipeToDismissBox. (I399d4)
SwipeDismissableNavHost now throws if there's no current destination (indicates that the NavGraph was not built with the wear.compose.navigation.composable utility function) (I91403)
Added additional documentation and examples for time source usage in TimeText (I4f6f0)

Version 1.0.0-alpha08

October 13, 2021

androidx.wear.compose:compose-foundation:1.0.0-alpha08, androidx.wear.compose:compose-material:1.0.0-alpha08, and androidx.wear.compose:compose-navigation:1.0.0-alpha08 are released. Version 1.0.0-alpha08 contains these commits.

API Changes

We have renamed AppCard and TitleCard body properties to content and moved them to the end of the property list to allow them to be provided as a trailing lambda. Also renamed bodyColor to contentColor for consistency with the new slot names. (I57e78)

Bug Fixes

Added links to developer.android.com guides from KDocs for button, card, chip, theme, position indicator and scaling lazy column components. (I22428)
Fix WearOS SwipeToDismissBox sometimes not handling swipes. (I9387e)
Added samples for Button, CompactButton, Chip, CompactChip, AppCard, TitleCard, ToggleButton, ToggleChip, SplitToggleChip (Iddc15)
Added microbenchmark performance tests for Card, Chip, ToggleChip, TimeText and ScalingLazyColumn. (If2fe9)

Version 1.0.0-alpha07

September 29, 2021

androidx.wear.compose:compose-foundation:1.0.0-alpha07, androidx.wear.compose:compose-material:1.0.0-alpha07, and androidx.wear.compose:compose-navigation:1.0.0-alpha07 are released. Version 1.0.0-alpha07 contains these commits.

New Features

Added a CurvedText component in material, a component allowing developers to easily write curved text following the curvature of a circle (usually at the edge of a circular screen). (I19593)

API Changes

Added tests for TimeText (Idfead)
Transform ArcPaddingValues into an interface. (Iecd4c)
Added animation to SwipeToDismissBox (I9ad1b)
Added hasBackground parameter to the SwipeToDismissBox API so that the swipe gesture can be disabled when there is no background content to display. (I313d8)
rememberNavController() now takes a optional set of Navigator instances that will be added to the returned NavController to better support optional Navigators such as those from Accompanist Navigation Material. (I4619e)
Reference NamedNavArgument from navigation-common and remove copy from wear.compose.navigation. (I43af6)

Bug Fixes

Fixed CurvedRow test flakiness on smaller devices. (If7941)
Fixed possible flickering on CurvedRow when the content updates, and ensures the curved row is remeasured (Ie4e06)
ChipDefaults.gradientBackgroundChipColors() has been updated in line with UX Spec changes. The gradient now starts with MaterialTheme.colors.primary with alpha 32.5% and ends with MaterialTheme.colors.surface with alpha @ 0% over a background of MaterialTheme.colors.surface @ 75% alpha. (Id1548)
We have updated the colors for ToggleChips when in the selected state to match the latest Wear Material Design UX Spec guidance. When selected ToggleChips now have a gradient background from MaterialTheme.color.surface @ 0% alpha, top left, to MaterialTheme.color.primary @ 32% alpha, bottom right, over a background of MaterialTheme.color.surface @ 75% alpha. This results in a more subtle difference between checked and unchecked for the ToggleChip. (Idd40b)

Version 1.0.0-alpha06

September 15, 2021

androidx.wear.compose:compose-foundation:1.0.0-alpha06, androidx.wear.compose:compose-material:1.0.0-alpha06, and androidx.wear.compose:compose-navigation:1.0.0-alpha06 are released. Version 1.0.0-alpha06 contains these commits.

New Features

We have added Scaffold a top level application composable that provides a structure for handling PositionIndicators (like Scroll or Volume) position, an area at the top of the screen for displaying the time and application status, and also supports a Vignette to blur the screen top and bottom edge for scrollable content. The main area of the Scaffold is where the application contents are placed. (I5e0bf)
Added TimeText implementation for Wear Compose (I5654c)

Wear Compose Navigation Library

We have added the first release of the Wear Compose Navigation library, which provides integration between the Wear Compose and Androidx Navigation libraries. It provides a simple means to navigate between @Composable functions as the destinations in your application.
This initial release provides:
- A SwipeDismissableNavHost composable that hosts a navigation graph and provides backwards navigation via swipe gestures
- NavGraphBuilder.composable extension to assist with constructing navigation graphs
- rememberSwipeDismissableNavController() to allow hoisting state

Example usage where we create two screens and navigate between them:

val navController = rememberSwipeDismissableNavController()
SwipeDismissableNavHost(
    navController = navController,
    startDestination = "start"
) {
    composable("start") {
        Column(
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.Center,
            modifier = Modifier.fillMaxSize(),
        ) {
            Button(onClick = { navController.navigate("next") }) {
                Text("Go")
            }
        }
    }
    composable("next") {
        Column(
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.Center,
            modifier = Modifier.fillMaxSize(),
        ) {
            Text("Swipe to go back")
        }
    }
}

Wear Compose Navigation is packaged as a separate library so that simple WearCompose applications that implement their own hand-rolled navigation are not required to depend on the Androidx Navigation library.

API Changes

Updated SwipeDismissableNavHost to support rememberSaveable by setting the key identity for background and content (I746fd)
We have added a PositionIndicator adapter that can handle LazyListState (I21b88)
Updated SwipeToDismissBox to support rememberSaveable (Ie728b)
We have added reverseLayout support to the ScalingLazyColumn. This allows for the reversing of the direction of scrolling and layout (I9e2fc)
Deprecated performGesture and GestureScope, which have been replaced by performTouchInput and TouchInjectionScope. (Ia5f3f, b/190493367)
We have renamed VignetteValue to VignettePosition and renamed VignetteValue.Both renamed to VignettePosition.TopAndBottom. (I57ad7)
We have renamed ScalingLazyColumnState to ScalingLazyListState, ScalingLazyColumnItemInfo to ScalingLazyListItemInfo, ScalingLazyColumnLayoutInfo to ScalingLazyListLayoutInfo and ScalingLazyColumnScope to ScalingLazyListScope in case we decide to add a ScalingLazyRow implementation in the future. (I22734)

Bug Fixes

Updated CompactChip documentation to describe what happens if neither an icon nor a label is provided. (I4ba88)
We have made some adjustments to the Wear card components. (I6b3d0)
1. TitleCard spacing between Title and Body reduced from 8.dp to 2.dp.
2. TitleCard header font changed from body to title3.
3. Card background gradient changed to make the background appear darker.

Version 1.0.0-alpha05

September 1, 2021

androidx.wear.compose:compose-foundation:1.0.0-alpha05 and androidx.wear.compose:compose-material:1.0.0-alpha05 are released. Version 1.0.0-alpha05 contains these commits.

API Changes

Mark ArcPaddingValues as @Stable (I57deb)
ScalingLazyColumnState now implements the ScrollableState interface giving developers programmatic access to scroll the component. (I47dbc)

Bug Fixes

We have reduced the spacing between Icon and Text in Chip and ToggleChip to bring them in line with updates to the UX Spec. (I83802)

Version 1.0.0-alpha04

August 18, 2021

androidx.wear.compose:compose-foundation:1.0.0-alpha04 and androidx.wear.compose:compose-material:1.0.0-alpha04 are released. Version 1.0.0-alpha04 contains these commits.

New Features

Added a SwipeToDismissBox and swipeable modifier that can be used to support a left-to-right swipe-to-dismiss gesture. Although independent of navigation components, this is expected to be used to exit one screen and navigate to another. Added integration tests to demo swipe-to-dismiss. (I7bbaa)
We have added ScalingLazyColumnItemInfo and ScalingLazyColumnLayoutInfo interfaces to ScalingLazyColumnState class to enable developers to know the actual positions and sizes of items in the ScalingLazyColumn after scaling has been applied. We have also fixed a bug with the way that scaling was calculated when 'top' content padding is applied to the ScalingLazyColumn. (I27c07)

API Changes

Add CurvedTextStyle class to specify curved text styling Options. Similar to TextStyle, but now only supports color, fontSize and background. More styling options will be added in the future. (I96ac3)
We have added ScalingLazyColumnItemInfo and ScalingLazyColumnLayoutInfo interfaces to ScalingLazyColumnState class to enable developers to know the actual positions and sizes of items in the ScalingLazyColumn after scaling has been applied. We have also fixed a bug with the way that scaling was calculated when 'top' content padding is applied to the ScalingLazyColumn. (I27c07)
Added @ExperimentalWearMaterialApi to SwipeDismissTarget enum, part of the SwipeToDismissBox API. (I48b5e)

Bug Fixes

Added test material for SwipeToDismissBox (I9febc)

Version 1.0.0-alpha03

August 4, 2021

androidx.wear.compose:compose-foundation:1.0.0-alpha03 and androidx.wear.compose:compose-material:1.0.0-alpha03 are released. Version 1.0.0-alpha03 contains these commits.

API Changes

Added CurvedText component, that allows developers to easily write text following the curvature a circle (usually at the edge of a circular screen) (Id1267)
We have renamed CardDefaults.imageBackgroundPainter() to CardDefaults.imageWithScrimBackgroundPainter() to make it clear that the background image with have a scrim drawn over it. (I53206)
Adding ScalingLazyColumn component that provides a list component for Wear Material that gives a fisheye view with the list contents scaling down in size and becoming transparent as they scale towards the edge of the component. (I7070c)

Bug Fixes

We changed the default color of the appName content in AppCard in response to a UX Spec update. The default color for the appName is now MaterialTheme.colors.onSurfaceVariant. Additionally added a missing parameter doc description for the title slot. (Ic4ad1)

Version 1.0.0-alpha02

July 21, 2021

androidx.wear.compose:compose-foundation:1.0.0-alpha02 and androidx.wear.compose:compose-material:1.0.0-alpha02 are released. Version 1.0.0-alpha02 contains these commits.

New Features

Added a new class CurvedRow to laid out composables in an arc (I29941)
Added a new type of card for use in applications (TitleCard), also add support for having images as the background to Cards to emphasize their contents (I53b0f)

API Changes

Add support for radial alignment to CurvedRow (similar to the vertical alignment in a row) (Id9de5)
Add a new class CurvedRow to laid out composables in an arc (I29941)
Added a new type of card for use in applications (TitleCard), also add support for having images as the background to Cards to emphasize their contents (I53b0f)
Added toggle icons (checkbox, switch and radio buttons) to ToggleChipDefaults to make it easier for developers to configure ToggleChip and SplitToggleChips (I7b639)
The start and end content padding for Chips has been updated so that it is consistently 14.dp regardless of whether the Chip has an icon present or not (was previously 12.dp if icon present and 14.dp if not) (I34c86)

Bug Fixes

Add tests for CurvedRow (I93cdb)
Tying Wear Compose dependencies to Compose 1.0.0-rc01. (Ie6bc9)
Changed the handing of background image painting in Cards and Chips so that the image is Cropped rather than being stretched in order to maintain image proportions. (I29b41)
Added more demos and integration tests for Button and ToggleButton. (5e27ed2)
Added more Chip tests to cover the content colors for imageBackgroundChips (Ia9183)

Version 1.0.0-alpha01

July 1, 2021

androidx.wear.compose:compose-foundation:1.0.0-alpha01 and androidx.wear.compose:compose-material:1.0.0-alpha01 are released. Version 1.0.0-alpha01 contains these commits.

New Features

Wear Compose is a Kotlin, Compose-based library that supports Wear Material design, an extension of Material Design for WearOS wearables. This first alpha release contains early, functional implementations of the following:

Material theme - configures the colors, typography and shapes consistently across the components used from this library.
Chip, CompactChip - chips are stadium shaped and variations are available to take icon, label and secondary label content.
- ToggleChip, SplitToggleChip - a specialized type of chip that includes a slot for a bi-state toggle icon such as a radio button or checkbox. In addition, the SplitToggleChip has two tappable areas, one clickable and one toggleable.
Button, CompactButton - buttons are circular in shape, with a single content slot for an icon or minimal text (maximum 3 characters).
ToggleButton - a button that turns an action on or off, with a single slot for icon or minimal text (maximum 3 characters).
Card, AppCard - rectangular shaped with rounded corners, offering slots for content such as app icon, time, title and body.

Future releases will extend the Widget set adding support for Wear Material Design pickers, sliders, lists, page indicators, dialogs, scroll rsb indicators, toasts and more.

Additionally support will be provided for other Wearable Specific features such as curved layouts and text, as well as scaffolding to make it easy for developers to build Wearable apps/overlays.

Wear Compose Material is designed with the same principles as Compose Material, although being targeted at wearables. The Wear Compose Material library should be used in place of the Compose Material library when building for a Wearable device.

The two “Material” libraries should be considered mutually exclusive and should not be mixed in the same app. If developers find themselves including the Compose Material library in their dependencies it would suggest that either a) there are components missing from the Wear Compose Material library, please let us know what you need, or b) are using a component that we do not recommend for use on a Wearable Device.