---
name: "picker"
mode: "component"
versionRequirements:
  - { name: "Base Library", version: "2.10.0" }
title: "picker - Scroll picker that pops up from the bottom"
---

## picker

> [VERSION] Base Library >= 2.10.0

### Description

Scroll picker that pops up from the bottom

### Props

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `checked` | `boolean` | No | `false` | Whether selected |
| `color` | `string` | No | `""` | Color when selected, same as CSS color |
| `range` | `any[]` | No | `[]` | Data source of the picker; valid when mode is selector or multiSelector |
| `value` | `any[] \| string` | No | `""` | mode = selector: index of the selected item in range (0-based). mode = multiSelector: indexes of the selected items in range (0-based). mode = time: selected time in the "hh:mm" format. mode = date: selected date in the "YYYY-MM-DD" format |
| `mode` | `string` | No | `"selector"` | Picker mode. Options: selector (single-column), multiSelector (multi-column), time (time), date (date) |
| `fields` | `string` | No | `"day"` | Valid only in date mode. Options: year (precision to year), month (precision to month), day (precision to day) |
| `start` | `string` | No | `""` | Valid only in time/date mode; start of the valid time/date range |
| `end` | `string` | No | `""` | Valid only in time/date mode; end of the valid time/date range |
| `disabled` | `boolean` | No | `false` | Whether disabled |
| `range-key` | `string` | No | `""` | When range is an array of objects, use rangeKey to specify which key’s value in the Object is displayed by the picker |
| `confirm-text` | `string` | No | `"确定"` | Confirm button text |
| `cancel-text` | `string` | No | `"取消"` | Cancel button text |

#### Events

| Event | Type | Description |
| --- | --- | --- |
| `change` | `(event: PickerChangeEvent) => void` | Fires when the selection is confirmed |
| `cancel` | `(event: Object) => void` | Triggered when selection is canceled |
| `columnchange` | `(event: PickerColumnChangeEvent) => void` | Fires when an option changes in any column of a multi-column picker |

**PickerChangeEvent**

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"change"` | Event type |
| `detail` | `PickerChangeDetail` | Event data |

**cancel callback object**

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"cancel"` |  |

**PickerColumnChangeEvent**

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"columnchange"` | Event type |
| `detail` | `PickerColumnChangeDetail` | Event data |

### Examples

#### Basic usage

*index.tyml*

```xml
// index.tyml
<picker mode=\"selector\" range=\"{{array}}\" bind:change=\"onChange\">
  <view class=\"picker\">Current selection: {{array[index]}}</view>
</picker>
```

*index.tyss*

```css
.picker { padding: 20rpx; background-color: #f5f5f5; }
```

*index.js*

```javascript
Page({
  data: { array: ['United States', 'China', 'Brazil'], index: 0 },
  onChange(e) { this.setData({ index: e.detail.value }); },
});
```

#### Time picker

*index.tyml*

```xml
// index.tyml
<picker mode=\"time\" value=\"{{time}}\" start=\"09:00\" end=\"18:00\" bind:change=\"onTimeChange\">
  <view class=\"picker\">Current selection: {{time}}</view>
</picker>
```

*index.tyss*

```css
.picker { padding: 20rpx; background-color: #f5f5f5; }
```

*index.js*

```javascript
Page({
  data: { time: '12:00' },
  onTimeChange(e) {
    this.setData({ time: e.detail.value });
  },
});
```

#### Date picker

*index.tyml*

```xml
// index.tyml
<picker mode=\"date\" value=\"{{date}}\" start=\"2020-01-01\" end=\"2030-12-31\" fields=\"day\" bind:change=\"onDateChange\" bind:cancel=\"onCancel\">
  <view class=\"picker\">Current date: {{date}}</view>
</picker>
```

*index.tyss*

```css
.picker { padding: 20rpx; background-color: #f5f5f5; }
```

*index.js*

```javascript
Page({
  data: { date: '2026-01-01' },
  onDateChange(e) { this.setData({ date: e.detail.value }); },
  onCancel() { console.log('Selection canceled'); },
});
```

#### Multi-column picker

*index.tyml*

```xml
<picker mode="multiSelector" range="{{range}}" value="{{value}}" bind:change="onChange" bind:columnchange="onColumnChange">
  <view class="picker">{{range[0][value[0]]}} - {{range[1][value[1]]}}</view>
</picker>
```

*index.tyss*

```css
.picker { padding: 20rpx; background-color: #f5f5f5; }
```

*index.js*

```javascript
Page({
  data: {
    range: [['Guangdong', 'Zhejiang', 'Jiangsu'], ['Guangzhou', 'Hangzhou', 'Nanjing']],
    value: [0, 0],
  },
  onChange(e) { this.setData({ value: e.detail.value }); },
  onColumnChange(e) { console.log('Column changed:', e.detail.column, e.detail.value); },
});
```