syncfusion-winforms-datetimepicker

name	syncfusion-winforms-datetimepicker
description	Implement Syncfusion Windows Forms SfDateTimeEdit - an advanced DateTime picker control for editing dates and times. Use this when working with datetime input, date range validation, or custom display patterns. Covers editing modes (text/mask), date validation, and globalization support in WinForms applications.
metadata	{"author":"Syncfusion Inc","version":"34.1.29"}

Windows Forms DateTime Editor (SfDateTimeEdit)

The Syncfusion Windows Forms SfDateTimeEdit control allows users to edit DateTime values in text or mask format with support for minimum and maximum value validation, watermark, custom patterns, and globalization.

When to Use This Skill

Use this skill when you need to:

• Edit date and time values with formatted input and validation
• Implement date pickers for forms, appointments, or scheduling applications
• Restrict date ranges with minimum and maximum date constraints
• Display dates in various formats (long date, short date, time, custom patterns)
• Support mask mode editing with field-by-field navigation and up-down buttons
• Handle nullable dates with watermark text display
• Validate date input with custom error messages
• Support multiple cultures and globalization requirements
• Implement RTL (Right-to-Left) date editing for international applications
• Create appointment schedulers or date-based filtering interfaces

Component Overview

Key Features:

• Editing modes: Default (text) and Mask (formatted field navigation)
• Date range validation: MinDateTime and MaxDateTime properties
• Display patterns: LongDate, ShortDate, LongTime, ShortTime, FullDateTime, MonthDay, YearMonth, Custom
• Nullable dates: AllowNull with watermark text support
• Validation: Built-in validation with error messages
• Globalization: Culture-based formatting and patterns
• Navigation: Tab, arrow keys, up-down buttons for field navigation
• Appearance: Themes, fonts, colors, borders, calendar dropdown

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

Read this reference when you need to:

• Install SfDateTimeEdit via NuGet or designer
• Add the control to a Windows Forms project
• Create SfDateTimeEdit instance programmatically
• Set basic Value property
• Configure initial datetime picker setup
• Understand assembly requirements

Date Range and Value

📄 Read: references/date-range-value.md

Read this reference when you need to:

• Set and get Value property
• Implement MinDateTime and MaxDateTime constraints
• Enable nullable dates with AllowNull
• Use DateTimeText property for text-based values
• Handle value change events
• Validate date range restrictions

Display Patterns

📄 Read: references/display-patterns.md

Read this reference when you need to:

• Set DateTimePattern (LongDate, ShortDate, LongTime, etc.)
• Create custom display formats with Format property
• Display dates in different formats
• Culture-specific date formatting
• Month/year only displays
• Time-only displays

Editing Modes

📄 Read: references/editing-modes.md

Read this reference when you need to:

• Switch between Default and Mask editing modes
• Enable field-by-field navigation
• Configure ShowUpDown buttons
• Implement keyboard shortcuts
• Handle Tab and arrow key navigation
• Increment/decrement date fields

Appearance and Styling

📄 Read: references/appearance-styling.md

Read this reference when you need to:

• Apply themes with Style and ThemeName
• Customize fonts, colors, and borders
• Configure calendar dropdown appearance
• Show/hide dropdown button
• Set control size and layout
• Add tooltips

Validation and Features

📄 Read: references/validation-features.md

Read this reference when you need to:

• Configure validation modes
• Handle ValidationCompleted event
• Display validation error messages
• Set watermark text for null values
• Implement globalization and culture support
• Enable RTL (Right-to-Left) mode
• Set ReadOnly mode

Quick Start

Basic DateTime Picker

using Syncfusion.WinForms.Input;

// Create datetime editor
SfDateTimeEdit dateTimeEdit = new SfDateTimeEdit();
dateTimeEdit.Location = new Point(20, 20);
dateTimeEdit.Size = new Size(200, 30);
dateTimeEdit.Value = DateTime.Now;

// Add to form
this.Controls.Add(dateTimeEdit);

VB.NET:

Imports Syncfusion.WinForms.Input

' Create datetime editor
Dim dateTimeEdit As New SfDateTimeEdit()
dateTimeEdit.Location = New Point(20, 20)
dateTimeEdit.Size = New Size(200, 30)
dateTimeEdit.Value = DateTime.Now

' Add to form
Me.Controls.Add(dateTimeEdit)

Common Patterns

Pattern 1: Date Picker with Range Restriction

// Appointment date picker (next 30 days only)
SfDateTimeEdit appointmentDate = new SfDateTimeEdit();
appointmentDate.Value = DateTime.Now;
appointmentDate.MinDateTime = DateTime.Now;
appointmentDate.MaxDateTime = DateTime.Now.AddDays(30);
appointmentDate.DateTimePattern = DateTimePattern.LongDate;

this.Controls.Add(appointmentDate);

Pattern 2: Time Picker Only

// Time selection control
SfDateTimeEdit timePicker = new SfDateTimeEdit();
timePicker.Value = DateTime.Now;
timePicker.DateTimePattern = DateTimePattern.LongTime;
timePicker.DateTimeEditingMode = DateTimeEditingMode.Mask;
timePicker.ShowUpDown = true;

this.Controls.Add(timePicker);

Pattern 3: Custom Format Date Editor

// Custom format: "DD-MMM-YYYY" (e.g., "25-Dec-2024")
SfDateTimeEdit customDate = new SfDateTimeEdit();
customDate.Value = DateTime.Now;
customDate.DateTimePattern = DateTimePattern.Custom;
customDate.Format = "dd-MMM-yyyy";

this.Controls.Add(customDate);

Pattern 4: Nullable Date with Watermark

// Optional date field with watermark
SfDateTimeEdit optionalDate = new SfDateTimeEdit();
optionalDate.DateTimeEditingMode = DateTimeEditingMode.Mask;
optionalDate.AllowNull = true;
optionalDate.Value = null;
optionalDate.Watermark = "Select a date...";

this.Controls.Add(optionalDate);

Pattern 5: Mask Mode with Up-Down Buttons

// Field-by-field editing with increment/decrement
SfDateTimeEdit maskEditor = new SfDateTimeEdit();
maskEditor.Value = DateTime.Now;
maskEditor.DateTimeEditingMode = DateTimeEditingMode.Mask;
maskEditor.ShowUpDown = true;
maskEditor.DateTimePattern = DateTimePattern.ShortDate;

this.Controls.Add(maskEditor);

Pattern 6: Date Range Filter

// Date range for filtering (From/To dates)
SfDateTimeEdit fromDate = new SfDateTimeEdit();
fromDate.Value = DateTime.Now.AddDays(-30);
fromDate.DateTimePattern = DateTimePattern.ShortDate;

SfDateTimeEdit toDate = new SfDateTimeEdit();
toDate.Value = DateTime.Now;
toDate.DateTimePattern = DateTimePattern.ShortDate;
toDate.MinDateTime = fromDate.Value.Value;

// Update toDate minimum when fromDate changes
fromDate.ValueChanged += (s, e) => {
    if (fromDate.Value.HasValue)
        toDate.MinDateTime = fromDate.Value.Value;
};

this.Controls.Add(fromDate);
this.Controls.Add(toDate);

Pattern 7: Validated Date Entry

// Date entry with validation
SfDateTimeEdit validatedDate = new SfDateTimeEdit();
validatedDate.Value = DateTime.Now;
validatedDate.MinDateTime = new DateTime(2020, 1, 1);
validatedDate.MaxDateTime = new DateTime(2030, 12, 31);

validatedDate.ValidationCompleted += (s, e) => {
    if (!e.IsValid)
    {
        MessageBox.Show($"Invalid date: {e.ErrorMessage}");
    }
};

this.Controls.Add(validatedDate);

Key Properties

Property	Type	Description
Value	DateTime?	Current date-time value (nullable)
MinDateTime	DateTime	Minimum allowed date-time
MaxDateTime	DateTime	Maximum allowed date-time
DateTimePattern	DateTimePattern	Display format (LongDate, ShortDate, LongTime, etc.)
Format	string	Custom date-time format string
DateTimeEditingMode	DateTimeEditingMode	Editing mode (Default or Mask)
AllowNull	bool	Enable null value support
Watermark	string	Text displayed when value is null
ShowUpDown	bool	Show up-down buttons for mask mode
DateTimeText	string	Date-time as text string
ValidationErrorMessage	string	Custom validation error message
Style	SfDateTimeEditStyle	Visual style/theme
ReadOnly	bool	Enable read-only mode
ToolTipText	string	Tooltip text for control

Key Events

Event	Description
ValueChanged	Occurs when Value property changes
ValidationCompleted	Occurs after validation is completed
DateTimeTextChanged	Occurs when DateTimeText changes

Common Use Cases

Use Case 1: Appointment Scheduling

Select appointment date and time with business hours constraints.

Use Case 2: Date Range Filtering

Implement "From Date" to "To Date" filters for reports or data queries.

Use Case 3: Birth Date Entry

Capture birth dates with past date restrictions and custom format.

Use Case 4: Time Entry

Time-only input for shift scheduling or time tracking.

Use Case 5: Optional Date Fields

Forms with nullable date fields showing watermark when empty.

Use Case 6: International Date Input

Culture-specific date formatting with RTL support for Arabic, Hebrew, etc.

Best Practices

1. Set appropriate date ranges: Use MinDateTime and MaxDateTime to prevent invalid date selection
2. Choose correct pattern: Use ShortDate for space-constrained UIs, LongDate for clarity
3. Enable mask mode for precision: Use DateTimeEditingMode.Mask for field-by-field editing
4. Show watermark for optional dates: Set AllowNull=true and provide clear watermark text
5. Validate on ValueChanged: Implement validation logic in ValueChanged event handler
6. Use custom formats sparingly: Stick to standard patterns for better user familiarity
7. Consider culture settings: Test with different cultures if supporting international users
8. Handle null values: Always check Value.HasValue before using Value.Value
9. Provide tooltips: Use ToolTipText to guide users on date format or constraints
10. Test keyboard navigation: Ensure Tab and arrow keys work smoothly in mask mode

Comparison with DateTimePickerAdv

Use SfDateTimeEdit when you need:

• Modern UI with themes
• Mask mode with field navigation
• Watermark support
• Better validation features
• Culture-specific patterns

Use DateTimePickerAdv when you need:

• Custom up-down/dropdown button appearance
• Legacy application compatibility
• Specific advanced customization not in SfDateTimeEdit