syncfusion/wpf-ui-components-skills / skills/syncfusion-wpf-datetimepicker
syncfusion-wpf-datetimepicker
VerifiedImplements the Syncfusion WPF DateTimeEdit (DateTimePicker) control for date and time selection with dropdown calendar/clock support. Use this when adding datetime pickers, masked datetime input, or datetime selection controls in WPF applications. Covers DateTime binding, mask/free-form editing, pattern formatting, CultureInfo localization, dropdown views, date range restrictions, blackout dates, null value handling, watermarks, and theming with SfSkinManager.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.3 KB |
| references/appearance.md | markdown | 3.6 KB |
| references/date-restrictions.md | markdown | 6.6 KB |
| references/datetime-editing.md | markdown | 8.0 KB |
| references/dropdown-popup.md | markdown | 8.3 KB |
| references/formatting-and-culture.md | markdown | 5.4 KB |
| references/getting-started.md | markdown | 4.6 KB |
| references/localization.md | markdown | 2.8 KB |
references/date-restrictions.md
View on GitHub# Date Restrictions & Null Values — DateTimeEdit (WPF)
## Table of Contents
- [Min and Max DateTime Range](#min-and-max-datetime-range)
- [BlackoutDates — Block Specific Dates](#blackoutdates--block-specific-dates)
- [DisableDateSelection — Month/Year Only](#disabledateselection--monthyear-only)
- [IsReadOnly — Prevent All Input](#isreadonly--prevent-all-input)
- [Null Value Support](#null-value-support)
- [Watermark Text When Null](#watermark-text-when-null)
---
## Min and Max DateTime Range
Prevent users from selecting dates outside a valid range using `MinDateTime` and `MaxDateTime`. The picker stops at the boundary — it cannot be pushed past min or max.
```xml
<syncfusion:DateTimeEdit MinDateTime="01/01/2020"
MaxDateTime="12/31/2030"
Name="dateTimeEdit"/>
```
```csharp
dateTimeEdit.MinDateTime = new DateTime(2020, 1, 1);
dateTimeEdit.MaxDateTime = new DateTime(2030, 12, 31);
```
> **Important:** `MaxDateTime` must always be greater than `MinDateTime`. If you set `MinDateTime` to a value greater than the current `MaxDateTime`, `MinDateTime` is automatically reset to match `MaxDateTime`.
**Listen for range changes:**
```csharp
dateTimeEdit.MinDateTimeChanged += (d, e) =>
{
var oldMin = e.OldValue;
var newMin = e.NewValue;
};
dateTimeEdit.MaxDateTimeChanged += (d, e) =>
{
var oldMax = e.OldValue;
var newMax = e.NewValue;
};
```
---
## BlackoutDates — Block Specific Dates
Prevent selection of a specific date range (e.g., holidays, unavailable dates). Apply via the calendar's `BlackoutDates` collection in the `Loaded` event:
```xml
<syncfusion:DateTimeEdit Loaded="DateTimeEdit_Loaded" Name="dateTimeEdit"/>
```
```csharp
private void DateTimeEdit_Loaded(object sender, RoutedEventArgs e)
{
// Block all dates from the 1st to two days before today
DateTime startDate = new DateTime(DateTime.Now.Year, DateTime.Now.Month, 1);
DateTime endDate = DateTime.Now.AddDays(-2);
var blackOutRange = new Syncfusion.Windows.Controls.CalendarDateRange
{
Start = startDate,
End = endDate
};
var calendar = dateTimeEdit.DateTimeCalender
as Syncfusion.Windows.Controls.Calendar;
calendar.BlackoutDates.Add(blackOutRange);
}
```
**Blackout behavior:**
- Typing a blackout date → reverts to the nearest valid date before the blocked range
- Pressing Down arrow into a blocked range → skips to the next valid date after the range
> **Warning:** Do not set `DateTime` to a value inside a blackout range — it throws `ArgumentOutOfRangeException`. Always validate before programmatic assignment.
---
## DisableDateSelection — Month/Year Only
Prevent selecting a specific day from the calendar popup. Users can only select month and year. Combine with a `CustomPattern` to show only month/year:
```xml
<syncfusion:DateTimeEdit DisableDateSelection="True"
Pattern="CustomPattern"
CustomPattern="MM-yyyy"
Name="dateTimeEdit"/>
```
```csharp
dateTimeEdit.DisableDateSelection = true;
dateTimeEdit.Pattern = DateTimePattern.CustomPattern;
dateTimeEdit.CustomPattern = "MM-yyyy";
```
> **Use case:** Month-year pickers for reporting filters (e.g., "select billing month").
---
## IsReadOnly — Prevent All Input
Make the control display-only. Users can still select text but cannot change the value via keyboard, mouse, or the popup.
```xml
<syncfusion:DateTimeEdit IsReadOnly="True"
DateTime="06/20/2024"
Name="dateTimeEdit"/>
```
```csharp
dateTimeEdit.IsReadOnly = true;
dateTimeEdit.DateTime = new DateTime(2024, 6, 20);
```
> The value **can** still be changed programmatically in code-behind even when `IsReadOnly="True"`.
---
## Null Value Support
By default, `DateTimeEdit` always shows a date. To allow an empty/null state:
**Step 1:** Enable null date mode:
```xml
<syncfusion:DateTimeEdit IsEmptyDateEnabled="True"
NullValue="{x:Null}"
ShowMaskOnNullValue="False"
Name="dateTimeEdit"/>
```
```csharp
dateTimeEdit.IsEmptyDateEnabled = true;
dateTimeEdit.NullValue = null;
dateTimeEdit.ShowMaskOnNullValue = false;
```
| Property | Purpose |
|---|---|
| `IsEmptyDateEnabled` | Must be `true` to allow null state |
| `NullValue` | The value shown when date is cleared (set to `null`) |
| `ShowMaskOnNullValue` | `true` = show mask placeholder; `false` = show empty/watermark |
**Show mask pattern when null (instead of blank):**
```xml
<syncfusion:DateTimeEdit IsEmptyDateEnabled="True"
NullValue="{x:Null}"
ShowMaskOnNullValue="True"
Name="dateTimeEdit"/>
```
---
## Watermark Text When Null
Display a text prompt when no date is selected. Requires null value to be enabled:
```xml
<syncfusion:DateTimeEdit NoneDateText="Select a date..."
IsEmptyDateEnabled="True"
NullValue="{x:Null}"
ShowMaskOnNullValue="False"
Name="dateTimeEdit"/>
```
```csharp
dateTimeEdit.NoneDateText = "Select a date...";
dateTimeEdit.IsEmptyDateEnabled = true;
dateTimeEdit.NullValue = null;
dateTimeEdit.ShowMaskOnNullValue = false;
```
**Full null + watermark MVVM pattern:**
```csharp
// ViewModel.cs
public class ViewModel : NotificationObject
{
private DateTime? _selectedDate = null;
public DateTime? SelectedDate
{
get => _selectedDate;
set { _selectedDate = value; RaisePropertyChanged(nameof(SelectedDate)); }
}
}
```
```xml
<syncfusion:DateTimeEdit NoneDateText="No date selected"
IsEmptyDateEnabled="True"
ShowMaskOnNullValue="False"
NullValue="{x:Null}"
Name="dateTimeEdit"/>
```
---
## Gotchas
| Issue | Cause | Fix |
|---|---|---|
| `ArgumentOutOfRangeException` on DateTime set | Value is in `BlackoutDates` range | Validate date against blackout ranges before setting |
| Null value not working | `IsEmptyDateEnabled` is `false` | Set `IsEmptyDateEnabled="True"` |
| Watermark not showing | `ShowMaskOnNullValue` is `true` | Set `ShowMaskOnNullValue="False"` |
| MinDateTime > MaxDateTime silently resets | WPF property coercion behavior | Always set `MaxDateTime` before `MinDateTime`, or set them together |
| DisableDateSelection has no effect | `DropDownView` not showing calendar | Only affects calendar popup — no effect on text field editing |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |