CalendarPicker

The CalendarPicker component provides a drop-down calendar for users to select a date.

NOTE

This component is supported since API version 10. Updates will be marked with a superscript to indicate their earliest API version.

Child Components

Not supported

APIs

CalendarPicker(options?: CalendarOptions)

Creates a calendar picker.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Device behavior differences: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly.

Parameters

Name	Type	Mandatory	Description
options	CalendarOptions	No	Parameters of the calendar picker.

Attributes

In addition to the universal attributes, the following attributes are supported.

edgeAlign

edgeAlign(alignType: CalendarAlign, offset?: Offset)

Sets how the picker is aligned with the entry component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Device behavior differences: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly.

Parameters

Name	Type	Mandatory	Description
alignType	CalendarAlign	Yes	Alignment type. Default value: CalendarAlign.END.
offset	Offset	No	Offset of the picker relative to the entry component after alignment based on the specified alignment type. Default value: {dx: 0, dy: 0}

edgeAlign¹⁸⁺

edgeAlign(alignType: Optional<CalendarAlign>, offset?: Offset)

Sets how the picker is aligned with the entry component. Compared with edgeAlign, this API supports the undefined type for the alignType parameter.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Full

Device behavior differences: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly.

Parameters

Name	Type	Mandatory	Description
alignType	Optional<CalendarAlign>	Yes	Alignment type. Default value: CalendarAlign.END. If the value of alignType is undefined, the default value is used.
offset	Offset	No	Offset of the picker relative to the entry component after alignment based on the specified alignment type. Default value: {dx: 0, dy: 0}

textStyle

textStyle(value: PickerTextStyle)

Sets the font color, font size, and font weight in the entry area.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Device behavior differences: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly.

Parameters

Name	Type	Mandatory	Description
value	PickerTextStyle	Yes	Font color, font size, and font weight in the entry area. Default value: { color: '#ff182431', font: { size: '16fp', weight: FontWeight.Regular } }

textStyle¹⁸⁺

textStyle(style: Optional<PickerTextStyle>)

Sets the font color, font size, and font weight in the entry area. Compared with textStyle, this API supports the undefined type for the style parameter.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Full

Device behavior differences: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly.

Parameters

Name	Type	Mandatory	Description
style	Optional<PickerTextStyle>	Yes	Font color, font size, and font weight in the entry area. Default value: { color: '#ff182431', font: { size: '16fp', weight: FontWeight.Regular } } If the value of style is undefined, the default value is used.

markToday¹⁹⁺

markToday(enabled: boolean)

Whether to highlight the current system date.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.ArkUI.ArkUI.Full

Device behavior differences: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly.

Parameters

Name	Type	Mandatory	Description
enabled	boolean	Yes	Whether to highlight the current system date. - true: Highlight the current system date. - false: Do not highlight the current system date. Default value: false.

Events

In addition to the universal events, the following events are supported.

onChange

onChange(callback: Callback<Date>)

Triggered when a date is selected. This event cannot be triggered by two-way bound state variables.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Device behavior differences: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly.

Parameters

Name	Type	Mandatory	Description
callback	Callback<Date>	Yes	Selected date value.

onChange¹⁸⁺

onChange(callback: Optional<Callback<Date>>)

Triggered when a date is selected. This event cannot be triggered by two-way bound state variables. Compared with onChange, this API supports the undefined type for the callback parameter.

NOTE

This API can be called within attributeModifier since API version 20.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Full

Device behavior differences: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly.

Parameters

Name	Type	Mandatory	Description
callback	Optional<Callback<Date>>	Yes	Selected date value. If callback is set to undefined, the callback function is not used.

CalendarOptions

Describes the parameters of the calendar picker.

System capability: SystemCapability.ArkUI.ArkUI.Full

Device behavior differences: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly.

Name	Type	Read-Only	Optional	Description
hintRadius	number \| Resource	No	Yes	Style of the background of the selected state. Value range: [0.0, 16.0] Unit: vp. Default value: 16.0 (the background is a circle). NOTE If the value is 0.0, the background is a right-angled rectangle. If the value is in the (0.0, 16.0) range, the background is a rounded rectangle. If the value is a negative number or greater than 16.0, the default value 16.0 is used, which means the background is a circle. Atomic service API: This API can be used in atomic services since API version 11.
selected	Date	No	Yes	Date of the selected item. If the value is not set or does not comply with the date format specifications, the default value will be used. Default value: current system date Value range: [Date('0001-01-01'), Date('5000-12-31')]. Atomic service API: This API can be used in atomic services since API version 11.
start¹⁸⁺	Date	No	Yes	Start date. Default value: Date('0001-01-01') Value range: [Date('0001-01-01'), Date('5000-12-31')]. Atomic service API: This API can be used in atomic services since API version 18.
end¹⁸⁺	Date	No	Yes	End date. Default value: Date('5000-12-31'). Value range: [Date('0001-01-01'), Date('5000-12-31')]. Atomic service API: This API can be used in atomic services since API version 18.
disabledDateRange¹⁹⁺	DateRange[]	No	Yes	Disabled date range. NOTE 1. If the start date or end date within a date range is invalid or is not set, the entire date range does not take effect. 2. If the end date is earlier than the start date within a date range, the entire date range does not take effect. 3. When users select a date and adjust it with the up or down arrow keys, the system skips over all dates in the disabled date range. Atomic service API: This API can be used in atomic services since API version 19.

Rules for setting start and end

Scenario	Description
The start date is later than the end date.	Both start and end dates are invalid, and the selected date is the default value.
The selected date is earlier than the start date.	The selected date is set as the start date.
The selected date is later than the end date.	The selected date is set as the end date.
The start date is later than the current system date, and the selected date is not set.	The selected date is set as the start date.
The end date is earlier than the current system date, and the selected date is not set.	The selected date is set as the end date.
The set date is in invalid format, for example, '1999-13-32'.	The start or end date setting is invalid, and the selected date is the default value.

CalendarAlign

Enumerates alignment types.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Device behavior differences: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly.

Name	Value	Description
START	0	Left-aligned with the entry component.
CENTER	1	Center-aligned with the entry component.
END	2	Right-aligned with the entry component.

Example

Example 1: Implementing a Calendar Picker

This example uses calendarPicker to implement the CalendarPicker component and provides a drop-down calendar.

// xxx.ets
@Entry
@Component
struct CalendarPickerExample {
  private selectedDate: Date = new Date('2024-03-05');

  build() {
    Column() {
      Column() {
        CalendarPicker({ hintRadius: 10, selected: this.selectedDate })
          .edgeAlign(CalendarAlign.END)
          .textStyle({ color: "#ff182431", font: { size: 20, weight: FontWeight.Normal } })
          .margin(10)
          .onChange((value) => {
            console.info(`CalendarPicker onChange: ${value.toString()}`);
          })
      }.alignItems(HorizontalAlign.End).width("100%")

      Text('Calendar picker').fontSize(30)
    }.width('100%').margin({ top: 350 })
  }
}

CalendarPicker

Example 2: Setting Start and End Dates

This example demonstrates how to set the start and end dates for the calendar picker using start and end.

Since API version 18., the start and end attributes are added to CalendarOptions.

// xxx.ets
@Entry
@Component
struct CalendarPickerExample {
  private selectedDate: Date = new Date('2025-01-15');
  private startDate: Date = new Date('2025-01-05');
  private endDate: Date = new Date('2025-01-25');

  build() {
    Column() {
      Column() {
        CalendarPicker({ hintRadius: 10, selected: this.selectedDate, start: this.startDate, end: this.endDate })
          .edgeAlign(CalendarAlign.END)
          .textStyle({ color: "#ff182431", font: { size: 20, weight: FontWeight.Normal } })
          .margin(10)
          .onChange((value) => {
            console.info(`CalendarPicker onChange: ${value.toString()}`);
          })
      }.alignItems(HorizontalAlign.End).width("100%")
    }.width('100%').margin({ top: 350 })
  }
}

CalendarPicker

Example 3: Highlighting the Current System Date and Disabling a Specific Date Range

This example shows how to highlight the current system date using markToday and disable a specific date range using disabledDateRange.

Since API version 19, the markToday API is added, and the disabledDateRange attribute is added to CalendarOptions.

// xxx.ets
@Entry
@Component
struct CalendarPickerExample {
  private disabledDateRange: DateRange[] = [
    { start: new Date('2025-01-01'), end: new Date('2025-01-02') },
    { start: new Date('2025-01-09'), end: new Date('2025-01-10') },
    { start: new Date('2025-01-15'), end: new Date('2025-01-16') },
    { start: new Date('2025-01-19'), end: new Date('2025-01-19') },
    { start: new Date('2025-01-22'), end: new Date('2025-01-25') }
  ];

  build() {
    Column() {
      CalendarPicker({ disabledDateRange: this.disabledDateRange })
        .margin(10)
        .markToday(true)
        .onChange((value) => {
          console.info(`CalendarPicker onChange: ${value.toString()}`);
        })
    }.alignItems(HorizontalAlign.End).width('100%')
  }
}

CalendarPicker

CalendarPicker

Child Components

APIs

Attributes

edgeAlign

edgeAlign18+

textStyle

textStyle18+

markToday19+

Events

onChange

onChange18+

CalendarOptions

CalendarAlign

Example

Example 1: Implementing a Calendar Picker

Example 2: Setting Start and End Dates

Example 3: Highlighting the Current System Date and Disabling a Specific Date Range

edgeAlign¹⁸⁺

textStyle¹⁸⁺

markToday¹⁹⁺

onChange¹⁸⁺