Picker

Composable Component

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.

Android

Deprecated Please use the new overload with additional rotaryBehavior parameter

@Composable
public fun Picker(
    state: PickerState,
    contentDescription: String?,
    modifier: Modifier = Modifier,
    readOnly: Boolean = false,
    readOnlyLabel: @Composable (BoxScope.() -> Unit)? = null,
    onSelected: () -> Unit = {},
    scalingParams: ScalingParams = PickerDefaults.defaultScalingParams(),
    separation: Dp = 0.dp,
    @FloatRange(from = 0.0, to = 0.5) gradientRatio: Float = PickerDefaults.DefaultGradientRatio,
    gradientColor: Color = MaterialTheme.colors.background,
    flingBehavior: FlingBehavior = PickerDefaults.flingBehavior(state),
    userScrollEnabled: Boolean = true,
    option: @Composable PickerScope.(optionIndex: Int) -> Unit,
)

Parameters


state	The state of the component
contentDescription	Text used by accessibility services to describe what the selected option represents. This text should be localized, such as by using `androidx.compose.ui.res.stringResource` or similar. Typically, the content description is inferred via derivedStateOf to avoid unnecessary recompositions, like this: val description by remember { derivedStateOf { /* expression using state.selectedOption */ } }
modifier	Modifier to be applied to the Picker
readOnly	Determines whether the Picker 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	A slot for providing a label, displayed above the selected option when the `Picker` is read-only. The label is overlaid with the currently selected option within a Box, so it is recommended that the label is given `Alignment.TopCenter`.
onSelected	Action triggered when the Picker is selected by clicking. Used by accessibility semantics, which facilitates implementation of multi-picker screens.
scalingParams	The parameters to configure the scaling and transparency effects for the component. See `ScalingParams`
separation	The amount of separation in `Dp` between items. Can be negative, which can be useful for Text if it has plenty of whitespace.
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	Should be the color outside of the Picker, so there is continuity.
flingBehavior	logic describing fling behavior.
userScrollEnabled	Determines whether the picker should be scrollable or not. When userScrollEnabled = true, picker is scrollable. This is different from `readOnly` as it changes the scrolling behaviour.
option	A block which describes the content. Inside this block you can reference `PickerScope.selectedOption` and other properties in `PickerScope`. When read-only mode is in use on a screen, it is recommended that this content is given `Alignment.Center` in order to align with the centrally selected Picker value.

Android

@Composable
public fun Picker(
    state: PickerState,
    contentDescription: String?,
    modifier: Modifier = Modifier,
    readOnly: Boolean = false,
    readOnlyLabel: @Composable (BoxScope.() -> Unit)? = null,
    onSelected: () -> Unit = {},
    scalingParams: ScalingParams = PickerDefaults.defaultScalingParams(),
    separation: Dp = 0.dp,
    @FloatRange(from = 0.0, to = 0.5) gradientRatio: Float = PickerDefaults.DefaultGradientRatio,
    gradientColor: Color = MaterialTheme.colors.background,
    flingBehavior: FlingBehavior = PickerDefaults.flingBehavior(state),
    userScrollEnabled: Boolean = true,
    rotaryScrollableBehavior: RotaryScrollableBehavior? =
        RotaryScrollableDefaults.snapBehavior(state, state.toRotarySnapLayoutInfoProvider()),
    option: @Composable PickerScope.(optionIndex: Int) -> Unit,
)

Parameters


state	The state of the component
contentDescription	Text used by accessibility services to describe what the selected option represents. This text should be localized, such as by using `androidx.compose.ui.res.stringResource` or similar. Typically, the content description is inferred via derivedStateOf to avoid unnecessary recompositions, like this: val description by remember { derivedStateOf { /* expression using state.selectedOption */ } }
modifier	Modifier to be applied to the Picker
readOnly	Determines whether the Picker 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	A slot for providing a label, displayed above the selected option when the `Picker` is read-only. The label is overlaid with the currently selected option within a Box, so it is recommended that the label is given `Alignment.TopCenter`.
onSelected	Action triggered when the Picker is selected by clicking. Used by accessibility semantics, which facilitates implementation of multi-picker screens.
scalingParams	The parameters to configure the scaling and transparency effects for the component. See `ScalingParams`
separation	The amount of separation in `Dp` between items. Can be negative, which can be useful for Text if it has plenty of whitespace.
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	Should be the color outside of the Picker, so there is continuity.
flingBehavior	logic describing fling behavior. Note that when configuring fling or snap behavior, this flingBehavior parameter and the `rotaryScrollableBehavior` parameter that controls rotary scroll are expected to be consistent.
userScrollEnabled	Determines whether the picker should be scrollable or not. When userScrollEnabled = true, picker is scrollable. This is different from `readOnly` as it changes the scrolling behaviour.
rotaryScrollableBehavior	Parameter for changing rotary behavior. Supports scroll `RotaryScrollableDefaults.behavior` and snap `RotaryScrollableDefaults.snapBehavior`. We do recommend to use `RotaryScrollableDefaults.snapBehavior` as this is a recommended behavior for Pickers. Note that when configuring fling or snap behavior, this rotaryBehavior parameter and the `flingBehavior` parameter that controls touch scroll are expected to be consistent. Can be null if rotary support is not required.
option	A block which describes the content. Inside this block you can reference `PickerScope.selectedOption` and other properties in `PickerScope`. When read-only mode is in use on a screen, it is recommended that this content is given `Alignment.Center` in order to align with the centrally selected Picker value.

Android

Deprecated This overload is provided for backwards compatibility with Compose for Wear OS 1.1.A newer overload is available which uses ScalingParams from androidx.wear.compose.foundation.lazy package

@Composable
public fun Picker(
    state: PickerState,
    contentDescription: String?,
    modifier: Modifier = Modifier,
    readOnly: Boolean = false,
    readOnlyLabel: @Composable (BoxScope.() -> Unit)? = null,
    onSelected: () -> Unit = {},
    scalingParams: androidx.wear.compose.material.ScalingParams = PickerDefaults.scalingParams(),
    separation: Dp = 0.dp,
    @FloatRange(from = 0.0, to = 0.5) gradientRatio: Float = PickerDefaults.DefaultGradientRatio,
    gradientColor: Color = MaterialTheme.colors.background,
    flingBehavior: FlingBehavior = PickerDefaults.flingBehavior(state),
    userScrollEnabled: Boolean = true,
    option: @Composable PickerScope.(optionIndex: Int) -> Unit,
): Unit

Android

Deprecated This overload is provided for backwards compatibility with Compose for Wear OS 1.1.A newer overload is available with additional userScrollEnabled parameter which improves accessibility of [Picker].

@Composable
public fun Picker(
    state: PickerState,
    contentDescription: String?,
    modifier: Modifier = Modifier,
    readOnly: Boolean = false,
    readOnlyLabel: @Composable (BoxScope.() -> Unit)? = null,
    onSelected: () -> Unit = {},
    scalingParams: androidx.wear.compose.material.ScalingParams = PickerDefaults.scalingParams(),
    separation: Dp = 0.dp,
    @FloatRange(from = 0.0, to = 0.5) gradientRatio: Float = PickerDefaults.DefaultGradientRatio,
    gradientColor: Color = MaterialTheme.colors.background,
    flingBehavior: FlingBehavior = PickerDefaults.flingBehavior(state),
    option: @Composable PickerScope.(optionIndex: Int) -> Unit,
): Unit

Parameters


state	The state of the component
contentDescription	Text used by accessibility services to describe what the selected option represents. This text should be localized, such as by using `androidx.compose.ui.res.stringResource` or similar. Typically, the content description is inferred via derivedStateOf to avoid unnecessary recompositions, like this: val description by remember { derivedStateOf { /* expression using state.selectedOption */ } }
modifier	Modifier to be applied to the Picker
readOnly	Determines whether the Picker 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	A slot for providing a label, displayed above the selected option when the `Picker` is read-only. The label is overlaid with the currently selected option within a Box, so it is recommended that the label is given `Alignment.TopCenter`.
onSelected	Action triggered when the Picker is selected by clicking. Used by accessibility semantics, which facilitates implementation of multi-picker screens.
scalingParams	The parameters to configure the scaling and transparency effects for the component. See `ScalingParams`
separation	The amount of separation in `Dp` between items. Can be negative, which can be useful for Text if it has plenty of whitespace.
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	Should be the color outside of the Picker, so there is continuity.
flingBehavior	logic describing fling behavior.
option	A block which describes the content. Inside this block you can reference `PickerScope.selectedOption` and other properties in `PickerScope`. When read-only mode is in use on a screen, it is recommended that this content is given `Alignment.Center` in order to align with the centrally selected Picker value.

Android

Deprecated This overload is provided for backwards compatibility with Compose for Wear OS 1.0.A newer overload is available with additional contentDescription, onSelected and userScrollEnabled parameters, which improves accessibility of [Picker].

@Composable
public fun Picker(
    state: PickerState,
    modifier: Modifier = Modifier,
    readOnly: Boolean = false,
    readOnlyLabel: @Composable (BoxScope.() -> Unit)? = null,
    scalingParams: androidx.wear.compose.material.ScalingParams = PickerDefaults.scalingParams(),
    separation: Dp = 0.dp,
    @FloatRange(from = 0.0, to = 0.5) gradientRatio: Float = PickerDefaults.DefaultGradientRatio,
    gradientColor: Color = MaterialTheme.colors.background,
    flingBehavior: FlingBehavior = PickerDefaults.flingBehavior(state),
    option: @Composable PickerScope.(optionIndex: Int) -> Unit,
): Unit

Parameters


state	The state of the component
modifier	Modifier to be applied to the Picker
readOnly	Determines whether the Picker 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	A slot for providing a label, displayed above the selected option when the `Picker` is read-only. The label is overlaid with the currently selected option within a Box, so it is recommended that the label is given `Alignment.TopCenter`.
scalingParams	The parameters to configure the scaling and transparency effects for the component. See `ScalingParams`
separation	The amount of separation in `Dp` between items. Can be negative, which can be useful for Text if it has plenty of whitespace.
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	Should be the color outside of the Picker, so there is continuity.
flingBehavior	logic describing fling behavior.
option	A block which describes the content. Inside this block you can reference `PickerScope.selectedOption` and other properties in `PickerScope`. When read-only mode is in use on a screen, it is recommended that this content is given `Alignment.Center` in order to align with the centrally selected Picker value.