> For the complete documentation index, see [llms.txt](https://docs.buildnatively.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buildnatively.com/guides/integration/date-picker.md).
# Date Picker
## What is Date Picker?
The Date Picker feature lets you show a native date and time selection UI - the same picker the user sees in other apps on their device. It supports three modes: date only, time only, or date and time combined. The result is returned as a timestamp in milliseconds, which you can convert to any date format your app needs.
## Prerequisites
{% hint style="success" %}
This feature is available in all plans. [See all plans](/getting-started/subscription-plans.md)
{% endhint %}
## Implementation
Choose your integration method below: **Bubble.io Plugin** (No-Code), **JavaScript SDK** (Code), or **AI Agents** (for AI-powered editors like Lovable, Base44, and Replit).
### Initialization
{% tabs %}
{% tab title="Bubble.io Plugin" %}
**Check Plugin**
Before starting, verify if the Natively plugin is already installed in your Bubble project.
1. Open your Bubble editor and navigate to the Plugins tab in the left sidebar.
2. **Check Installed Plugins:** Look through your list of installed plugins for "Natively iOS & Android app builder".
* If it IS installed: Check the version number. If an update is available (e.g., you see a button saying "Update"), click it to ensure you have the latest features and bug fixes.
* If it is NOT installed: Click the + Add plugins button, search for "Natively", and click Install.
{% endtab %}
{% tab title="JavaScript SDK" %}
**Check SDK**
Before writing any logic, ensure the Natively SDK is correctly installed and up-to-date in your codebase.
1. Open your project's main HTML file (or header settings) and look for the Natively script tag inside the `` section.
2. Install/Update: If missing or outdated, add the following code. You can specify the SDK version in the URL (e.g., `@2.26.0`).
```javascript
```
{% hint style="info" %}
To ensure you are using the most up-to-date version, check the [Natively GitHub releases page](https://github.com/buildnatively/js-sdk/releases) for the latest version number.
{% endhint %}
{% endtab %}
{% tab title="AI Agents" %}
**Initialize the SDK**
AI-powered editors like Lovable, Base44, and Replit use the JavaScript SDK to implement Natively features. Before implementing any feature, the Natively SDK must be initialized in your project.
Copy the line below and paste it into your AI agent to check and set up the Natively SDK in your project.
```
Check if the following Natively SDK script is present in the of index.html. If missing or outdated, add it: For reference: https://docs.buildnatively.com/guides/integration/how-to-get-started https://github.com/buildnatively/js-sdk/releases
```
{% endtab %}
{% endtabs %}
### Setup Logic
{% tabs %}
{% tab title="Bubble.io Plugin" %}
#### \[Element] Natively - Date Picker
#### Events:
* Date selected
* Date Picker closed
#### States:
* Selected Date
#### Actions:
* Show Date Picker
* **Title** - label shown at the top of the picker.
* **Description** - optional subtitle shown below the title (iOS only - may not have a visible effect on Android).
* **Type** - `DATE`, `TIME`, or `DATE_AND_TIME` .
* **Style** - `DARK` or `LIGHT` .
{% endtab %}
{% tab title="JavaScript SDK" %}
```javascript
// ============================================================================
// NATIVELY DATE PICKER - DOCUMENTATION & EXAMPLES
// ============================================================================
// Initialize
const picker = new NativelyDatePicker();
// ============================================================================
// ALL AVAILABLE METHODS
// ============================================================================
// picker.showDatePicker(title, description, type, style, callback)
// - Displays the native date/time picker.
// - title: string — label shown at the top of the picker
// - description: string — optional subtitle shown below the title (iOS only - may not have a visible effect on Android)
// - type: string — "DATE" / "TIME" / "DATE_AND_TIME"
// - style: string — "LIGHT" / "DARK"
// - callback: function — called when the user selects a date or dismisses the picker
// ============================================================================
// CALLBACK RESPONSE FIELDS
// ============================================================================
// resp.date - Milliseconds since epoch (Unix timestamp in ms).
// Convert to a Date object: new Date(Number(resp.date))
// Returns an invalid date if the user dismisses without selecting.
// --- Date Picker. Example. Start ---
const title = "Select Date";
const description = "";
const type = "DATE_AND_TIME"; // "DATE" / "TIME" / "DATE_AND_TIME"
const style = "LIGHT"; // "LIGHT" / "DARK"
const datepicker_callback = function(resp) {
const date = new Date(Number(resp.date));
if (isNaN(date.getTime())) {
// User dismissed the picker without selecting a date
console.log("No date selected");
return;
}
console.log("Selected date:", date);
};
picker.showDatePicker(title, description, type, style, datepicker_callback);
// --- Date Picker. Example. End ---
```
{% endtab %}
{% tab title="AI Agents" %}
AI-powered editors like Lovable, Base44, and Replit use the JavaScript SDK to implement Natively features.
Copy the line below and paste it into your AI agent.
[Your feature description] using the Natively Date Picker SDK: const picker = new NativelyDatePicker(); // picker.showDatePicker(title, description, type, style, callback) — shows the native date/time picker. // title: string — label shown at the top of the picker. // description: string — optional subtitle shown below the title (iOS only, may not affect Android). // type: "DATE" / "TIME" / "DATE_AND_TIME". // style: "LIGHT" / "DARK". // resp.date — milliseconds since epoch. Convert with: new Date(Number(resp.date)). Returns invalid date if user dismisses without selecting. For reference: https://docs.buildnatively.com/guides/integration/date-picker
{% hint style="warning" %}
Replace the placeholder at the beginning with a description of what you want to build - for example: "Show a native date picker when the user taps the booking date field and save the selected date to the form".
{% endhint %}
{% endtab %}
{% endtabs %}
### How to use
#### Choose the right type
Use `DATE` for date-only inputs like birthdays or booking dates, `TIME` for scheduling or time-based inputs, and `DATE_AND_TIME` when you need both - for example, scheduling a meeting or setting a reminder.
#### Converting the timestamp
The picker returns milliseconds since epoch via `resp.date`. Convert it to a JavaScript Date object with `new Date(Number(resp.date))`. From there, you can format it however your app needs - as a readable string, store it in your database, or pass it to another function.
#### Handling dismissal
If the user closes the picker without selecting a date, `resp.date` will return an invalid date. Always check with `isNaN(date.getTime())` before using the value to avoid passing invalid data to your app logic.
#### Match the picker style to your app
Use `LIGHT` or `DARK` to match your app's visual theme. If your app supports both light and dark modes, consider reading the current mode from [Device Info](/guides/integration/device-info.md) and passing it dynamically to the picker.
## Troubleshooting
The selected date is invalid or NaN
The user dismissed the picker without making a selection. This is expected behavior - always validate the returned value with `isNaN(date.getTime())` before using it in your app logic.
Description not visible on Android
The description field may only have a visible effect on iOS. If you need to display additional context on Android, consider adding it as a label in your app's UI instead.
Wrong date format returned
The picker always returns milliseconds since epoch - not a formatted date string. Use `new Date(Number(resp.date))` to convert it, then apply your preferred formatting library or method.
Date picker not appearing
Make sure the Natively SDK is fully loaded before calling `picker.showDatePicker()`. Trigger it via a user interaction after the SDK has initialized.
Style not applying correctly
Make sure the `style` parameter is either `"LIGHT"` or `"DARK"` - any other value may cause unexpected behavior.
[^1]: Replace this placeholder
