0
# jQuery DateTimePicker
1

2
jQuery DateTimePicker is a comprehensive jQuery plugin that combines both date picker and time picker functionality into a single, customizable widget. It provides advanced features including internationalization support for 40+ languages, flexible date/time formatting, validation, and extensive customization options for web applications.
3

4
## Package Information
5

6
- **Package Name**: jquery-datetimepicker
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install jquery-datetimepicker`
10
- **Dependencies**: jQuery (>= 1.7.2), jquery-mousewheel (>= 3.1.13), php-date-formatter (^1.3.4)
11

12
## Core Imports
13

14
Browser (from CDN or local files):
15

16
```html
17
<link rel="stylesheet" type="text/css" href="jquery.datetimepicker.css">
18
<script src="jquery.js"></script>
19
<script src="jquery.datetimepicker.js"></script>
20
```
21

22
Node.js/Webpack:
23

24
```javascript
25
require('jquery-datetimepicker');
26
require('jquery-datetimepicker/build/jquery.datetimepicker.min.css');
27
```
28

29
ES6 Modules:
30

31
```javascript
32
import 'jquery-datetimepicker';
33
import 'jquery-datetimepicker/build/jquery.datetimepicker.min.css';
34
```
35

36
## Basic Usage
37

38
```javascript
39
// Basic initialization
40
$('#datetimepicker').datetimepicker();
41

42
// Date picker only
43
$('#datepicker').datetimepicker({
44
    timepicker: false,
45
    format: 'd/m/Y'
46
});
47

48
// Time picker only
49
$('#timepicker').datetimepicker({
50
    datepicker: false,
51
    format: 'H:i'
52
});
53

54
// With options
55
$('#datetime').datetimepicker({
56
    format: 'Y-m-d H:i',
57
    minDate: '2023-01-01',
58
    maxDate: '2024-12-31',
59
    step: 30
60
});
61
```
62

63
## Architecture
64

65
jQuery DateTimePicker is built around several key components:
66

67
- **Plugin Method**: `$.fn.datetimepicker()` for initialization and method calls
68
- **Static API**: `$.datetimepicker` namespace for global configuration and utilities
69
- **Instance Methods**: Methods available on individual picker instances
70
- **Configuration System**: Extensive options for customization and localization
71
- **Event System**: Callbacks and triggers for user interactions
72
- **Internationalization**: Built-in support for 40+ locales with custom i18n options
73

74
## Capabilities
75

76
### Core Plugin Interface
77

78
Main jQuery plugin method for initialization and control. Supports both options-based initialization and string-based method calls.
79

80
```javascript { .api }
81
function datetimepicker(options?: DateTimePickerOptions): JQuery;
82
function datetimepicker(method: 'show' | 'hide' | 'toggle' | 'destroy' | 'reset' | 'validate'): JQuery;
83
function datetimepicker(method: string, ...args: any[]): any;
84
```
85

86
[Plugin Interface](./plugin-interface.md)
87

88
### Configuration Options
89

90
Comprehensive configuration system with 80+ options for customizing appearance, behavior, and functionality.
91

92
```javascript { .api }
93
interface DateTimePickerOptions {
94
    // Display options
95
    format?: string;
96
    formatTime?: string;
97
    formatDate?: string;
98
    datepicker?: boolean;
99
    timepicker?: boolean;
100
    inline?: boolean;
101
    
102
    // Behavior options
103
    closeOnDateSelect?: boolean;
104
    closeOnTimeSelect?: boolean;
105
    openOnFocus?: boolean;
106
    step?: number;
107
    
108
    // Date/time constraints
109
    minDate?: Date | string | boolean;
110
    maxDate?: Date | string | boolean;
111
    minTime?: Date | string | boolean;
112
    maxTime?: Date | string | boolean;
113
    
114
    // And many more...
115
}
116
```
117

118
[Configuration Options](./configuration-options.md)
119

120
### Global API
121

122
Static methods and constants available on the `$.datetimepicker` namespace for global configuration and utilities.
123

124
```javascript { .api }
125
interface DateTimePickerStatic {
126
    setLocale(locale: string): void;
127
    setDateFormatter(dateFormatter: string | DateFormatter): void;
128
    
129
    // Standard format constants
130
    readonly RFC_2822: string;
131
    readonly ATOM: string;
132
    readonly ISO_8601: string;
133
    readonly RFC_822: string;
134
    readonly RFC_850: string;
135
    readonly RFC_1036: string;
136
    readonly RFC_1123: string;
137
    readonly RSS: string;
138
    readonly W3C: string;
139
}
140

141
// Available via $.fn.datetimepicker.defaults
142
interface DateTimePickerDefaults {
143
    defaults: DateTimePickerOptions;
144
}
145
```
146

147
[Global API](./global-api.md)
148

149
### Instance Methods
150

151
Methods available on individual datetimepicker instances for programmatic control and value access.
152

153
```javascript { .api }
154
interface DateTimePickerInstance {
155
    getValue(): Date;
156
    setOptions(options: DateTimePickerOptions): void;
157
}
158
```
159

160
[Instance Methods](./instance-methods.md)
161

162
### Internationalization
163

164
Built-in internationalization support with 40+ pre-configured locales and custom i18n options.
165

166
```javascript { .api }
167
interface InternationalizationOptions {
168
    i18n?: {
169
        [locale: string]: {
170
            months: string[];
171
            dayOfWeekShort: string[];
172
            dayOfWeek: string[];
173
        };
174
    };
175
}
176
```
177

178
[Internationalization](./internationalization.md)
179

180
### Event Handling
181

182
Comprehensive event system with callbacks for user interactions and picker state changes.
183

184
```javascript { .api }
185
interface EventCallbacks {
186
    onShow?: (currentTime: Date, input: HTMLInputElement) => boolean | void;
187
    onClose?: (currentTime: Date, input: HTMLInputElement) => boolean | void;
188
    onSelectDate?: (currentTime: Date, input: HTMLInputElement) => void;
189
    onSelectTime?: (currentTime: Date, input: HTMLInputElement) => void;
190
    onChangeMonth?: (currentTime: Date, input: HTMLInputElement) => void;
191
    onChangeYear?: (currentTime: Date, input: HTMLInputElement) => void;
192
    onChangeDateTime?: (currentTime: Date, input: HTMLInputElement) => void;
193
    onGenerate?: (currentTime: Date, input: HTMLInputElement) => void;
194
}
195
```
196

197
[Event Handling](./event-handling.md)
198

199
## Types
200

201
```javascript { .api }
202
interface DateTimePickerOptions extends EventCallbacks, InternationalizationOptions {
203
    // Core options
204
    value?: string;
205
    format?: string;
206
    formatTime?: string;
207
    formatDate?: string;
208
    
209
    // Display options
210
    datepicker?: boolean;
211
    timepicker?: boolean;
212
    inline?: boolean;
213
    theme?: string;
214
    className?: string;
215
    rtl?: boolean;
216
    weeks?: boolean;
217
    
218
    // Behavior options
219
    step?: number;
220
    closeOnDateSelect?: boolean;
221
    closeOnTimeSelect?: boolean;
222
    closeOnWithoutClick?: boolean;
223
    closeOnInputClick?: boolean;
224
    openOnFocus?: boolean;
225
    mask?: boolean | string;
226
    validateOnBlur?: boolean;
227
    allowBlank?: boolean;
228
    
229
    // Date/time constraints
230
    minDate?: Date | string | boolean;
231
    maxDate?: Date | string | boolean;
232
    minTime?: Date | string | boolean;
233
    maxTime?: Date | string | boolean;
234
    minDateTime?: Date | string | boolean;
235
    maxDateTime?: Date | string | boolean;
236
    defaultTime?: string | boolean;
237
    defaultDate?: Date | string | boolean;
238
    
239
    // Advanced options
240
    allowTimes?: string[];
241
    allowDates?: (Date | string)[];
242
    allowDateRe?: RegExp | string;
243
    disabledDates?: (Date | string)[];
244
    disabledWeekDays?: number[];
245
    highlightedDates?: (Date | string | HighlightedDate)[];
246
    highlightedPeriods?: HighlightedPeriod[];
247
    weekends?: number[];
248
    
249
    // Time picker options
250
    hours12?: boolean;
251
    timeHeightInTimePicker?: number;
252
    timepickerScrollbar?: boolean;
253
    
254
    // Year/month options
255
    yearStart?: number;
256
    yearEnd?: number;
257
    monthStart?: number;
258
    monthEnd?: number;
259
    yearOffset?: number;
260
    
261
    // Appearance options
262
    todayButton?: boolean;
263
    prevButton?: boolean;
264
    nextButton?: boolean;
265
    showApplyButton?: boolean;
266
    next?: string;
267
    prev?: string;
268
    
269
    // Advanced behavior
270
    scrollMonth?: boolean;
271
    scrollTime?: boolean;
272
    scrollInput?: boolean;
273
    lazyInit?: boolean;
274
    initTime?: boolean;
275
    defaultSelect?: boolean;
276
    enterLikeTab?: boolean;
277
    
278
    // Layout options
279
    fixed?: boolean;
280
    insideParent?: boolean;
281
    parentID?: string;
282
    
283
    // Custom functions
284
    beforeShowDay?: (date: Date) => [boolean, string?, string?];
285
    onGetWeekOfYear?: (date: Date) => number;
286
    
287
    // Misc options
288
    withoutCopyright?: boolean;
289
    inverseButton?: boolean;
290
    dayOfWeekStart?: number;
291
}
292

293
interface HighlightedDate {
294
    date: Date;
295
    desc?: string;
296
    style?: string;
297
}
298

299
interface HighlightedPeriod {
300
    start: Date | string;
301
    end: Date | string;
302
    desc?: string;
303
    style?: string;
304
}
305

306
interface DateFormatter {
307
    parseDate(dateString: string, format: string): Date;
308
    formatDate(date: Date, format: string): string;
309
}
310
```