# Picker

## Functions summary

|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable https://developer.android.com/reference/kotlin/androidx/wear/compose/material3/Picker.composable#Picker(androidx.wear.compose.material3.PickerState,kotlin.Function0,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Function1,kotlin.Function0,androidx.compose.ui.unit.Dp,kotlin.Float,androidx.compose.ui.graphics.Color,kotlin.Boolean,androidx.wear.compose.foundation.rotary.RotaryScrollableBehavior,kotlin.Function2)( state: https://developer.android.com/reference/kotlin/androidx/wear/compose/material3/PickerState, contentDescription: (() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)?, modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier, readOnly: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, readOnlyLabel: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/BoxScope.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)?, onSelected: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html, verticalSpacing: https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp, gradientRatio: @https://developer.android.com/reference/kotlin/androidx/annotation/FloatRange(from = 0.0, to = 0.5) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, gradientColor: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Color, userScrollEnabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, rotaryScrollableBehavior: https://developer.android.com/reference/kotlin/androidx/wear/compose/foundation/rotary/RotaryScrollableBehavior?, option: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable https://developer.android.com/reference/kotlin/androidx/wear/compose/material3/PickerScope.(index: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html )` A scrollable list of items to pick from. |

## Functions

### Picker

Artifact: [androidx.wear.compose:compose-material3](https://developer.android.com/jetpack/androidx/releases/wear-compose) [View Source](https://cs.android.com/search?q=file:androidx/wear/compose/material3/Picker.kt+function:Picker)

```
@Composable
fun Picker(
    state: PickerState,
    contentDescription: (() -> String)?,
    modifier: Modifier = Modifier,
    readOnly: Boolean = false,
    readOnlyLabel: (@Composable BoxScope.() -> Unit)? = null,
    onSelected: () -> Unit = {},
    verticalSpacing: Dp = 0.dp,
    gradientRatio: @FloatRange(from = 0.0, to = 0.5) Float = PickerDefaults.GradientRatio,
    gradientColor: Color = MaterialTheme.colorScheme.background,
    userScrollEnabled: Boolean = true,
    rotaryScrollableBehavior: RotaryScrollableBehavior? = PickerDefaults.rotarySnapBehavior(state),
    option: @Composable PickerScope.(index: Int) -> Unit
): Unit
```

A scrollable list of items to pick from. By default, items will be repeated "infinitely" in both directions, unless PickerState#repeatItems is specified as false.

Picker supports rotary input by default. Rotary input allows users to scroll the content of the `https://developer.android.com/reference/kotlin/androidx/wear/compose/material3/Picker.composable#Picker(androidx.wear.compose.material3.PickerState,kotlin.Function0,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Function1,kotlin.Function0,androidx.compose.ui.unit.Dp,kotlin.Float,androidx.compose.ui.graphics.Color,kotlin.Boolean,androidx.wear.compose.foundation.rotary.RotaryScrollableBehavior,kotlin.Function2)` - by using a crown or a rotating bezel on their Wear OS device. It can be modified or turned off using the `https://developer.android.com/reference/kotlin/androidx/wear/compose/material3/package-summary#Picker(androidx.wear.compose.material3.PickerState,kotlin.Function0,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Function1,kotlin.Function0,androidx.compose.ui.unit.Dp,kotlin.Float,androidx.compose.ui.graphics.Color,kotlin.Boolean,androidx.wear.compose.foundation.rotary.RotaryScrollableBehavior,kotlin.Function2)` parameter.

Example of a simple picker to select one of five options:

```kotlin
import androidx.compose.foundation.gestures.Orientation
import androidx.compose.foundation.gestures.scrollable
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.runtime.derivedStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.wear.compose.material3.Picker
import androidx.wear.compose.material3.Text
import androidx.wear.compose.material3.rememberPickerState

val items = listOf("One", "Two", "Three", "Four", "Five")
val state = rememberPickerState(items.size)
// We forward scroll gestures from the whole screen to the Picker which makes this sample
// accessible for 2-finger vertical scrolling.
Box(
    modifier =
        Modifier.fillMaxSize()
            .scrollable(
                state = state,
                orientation = Orientation.Vertical,
                reverseDirection = true,
            ),
    contentAlignment = Alignment.Center,
) {
    val selectedLabel by remember {
        derivedStateOf { "Selected: ${items[state.selectedOptionIndex]}" }
    }
    Text(
        modifier = Modifier.align(Alignment.TopCenter).padding(top = 10.dp),
        text = selectedLabel,
    )
    Picker(
        modifier = Modifier.size(100.dp, 100.dp),
        state = state,
        contentDescription = { "${state.selectedOptionIndex + 1}" },
    ) {
        Text(items[it])
    }
}
```

![SimplePicker Composite
Image](https://developer.android.com/wear/images/design/WearComposeM3_SimplePicker_CompositeImage.png)

Example of a sample picker group with an hour and minute picker (24 hour format):

```kotlin
import androidx.compose.animation.AnimatedContent
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.size
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.wear.compose.material3.PickerGroup
import androidx.wear.compose.material3.Text
import androidx.wear.compose.material3.rememberPickerState

var selectedPickerIndex by remember { mutableIntStateOf(0) }
val pickerStateHour = rememberPickerState(initialNumberOfOptions = 24)
val pickerStateMinute = rememberPickerState(initialNumberOfOptions = 60)
Column(
    modifier = Modifier.fillMaxWidth(),
    verticalArrangement = Arrangement.Center,
    horizontalAlignment = Alignment.CenterHorizontally,
) {
    Spacer(modifier = Modifier.size(30.dp))
    val label = if (selectedPickerIndex == 0) "Hours" else "Minutes"
    AnimatedContent(targetState = label) { targetText -> Text(text = targetText) }
    Spacer(modifier = Modifier.size(10.dp))
    PickerGroup(
        selectedPickerState =
            if (selectedPickerIndex == 0) pickerStateHour else pickerStateMinute,
        autoCenter = false,
    ) {
        PickerGroupItem(
            pickerState = pickerStateHour,
            selected = selectedPickerIndex == 0,
            onSelected = { selectedPickerIndex = 0 },
            option = { optionIndex, _ -> Text(text = "%02d".format(optionIndex)) },
            contentDescription = { "Hours" },
            modifier = Modifier.size(80.dp, 100.dp),
        )

        PickerGroupItem(
            pickerState = pickerStateMinute,
            selected = selectedPickerIndex == 1,
            onSelected = { selectedPickerIndex = 1 },
            option = { optionIndex, _ -> Text(text = "%02d".format(optionIndex)) },
            contentDescription = { "Minutes" },
            modifier = Modifier.size(80.dp, 100.dp),
        )
    }
}
```

![PickerGroupSample Composite
Image](https://developer.android.com/wear/images/design/WearComposeM3_PickerGroupSample_CompositeImage.png)

| Parameters |
|---|---|
| `state: https://developer.android.com/reference/kotlin/androidx/wear/compose/material3/PickerState` | The state of the component |
| `contentDescription: (() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)?` | A block which computes text used by accessibility services to describe what the selected option represents. This text should be localized, such as by using `https://developer.android.com/reference/kotlin/androidx/compose/ui/res/stringResource.composable#stringResource(kotlin.Int)` or similar. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier = Modifier` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier` to be applied to the Picker. |
| `readOnly: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = false` | Determines whether the `https://developer.android.com/reference/kotlin/androidx/wear/compose/material3/Picker.composable#Picker(androidx.wear.compose.material3.PickerState,kotlin.Function0,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Function1,kotlin.Function0,androidx.compose.ui.unit.Dp,kotlin.Float,androidx.compose.ui.graphics.Color,kotlin.Boolean,androidx.wear.compose.foundation.rotary.RotaryScrollableBehavior,kotlin.Function2)` should display other available options for this field, inviting the user to scroll to change the value. When readOnly = true, only displays the currently selected option (and optionally a label). This is intended to be used for screens that display multiple Pickers, only one of which has the focus at a time. |
| `readOnlyLabel: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/BoxScope.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)? = null` | A slot for providing a label, displayed above the selected option when the `https://developer.android.com/reference/kotlin/androidx/wear/compose/material3/Picker.composable#Picker(androidx.wear.compose.material3.PickerState,kotlin.Function0,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Function1,kotlin.Function0,androidx.compose.ui.unit.Dp,kotlin.Float,androidx.compose.ui.graphics.Color,kotlin.Boolean,androidx.wear.compose.foundation.rotary.RotaryScrollableBehavior,kotlin.Function2)` is read-only. The label is overlaid with the currently selected option within a Box, so it is recommended that the label is given `https://developer.android.com/reference/kotlin/androidx/compose/ui/Alignment#TopCenter()`. |
| `onSelected: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html = {}` | Action triggered when the Picker is selected by clicking. Used by accessibility semantics, which facilitates implementation of multi-picker screens. |
| `verticalSpacing: https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp = 0.dp` | The amount of vertical spacing in `https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp` between items. Can be negative, which can be useful for Text if it has plenty of whitespace. |
| `gradientRatio: @https://developer.android.com/reference/kotlin/androidx/annotation/FloatRange(from = 0.0, to = 0.5) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html = PickerDefaults.GradientRatio` | The size relative to the Picker height that the top and bottom gradients take. These gradients blur the picker content on the top and bottom. The default is 0.33, so the top 1/3 and the bottom 1/3 of the picker are taken by gradients. Should be between 0.0 and 0.5. Use 0.0 to disable the gradient. |
| `gradientColor: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Color = MaterialTheme.colorScheme.background` | Should be the color outside of the Picker, so there is continuity. If using custom background (gradients, images), gradientColor must be set to `https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Color#Unspecified()` |
| `userScrollEnabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = true` | Determines whether the picker should be scrollable or not. When userScrollEnabled = true, picker is scrollable. This is different from `https://developer.android.com/reference/kotlin/androidx/wear/compose/material3/package-summary#Picker(androidx.wear.compose.material3.PickerState,kotlin.Function0,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Function1,kotlin.Function0,androidx.compose.ui.unit.Dp,kotlin.Float,androidx.compose.ui.graphics.Color,kotlin.Boolean,androidx.wear.compose.foundation.rotary.RotaryScrollableBehavior,kotlin.Function2)` as it changes the scrolling behaviour. |
| `rotaryScrollableBehavior: https://developer.android.com/reference/kotlin/androidx/wear/compose/foundation/rotary/RotaryScrollableBehavior? = PickerDefaults.rotarySnapBehavior(state)` | Parameter for changing rotary behavior. We recommend to use `https://developer.android.com/reference/kotlin/androidx/wear/compose/material3/PickerDefaults#rotarySnapBehavior(androidx.wear.compose.material3.PickerState)` for Pickers, but passing null turns off the rotary handling if it is not required. |
| `option: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable https://developer.android.com/reference/kotlin/androidx/wear/compose/material3/PickerScope.(index: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | A block which describes the content. Inside this block you can reference `https://developer.android.com/reference/kotlin/androidx/wear/compose/material3/PickerScope#selectedOptionIndex()` to determine which option is selected. When read-only mode is in use on a screen, it is recommended that this content is given `https://developer.android.com/reference/kotlin/androidx/compose/ui/Alignment#Center()` in order to align with the centrally selected Picker value. |