NumberPicker

NumberPicker is a basic interactive component in COUI used for selecting a value from a range of numbers by vertical scrolling. The selected item is centered, enlarged and highlighted, while surrounding items scale down and transition to the unselected color within half an item of the center. Supports infinite scrolling with the wrapAround parameter.

Import

import io.github.suqi8.coui.kmp.basic.NumberPicker

Basic Usage

var value by remember { mutableIntStateOf(5) }

NumberPicker(
    value = value,
    onValueChange = { value = it },
    range = 0..10
)

Component States

Disabled State

var value by remember { mutableIntStateOf(5) }

NumberPicker(
    value = value,
    onValueChange = { value = it },
    range = 0..10,
    enabled = false
)

Infinite Scrolling

When wrapAround is enabled, the picker wraps from the last item back to the first, allowing continuous scrolling.

var value by remember { mutableIntStateOf(0) }

NumberPicker(
    value = value,
    onValueChange = { value = it },
    range = 0..23,
    wrapAround = true
)

Properties

NumberPicker Properties

Property Name	Type	Description	Default Value	Required
value	Int	Current selected value. If outside range, it will be coerced	-	Yes
onValueChange	(Int) -> Unit	Callback invoked when the selected value changes	-	Yes
modifier	Modifier	Modifier applied to the picker	Modifier	No
enabled	Boolean	Whether the picker is enabled for user interaction	true	No
range	IntRange	The range of selectable values	0..10	No
label	(Int) -> String	Converts a value to its display string		No
visibleItemCount	Int	Number of visible items. Must be odd and at least 3	3	No
wrapAround	Boolean	Whether the picker wraps around (infinite scrolling)	false	No
colors	NumberPickerColors	Color configuration of the picker	NumberPickerDefaults.colors()	No
textStyle	TextStyle	Text style for picker items	COUITheme.textStyles.title3	No
itemHeight	Dp	The height of each item in the picker	NumberPickerDefaults.ItemHeight	No

NumberPickerDefaults Object

The NumberPickerDefaults object provides default configurations for the NumberPicker component.

Properties

Property Name	Type	Description	Default Value
ItemHeight	Dp	Default height of each item	45.dp

Methods

Method Name	Return Type	Description
colors()	NumberPickerColors	Creates default color configuration

The colors() factory accepts the following parameters:

Parameter Name	Type	Default Value
selectedTextColor	Color	COUITheme.colorScheme.onSurface
unselectedTextColor	Color	COUITheme.colorScheme.onSurfaceVariantActions
disabledSelectedTextColor	Color	COUITheme.colorScheme.disabledOnSecondary
disabledUnselectedTextColor	Color	COUITheme.colorScheme.disabledOnSecondary

NumberPickerColors Class

Property Name	Type	Description
selectedTextColor	Color	Text color for the selected (center) item
unselectedTextColor	Color	Text color for unselected items
disabledSelectedTextColor	Color	Selected text color when disabled
disabledUnselectedTextColor	Color	Unselected text color when disabled

Advanced Usage

Custom Label Format

var hour by remember { mutableIntStateOf(9) }

NumberPicker(
    value = hour,
    onValueChange = { hour = it },
    range = 0..23,
    label = { it.toString().padStart(2, '0') }  // "00", "01", ... "23"
)

Time Picker

Combine two NumberPickers to create a time picker.

var hour by remember { mutableIntStateOf(16) }
var minute by remember { mutableIntStateOf(30) }

Row(
    horizontalArrangement = Arrangement.Center,
    verticalAlignment = Alignment.CenterVertically,
) {
    NumberPicker(
        value = hour,
        onValueChange = { hour = it },
        range = 0..23,
        label = { it.toString().padStart(2, '0') },
        wrapAround = true,
        modifier = Modifier.weight(1f),
    )
    Text(
        text = ":",
        fontWeight = FontWeight.Bold,
    )
    NumberPicker(
        value = minute,
        onValueChange = { minute = it },
        range = 0..59,
        label = { it.toString().padStart(2, '0') },
        wrapAround = true,
        modifier = Modifier.weight(1f),
    )
}

Custom Visible Item Count

var value by remember { mutableIntStateOf(5) }

NumberPicker(
    value = value,
    onValueChange = { value = it },
    range = 1..100,
    visibleItemCount = 5 // Must be odd and at least 3
)

Custom Colors

var value by remember { mutableIntStateOf(5) }

NumberPicker(
    value = value,
    onValueChange = { value = it },
    range = 0..10,
    colors = NumberPickerDefaults.colors(
        selectedTextColor = Color.Red,
        unselectedTextColor = Color.Gray
    )
)

Changelog

Last edited 9 days ago

View full history

429b622-docs: rebrand site to COUI and audit all component pages

9aba0de-chore: rename package from com.suqi8 to io.github.suqi8

7acb5ab-library: retheme to COUI 16 and rename Miuix to COUI

a6234e9-library: refactor: unify dropdown and spinner components (#315)

bbcc0bb-library: add NumberPicker component (#249)