Capacitor Datetime Picker Plugin

Capacitor plugin for seamless date and time selection with advanced features like localization, theming, and more. Available for Android and iOS.

Features

The Capacitor Datetime Picker plugin is one of the most feature-rich date and time selection solutions for Capacitor apps. Here are some of the key features:

• 🖥️ Cross-platform: Supports Android and iOS.
• 📅 Multiple modes: Date, time, datetime, and month picker modes.
• 🌍 Localization: Support for BCP 47 language tags.
• 🎨 Theming: Auto, light, and dark theme support.
• ⚡ Custom formats: Define your own date/time format strings.
• 🔒 Min/Max constraints: Set minimum and maximum selectable dates/times.
• 📱 Native UI: Uses platform-specific picker components.
• ⚙️ Flexible configuration: Customizable button texts and picker modes.
• 🤝 Compatibility: Works alongside the Action Sheet, Dialog and Localization plugins.
• 🔁 Up-to-date: Always supports the latest Capacitor version.

Missing a feature? Just open an issue and we'll take a look!

Use Cases

The Datetime Picker plugin is typically used whenever an app needs the user to enter a date or time, for example:

• Appointment booking: Let users pick a date and time for a reservation and restrict the selection with minimum and maximum constraints.
• Profile forms: Ask for a date of birth with a native, localized date picker.
• Reminders and alarms: Let users choose a time of day using the native time picker, optionally with a custom minute interval on iOS.
• Reports and statements: Let users select a month and year only, for example to filter a monthly report, using the month mode.

Compatibility

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

npx skills add capawesome-team/skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-datetime-picker` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands:

npm install @capawesome-team/capacitor-datetime-picker
npx cap sync

Configuration

No configuration required for this plugin.

Demo

A working example can be found here: robingenz/capacitor-plugin-demo

Android	iOS

Usage

The following examples show how to present a date, time, or datetime picker, and how to let the user pick a month and year only.

Present a date, time, or datetime picker

Open the native picker with the present(...) method. Use the mode option to choose between a date, time, or datetime picker, and customize the theme, locale, and button texts as needed. Only available on Android and iOS:

import { DatetimePicker } from '@capawesome-team/capacitor-datetime-picker';

const present = async () => {
  const date = new Date('1995-12-24T02:23:00');

  const { value } = await DatetimePicker.present({
    cancelButtonText: 'Cancel',
    doneButtonText: 'Ok',
    mode: 'time',
    value: date.toISOString(),
    theme: 'dark',
    locale: 'en-US',
  });

  return value;
};

Let the user pick a month and year only

Use the month mode to let the user pick a month and year without a day or time, for example to filter a monthly report. The returned value is the first day of the selected month:

import { DatetimePicker } from '@capawesome-team/capacitor-datetime-picker';

const presentMonth = async () => {
  const { value } = await DatetimePicker.present({
    cancelButtonText: 'Cancel',
    doneButtonText: 'Ok',
    mode: 'month',
    value: '2026-05',
    format: 'yyyy-MM',
    locale: 'en-US',
  });

  return value;
};

API

• present(...)
• cancel()
• Interfaces

present(...)

present(options?: PresentOptions | undefined) => Promise<PresentResult>

Open the datetime picker.

An error is thrown if the input is canceled or dismissed by the user.

On Android, the picker is dismissed (the promise rejects with the dismissed error code) if the system language, font size or layout direction changes while it is open.

Only available on Android and iOS.

Returns: Promise<PresentResult>

Since: 0.0.1

cancel()

cancel() => Promise<void>

Cancel the currently active datetime picker.

If there is no active picker, this method does nothing.

Only available on Android and iOS.

Since: 7.2.0

Interfaces

PresentResult

PresentOptions

FAQ

What happens when the user cancels the picker?

The present(...) method throws an error if the input is canceled or dismissed by the user. Make sure to catch this error in your code, for example to keep the previous value.

How can I close the picker programmatically?

Use the cancel() method to cancel the currently active datetime picker, for example when your app is sent to the background. If there is no active picker, this method does nothing.

How do I restrict which dates the user can select?

Use the min and max options of the present(...) method to define the earliest and latest date and time to accept. The format of both values must match the value of the format parameter.

How do I let the user pick only a month and year?

Set the mode option to month. Unlike the other modes, the month picker uses a custom (non-native) UI on both platforms, because neither Android nor iOS provide a native month-only picker. The returned value is the first day of the selected month at 00:00:00 local time. See the usage example above.

Can I change the language and theme of the picker?

Yes, use the locale option with a BCP 47 language tag to define the language of the UI, and the theme option to choose between auto, light, and dark. With auto, the system theme is used.

Does this plugin work on the Web?

No, this plugin is only available on Android and iOS, where it uses platform-specific picker components. The present(...) and cancel() methods are not available on the Web.

Related Plugins

• Action Sheet: Show native action sheets.
• Dialog: Display native alert, confirm, and prompt dialogs.
• Localization: Read the user's preferred locales to localize the picker.
• Option Picker: Let the user pick an option from a list with a native picker.

Credits

The iOS implementation of this plugin is based on RPicker which is licensed under MIT.

Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Changelog

See CHANGELOG.md.

License

See LICENSE.