Picker

Displays a scrollable list of one or more option sets.

Install

npm install antd-mobile@5.43.0

antd-mobile is for mobile web, not React Native or Mini Programs. React 19 projects must register createRoot with unstableSetRender at the entry, or imperative APIs such as Toast and Dialog cannot render. Switch dark mode with <html data-prefers-color-scheme="dark">.

Examples come from the official Ant Design Mobile repository (MIT) at the commit published as npm 5.43.0. Presentation helpers such as DemoBlock are JGuang rewrites, not antd-mobile APIs.

Displays a scrollable list of one or more option sets.

When to Use

• Provides one or more sets of association options for the user to choose from.
• When there are less than 5 options, it is recommended to tile the options directly, using Radio is a better choice.

The Picker series includes three components: Picker, CascadePicker and DatePicker.

Picker

Demos

Props

type PickerColumnItem = {
  label: ReactNode
  value: string
  key?: string | number
}

type PickerColumn = (string | PickerColumnItem)[]

type PickerValue = string | null

type PickerValueExtend = {
  items: (PickerColumnItem | null)[]
}

In addition, the following attributes of Popup are supported: getContainer afterShow afterClose onClick stopPropagation.

Please note that the type of the columns property is a two-level array, the first level corresponds to each column, and the second level corresponds to each option in a column. Therefore, the following writing is wrong:

<Picker
   columns={[
     { label: 'Foo', value: 'foo' },
     { label: 'Bar', value: 'bar' },
   ]}
/>

need to be written as:

<Picker
   columns={[
     [
       { label: 'Foo', value: 'foo' },
       { label: 'Bar', value: 'bar' },
     ]
   ]}
/>

PickerActions

Ref

Same as PickerActions.

CSS Variables

CascadePicker

Demos

Props

type CascadePickerOption = {
  label: string
  value: string
  children?: CascadePickerOption[]
}

Other props are the same as Picker, but columns are not supported.

Ref

Same as Picker.

CSS Variables

Same as Picker.

DatePicker

Demos

Props

type PickerDate = Date & {
  tillNow?: boolean
}

type DatePickerFilter = Partial<
  Record<
    Precision,
    (
      val: number,
      extend: {
        date: Date
      }
    ) => boolean
  >
>

In addition, the following attributes of Picker are supported: onCancel onClose closeOnMaskClick visible confirmText cancelText getContainer afterShow afterClose onClick title stopPropagation loading loadingContent

Ref

Same as Picker.

CSS Variables

Same as Picker.

Imperative Call

Picker supports Imperative Call and provides the prompt method:

prompt: (props: Omit<PickerProps, 'value' | 'visible' | 'children'>) => Promise<PickerValue[] | null>

The return value of the prompt method is a Promise. If the user clicks OK, the Promise can be resolved to PickerValue[], and if the user triggers the cancellation operation, the value in the Promise is null. You can get the value through await or .then():

const value = await Picker.prompt({
  columns: yourColumnsConfig,
})

Picker.prompt({
  columns: yourColumnsConfig,
}).then((value) => {
  // ...
})

Similarly, CascadePicker and DatePicker also support the prompt method, the specific usage will not be repeated here.

FAQ

How to highlight the selected items?

The DOM element of selected items has a data-selected="true" attribute. You can use this mark to add custom CSS styles to selected items.

Why is the name of the component called "DatePicker" instead of "DatetimePicker"?

Because the type of value is Date.

Why is there no "hour-minute" or "month-day" option?

Different from the Picker component, the value type of the DatePicker is a Date object, so it needs to be selected from the beginning of the year. Only the parameters of hour and minutes cannot construct a Date object.

If you need to use DatePicker like that, you can implement it yourself through the Picker component.