# Date Picker Configuration and Date Formatting Guide in OutSystems

- Tool: OutSystems
- Difficulty: Beginner
- Time required: 20-25 min
- Compatibility: OutSystems 11 and ODC
- Last updated: March 2026

## TL;DR

The OutSystems UI Date Picker pattern uses Flatpickr under the hood. Set the DateFormat property to control display format (e.g., 'Y-m-d' or 'd/m/Y'), bind InitialDate to a Date variable, and handle the OnSelectedDateChanged event to capture the selected value. For formatting dates in expressions, use FormatDate(date, 'format_string') with OutSystems format tokens.

## Date Picker Configuration and Date Formatting in OutSystems

OutSystems includes a standard Input widget with InputType = Date, but for real-world apps you need the OutSystems UI Date Picker pattern — it provides a calendar popup, min/max constraints, date range selection, and locale support via Flatpickr. This tutorial covers setup from scratch and includes the most common formatting expressions developers look up repeatedly.

## Before you start

- A Reactive Web App with OutSystems UI library referenced (included by default in new apps)
- A screen open in the Screen Editor with a Form widget
- Familiarity with Local Variables in Service Studio

## Step-by-step guide

### 1. Locate and add the Date Picker pattern

In the Toolbox (left panel), search for 'Date Picker'. It appears under the Interaction category in the OutSystems UI section. Drag it inside your Form widget on the canvas. Service Studio places a DatePicker block on screen and may prompt you to accept the OutSystems UI library dependency — click Yes.

The Date Picker is an OutSystems UI Block (not a native widget), so it appears in the Widget Tree as a block element with a label placeholder above it. Create a Local Variable: right-click screen → Add Local Variable → Name = 'SelectedDate', Type = Date, Default Value = CurrDate().

**Expected result:** A calendar icon input field appears on the screen. TrueChange shows no errors.

### 2. Configure the Date Picker input parameters

Select the Date Picker block on the canvas. In the Properties Panel (right side), find the block's Input Parameters:

- DateFormat: enter 'dd/MM/yyyy' for day/month/year display (this uses OutSystems format tokens, not Flatpickr tokens — OutSystems translates internally). Common formats: 'MM/dd/yyyy' (US), 'yyyy-MM-dd' (ISO), 'dd MMM yyyy' (e.g., '30 Mar 2026')
- InitialDate: bind to SelectedDate (your Local Variable)
- MinDate: add expression for earliest selectable date, e.g. CurrDate() to prevent past dates
- MaxDate: e.g. AddYears(CurrDate(), 1) to limit to one year ahead
- ShowTodayButton: True to display a 'Today' shortcut in the calendar
- DisabledWeekDays: integer list for disabled days (0=Sunday, 6=Saturday) — e.g. [0, 6] to disable weekends

```
/* Date Picker input parameter expressions */
DateFormat:       "dd/MM/yyyy"
InitialDate:      SelectedDate
MinDate:          CurrDate()
MaxDate:          AddYears(CurrDate(), 1)
ShowTodayButton:  True
DisabledWeekDays: [6, 0]
```

**Expected result:** The calendar opens with today pre-selected, past dates greyed out, and weekends disabled.

### 3. Handle the OnSelectedDateChanged event

The Date Picker fires OnSelectedDateChanged when the user picks a date. This event provides the selected date value so you can store it.

Select the Date Picker block → Properties Panel → Events section → OnSelectedDateChanged → 'New Client Action'. Service Studio creates 'DatePickerOnSelectedDateChanged' and opens it.

In the Action Flow Editor, the event provides a local parameter 'SelectedDate' (Date type) automatically. Assign it to your screen variable:

Start → Assign: SelectedDate = SelectedDate (map event parameter to screen variable) → End

Note: the parameter name in the event handler is also 'SelectedDate' by default — rename your screen variable to 'ChosenDate' to avoid confusion, or rename the event parameter.

```
/* OnSelectedDateChanged Client Action */
/* Event input parameter: SelectedDate (Date) */
Start
  --> Assign: ChosenDate = SelectedDate
  --> End
```

**Expected result:** Picking any date in the calendar updates ChosenDate. Add an Expression widget to the screen bound to ChosenDate to verify the value updates live.

### 4. Format dates in expressions with FormatDate()

Use the FormatDate() built-in function whenever you need to display a date as a formatted string — in Expression widgets, labels, email bodies, or concatenated text.

FormatDate syntax: FormatDate(Date/DateTime value, Text format_string)

Format tokens:
- yyyy or YYYY = 4-digit year (e.g. 2026)
- yy = 2-digit year (e.g. 26)
- MM = 2-digit month (01-12)
- MMM = abbreviated month name (Jan, Feb, ...)
- MMMM = full month name (January, February, ...)
- dd = 2-digit day (01-31)
- d = day without leading zero (1-31)
- HH = 24-hour hours (00-23)
- mm = minutes (00-59)
- ss = seconds (00-59)

Common examples:
- FormatDate(CurrDate(), "dd/MM/yyyy") → '30/03/2026'
- FormatDate(CurrDate(), "MMMM d, yyyy") → 'March 30, 2026'
- FormatDate(CurrDateTime(), "yyyy-MM-dd HH:mm") → '2026-03-30 14:35'

```
/* FormatDate expression examples */
FormatDate(CurrDate(), "dd/MM/yyyy")           /* 30/03/2026 */
FormatDate(CurrDate(), "MMMM d, yyyy")         /* March 30, 2026 */
FormatDate(CurrDateTime(), "yyyy-MM-dd HH:mm") /* 2026-03-30 14:35 */
FormatDate(OrderDate, "d MMM yyyy")            /* 30 Mar 2026 */

/* Date arithmetic combined with FormatDate */
FormatDate(AddDays(CurrDate(), 30), "dd/MM/yyyy")  /* 30 days from now */
FormatDate(AddMonths(CurrDate(), 3), "MMM yyyy")   /* 3 months from now */
```

**Expected result:** Expression widgets on screen display the ChosenDate in your chosen format. TrueChange confirms the expression type is Text (correct for Expression widget value).

### 5. Enable date range mode for start/end date selection

The Date Picker supports a RangeDate mode that lets users select a start and end date with a single widget. To activate this, use the Date Picker's RangeDate parameter instead of InitialDate.

Create two Local Variables: 'StartDate' (Date) and 'EndDate' (Date). In the Date Picker Properties Panel:
- Remove the InitialDate binding
- Set RangeDate: click the expression editor → create a DatePickerRangeDate structure:
  StartDate: StartDate
  EndDate: EndDate

In the OnSelectedDateChanged event, the SelectedDate parameter becomes a DatePickerRangeDate structure. Update both variables:
Start → Assign: StartDate = SelectedDate.StartDate, EndDate = SelectedDate.EndDate → End

Display the range: FormatDate(StartDate, "dd/MM/yyyy") + " to " + FormatDate(EndDate, "dd/MM/yyyy")

```
/* RangeDate binding */
RangeDate.StartDate = StartDate
RangeDate.EndDate   = EndDate

/* OnSelectedDateChanged for range mode */
StartDate = SelectedDate.StartDate
EndDate   = SelectedDate.EndDate

/* Display expression */
FormatDate(StartDate, "dd/MM/yyyy") + " to " + FormatDate(EndDate, "dd/MM/yyyy")
```

**Expected result:** The calendar allows clicking a start date and then an end date, highlighting the range. Your StartDate and EndDate variables update correctly.

## Complete code example

File: `DatePicker_screen_configuration.txt`

```outsystems-pseudocode
/* Screen: DatePickerDemo

   Local Variables:
     ChosenDate  : Date = CurrDate()
     StartDate   : Date = NullDate()
     EndDate     : Date = NullDate()

   Widget tree:
     Form
       Date Picker (single date mode)
         DateFormat:       "dd/MM/yyyy"
         InitialDate:      ChosenDate
         MinDate:          CurrDate()
         MaxDate:          AddYears(CurrDate(), 1)
         ShowTodayButton:  True
         OnSelectedDateChanged: DatePickerOnSelectedDateChanged

       Expression: FormatDate(ChosenDate, "MMMM d, yyyy")

       Date Picker (range mode)
         RangeDate.StartDate: StartDate
         RangeDate.EndDate:   EndDate
         OnSelectedDateChanged: RangeDatePickerOnSelectedDateChanged

       Expression: FormatDate(StartDate,"dd/MM/yyyy") + " to " + FormatDate(EndDate,"dd/MM/yyyy")
*/

/* Client Action: DatePickerOnSelectedDateChanged
   Input parameter: SelectedDate (Date) */
Start
  --> Assign: ChosenDate = SelectedDate
  --> End

/* Client Action: RangeDatePickerOnSelectedDateChanged
   Input parameter: SelectedDate (DatePickerRangeDate) */
Start
  --> Assign: StartDate = SelectedDate.StartDate
              EndDate   = SelectedDate.EndDate
  --> End

/* Useful FormatDate reference:
   FormatDate(CurrDate(), "dd/MM/yyyy")          = 30/03/2026
   FormatDate(CurrDate(), "MMMM d, yyyy")        = March 30, 2026
   FormatDate(CurrDate(), "yyyy-MM-dd")          = 2026-03-30
   FormatDate(CurrDate(), "d MMM yy")            = 30 Mar 26
   FormatDate(AddDays(CurrDate(),7), "EEEE")     = Sunday (day name)
*/
```

## Common mistakes

- **Storing a FormatDate() result (Text) in an entity attribute instead of the raw Date value** — undefined Fix: Always store dates as Date or DateTime type in entities. Format only at display time using FormatDate(). Storing '30/03/2026' as Text breaks date comparisons, sorting, and aggregation.
- **Binding InitialDate to a DateTime variable when the Date Picker expects a Date type** — undefined Fix: The Date Picker's InitialDate expects a Date type, not DateTime. Use DateTimeToDate(MyDateTimeVar) to convert if needed, or change the variable type to Date.
- **Using JavaScript-style date format strings (e.g. 'MM/DD/YYYY') in FormatDate()** — undefined Fix: OutSystems uses its own format tokens. 'MM' = month (01-12), 'dd' = day (01-31), 'yyyy' = 4-digit year. Using 'DD' gives the wrong result — 'DD' is not a valid token and will render literally.
- **Not handling OnSelectedDateChanged and wondering why the variable never updates** — undefined Fix: The Date Picker fires an event; it does not two-way bind directly to a variable. You must handle OnSelectedDateChanged and Assign the event's SelectedDate parameter to your screen variable.

## Best practices

- Always handle OnSelectedDateChanged to store the picked date in a Local Variable — the Date Picker does not automatically two-way bind to a variable like a standard Input widget does.
- Use FormatDate() for display only. Store dates as the Date or DateTime data type in entities and variables — never as formatted Text strings.
- Set MinDate = CurrDate() for booking or scheduling forms to prevent users from selecting dates in the past.
- For date display in lists and tables, use FormatDate() in the Expression widget rather than relying on the default date toString rendering, which varies by locale.
- When comparing dates in filter expressions, compare Date variables directly (OrderDate >= StartDate) rather than comparing formatted strings.
- Test date formatting with the Test/Preview feature in Service Studio to confirm the format string produces the expected output before publishing.

## Frequently asked questions

### How do I display only the month and year (no day) in a Date Picker?

The standard Date Picker always shows a full calendar. For month-only selection, set the MonthSelector parameter to True (available in newer OutSystems UI versions) or use a custom Flatpickr configuration via a JavaScript node after the picker renders, setting the Flatpickr option: { plugins: [new monthSelectPlugin()] }.

### Why does my date display in US format in the live preview but European format in production?

The Date Picker and FormatDate() use the format string you specify, not the system locale. If you see inconsistent formatting, check that your Expression widget is using FormatDate() explicitly rather than relying on the default date-to-string conversion, which is locale-dependent.

### How do I get the day of the week name for a selected date?

OutSystems does not have a built-in DayOfWeekName() function. Use DayOfWeek(date) to get an integer (0=Sunday, 6=Saturday), then use an If expression or a Static Entity lookup to convert it to a name. Alternatively, FormatDate(date, 'EEEE') returns the full day name in some OutSystems versions — check your platform version.

### Does the Date Picker work on mobile apps, or only Reactive Web?

The OutSystems UI Date Picker pattern is available in both Reactive Web and Mobile apps. On mobile, it renders a native-like calendar overlay optimized for touch. The same properties, events, and FormatDate() expressions work identically across both app types.

---

Source: https://www.rapidevelopers.com/outsystems-tutorial/outsystems-date-picker-format
© RapidDev — https://www.rapidevelopers.com/outsystems-tutorial/outsystems-date-picker-format