Picker

TxPicker renders one or more scrollable option columns. It can be used inline or as a bottom popup, normalizes missing values to the first enabled option in each column, and emits both live changes and toolbar confirm/cancel actions.

Basic Usage

Picker

Demo will load when visible.

<script setup lang="ts">
import { ref } from 'vue'

const visible = ref(false)
const value = ref<(string | number)[]>(['b', 2])

const columns = [
  {
    key: 'letter',
    options: [
      { value: 'a', label: 'A' },
      { value: 'b', label: 'B' },
      { value: 'c', label: 'C' },
    ],
  },
  {
    key: 'number',
    options: [
      { value: 1, label: '1' },
      { value: 2, label: '2' },
      { value: 3, label: '3' },
      { value: 4, label: '4', disabled: true },
    ],
  },
]
</script>

<template>
  <div style="width: 360px; padding: 16px; border: 1px solid var(--tx-border-color); border-radius: 12px;">
    <div style="display: flex; gap: 8px; align-items: center;">
      <TxButton variant="primary" @click="visible = true">
        Open picker
      </TxButton>
      <div style="color: var(--tx-text-color-secondary);">
        Value: {{ value }}
      </div>
    </div>

    <TxPicker v-model="value" v-model:visible="visible" title="Picker" :columns="columns" />
  </div>
</template>

API

Props

Prop	Type	Default	Description
`modelValue`	`(string \| number)[]`	`[]`	Selected value per column. Missing or invalid entries normalize to the first enabled option.
`columns`	`PickerColumn[]`	`[]`	Column definitions rendered from left to right.
`visible`	`boolean`	`false`	Popup open state controlled by `v-model:visible`.
`popup`	`boolean`	`true`	Renders as a Teleport bottom popup when true; renders inline when false.
`title`	`string`	`''`	Center title shown in the toolbar.
`showToolbar`	`boolean`	`true`	Shows cancel/title/confirm toolbar actions.
`confirmText`	`string`	`'Confirm'`	Text for the confirm button.
`cancelText`	`string`	`'Cancel'`	Text for the cancel button.
`disabled`	`boolean`	`false`	Disables toolbar buttons, option buttons, and drag state updates.
`itemHeight`	`number`	`36`	Option row height in pixels; values below 24 are clamped to 24.
`visibleItemCount`	`number`	`5`	Number of visible rows. Even values are rounded up to the next odd count.
`closeOnClickMask`	`boolean`	`true`	Closes the popup when the mask is clicked.
`lazyMount`	`boolean`	`true`	Delays popup body rendering until the picker has opened once.

PickerColumn

Field	Type	Description
`key`	`string`	Optional stable key for the column.
`options`	`PickerOption[]`	Options available in this column.

PickerOption

Field	Type	Description
`value`	`string \| number`	Primitive value emitted for the column.
`label`	`string`	Visible option label.
`disabled`	`boolean`	Prevents selecting this option and skips it during normalization fallback.

Events

Event	Params	Description
`update:modelValue`	`(value: PickerValue)`	Emitted when scrolling changes a column value.
`change`	`(value: PickerValue)`	Emitted with the same normalized value after a live column change.
`update:visible`	`(visible: boolean)`	Popup visibility update emitted by open/close actions.
`confirm`	`(value: PickerValue)`	Emitted with the current local value when confirm is clicked, then closes.
`cancel`	-	Emitted when cancel is clicked, then closes.
`open`	-	Emitted when the picker opens.
`close`	-	Emitted when the picker closes.