0
# Datepicker Components
1
2
Comprehensive date selection components with multiple calendar systems, internationalization support, and flexible input integration. Supports various calendar types including Gregorian, Islamic, Hebrew, Persian, Buddhist, and Ethiopian calendars.
3
4
## Core Imports
5
6
```typescript
7
import {
8
NgbDatepickerModule,
9
NgbDate,
10
NgbCalendar,
11
NgbDateAdapter,
12
NgbDatepickerI18n
13
} from '@ng-bootstrap/ng-bootstrap';
14
```
15
16
## Capabilities
17
18
### NgbDatepicker
19
20
Main datepicker component for inline date selection.
21
22
```typescript { .api }
23
@Component({
24
selector: 'ngb-datepicker',
25
exportAs: 'ngbDatepicker'
26
})
27
class NgbDatepicker implements ControlValueAccessor {
28
/** Template for custom day rendering */
29
@Input() dayTemplate: TemplateRef<DayTemplateContext>;
30
31
/** Number of months to display */
32
@Input() displayMonths: number;
33
34
/** First day of the week (1=Monday, 7=Sunday) */
35
@Input() firstDayOfWeek: number;
36
37
/** Footer template */
38
@Input() footerTemplate: TemplateRef<any>;
39
40
/** Function to mark dates as disabled */
41
@Input() markDisabled: (date: NgbDate) => boolean;
42
43
/** Maximum selectable date */
44
@Input() maxDate: NgbDate;
45
46
/** Minimum selectable date */
47
@Input() minDate: NgbDate;
48
49
/** Navigation style (select | arrows | none) */
50
@Input() navigation: 'select' | 'arrows' | 'none';
51
52
/** How to display days outside current month */
53
@Input() outsideDays: 'visible' | 'collapsed' | 'hidden';
54
55
/** If true, show week numbers */
56
@Input() showWeekNumbers: boolean;
57
58
/** Initial month to display */
59
@Input() startDate: NgbDate;
60
61
/** Event emitted when user navigates to a different month */
62
@Output() navigate: EventEmitter<NgbDatepickerNavigateEvent>;
63
64
/** Event emitted when a date is selected */
65
@Output() select: EventEmitter<NgbDate>;
66
67
/** Navigate to a specific date */
68
navigateTo(date?: NgbDate): void;
69
}
70
```
71
72
### NgbInputDatepicker
73
74
Directive for integrating datepicker with input elements.
75
76
```typescript { .api }
77
@Directive({
78
selector: 'input[ngbDatepicker]',
79
exportAs: 'ngbInputDatepicker'
80
})
81
class NgbInputDatepicker implements ControlValueAccessor {
82
/** If true, datepicker popup will be closed automatically after date selection */
83
@Input() autoClose: boolean | 'inside' | 'outside';
84
85
/** Reference to the datepicker popup */
86
@Input() ngbDatepicker: NgbDatepicker;
87
88
/** Placement of the datepicker popup */
89
@Input() placement: Placement;
90
91
/** Event emitted when datepicker is closed */
92
@Output() closed: EventEmitter<void>;
93
94
/** Event emitted when a date is selected */
95
@Output() dateSelect: EventEmitter<NgbDate>;
96
97
/** Open the datepicker popup */
98
open(): void;
99
100
/** Close the datepicker popup */
101
close(): void;
102
103
/** Toggle the datepicker popup */
104
toggle(): void;
105
106
/** Check if the datepicker popup is open */
107
isOpen(): boolean;
108
}
109
```
110
111
### NgbDate
112
113
Immutable date object representing a specific date.
114
115
```typescript { .api }
116
class NgbDate {
117
/** Year */
118
readonly year: number;
119
120
/** Month (1-12) */
121
readonly month: number;
122
123
/** Day of month (1-31) */
124
readonly day: number;
125
126
constructor(year: number, month: number, day: number);
127
128
/** Check if this date equals another date */
129
equals(other: NgbDate): boolean;
130
131
/** Check if this date is before another date */
132
before(other: NgbDate): boolean;
133
134
/** Check if this date is after another date */
135
after(other: NgbDate): boolean;
136
137
/** Convert to string representation */
138
toString(): string;
139
140
/** Create a new NgbDate from this one */
141
static from(date: NgbDateStruct): NgbDate;
142
}
143
```
144
145
### Calendar Services
146
147
Abstract calendar service and implementations for different calendar systems.
148
149
```typescript { .api }
150
@Injectable({ providedIn: 'root' })
151
abstract class NgbCalendar {
152
/** Get today's date */
153
abstract getToday(): NgbDate;
154
155
/** Get next date */
156
abstract getNext(date: NgbDate, period?: NgbPeriod, number?: number): NgbDate;
157
158
/** Get previous date */
159
abstract getPrev(date: NgbDate, period?: NgbPeriod, number?: number): NgbDate;
160
161
/** Get number of weeks in a month */
162
abstract getWeeksPerMonth(): number;
163
164
/** Get weekdays */
165
abstract getWeekdays(): readonly number[];
166
167
/** Get months */
168
abstract getMonths(year?: number): readonly number[];
169
170
/** Check if date is valid */
171
abstract isValid(date: NgbDateStruct): boolean;
172
}
173
174
@Injectable()
175
class NgbCalendarGregorian extends NgbCalendar {}
176
177
@Injectable()
178
class NgbCalendarIslamicCivil extends NgbCalendar {}
179
180
@Injectable()
181
class NgbCalendarIslamicUmalqura extends NgbCalendar {}
182
183
@Injectable()
184
class NgbCalendarPersian extends NgbCalendar {}
185
186
@Injectable()
187
class NgbCalendarHebrew extends NgbCalendar {}
188
189
@Injectable()
190
class NgbCalendarBuddhist extends NgbCalendar {}
191
192
@Injectable()
193
class NgbCalendarEthiopian extends NgbCalendar {}
194
```
195
196
### Date Adapters
197
198
Services for converting between NgbDate and other date formats.
199
200
```typescript { .api }
201
@Injectable({ providedIn: 'root' })
202
abstract class NgbDateAdapter<T> {
203
/** Convert from model format to NgbDate */
204
abstract fromModel(value: T): NgbDate;
205
206
/** Convert from NgbDate to model format */
207
abstract toModel(date: NgbDate): T;
208
}
209
210
@Injectable()
211
class NgbDateStructAdapter extends NgbDateAdapter<NgbDateStruct> {}
212
213
@Injectable()
214
class NgbDateNativeAdapter extends NgbDateAdapter<Date> {}
215
216
@Injectable()
217
class NgbDateNativeUTCAdapter extends NgbDateAdapter<Date> {}
218
```
219
220
### Internationalization
221
222
```typescript { .api }
223
@Injectable({ providedIn: 'root' })
224
abstract class NgbDatepickerI18n {
225
/** Get weekday short names */
226
abstract getWeekdayShortName(weekday: number): string;
227
228
/** Get month short names */
229
abstract getMonthShortName(month: number, year?: number): string;
230
231
/** Get month full names */
232
abstract getMonthFullName(month: number, year?: number): string;
233
234
/** Get day ARIA label */
235
abstract getDayAriaLabel(date: NgbDate): string;
236
}
237
238
@Injectable()
239
class NgbDatepickerI18nDefault extends NgbDatepickerI18n {}
240
241
@Injectable()
242
class NgbDatepickerI18nHebrew extends NgbDatepickerI18n {}
243
244
@Injectable()
245
class NgbDatepickerI18nAmharic extends NgbDatepickerI18n {}
246
```
247
248
### Configuration Services
249
250
```typescript { .api }
251
@Injectable({ providedIn: 'root' })
252
class NgbDatepickerConfig {
253
dayTemplate: TemplateRef<DayTemplateContext>;
254
dayTemplateData: (date: NgbDate, current: {year: number, month: number}) => any;
255
displayMonths: number;
256
firstDayOfWeek: number;
257
footerTemplate: TemplateRef<any>;
258
markDisabled: (date: NgbDate) => boolean;
259
maxDate: NgbDate;
260
minDate: NgbDate;
261
navigation: 'select' | 'arrows' | 'none';
262
outsideDays: 'visible' | 'collapsed' | 'hidden';
263
showWeekNumbers: boolean;
264
startDate: NgbDate;
265
}
266
267
@Injectable({ providedIn: 'root' })
268
class NgbInputDatepickerConfig {
269
autoClose: boolean | 'inside' | 'outside';
270
container: string;
271
positionTarget: string;
272
placement: PlacementArray;
273
}
274
```
275
276
## Type Definitions
277
278
```typescript { .api }
279
interface NgbDateStruct {
280
year: number;
281
month: number;
282
day: number;
283
}
284
285
interface NgbDatepickerNavigateEvent {
286
current: {year: number, month: number};
287
next: {year: number, month: number};
288
preventDefault: () => void;
289
}
290
291
interface DayTemplateContext {
292
$implicit: NgbDate;
293
date: NgbDate;
294
currentMonth: number;
295
disabled: boolean;
296
focused: boolean;
297
selected: boolean;
298
today: boolean;
299
}
300
301
type NgbPeriod = 'y' | 'm' | 'd';
302
```
303
304
## Usage Examples
305
306
### Basic Datepicker
307
308
```typescript
309
@Component({
310
template: `
311
<ngb-datepicker
312
[(ngModel)]="selectedDate"
313
(select)="onDateSelect($event)">
314
</ngb-datepicker>
315
316
<p *ngIf="selectedDate">Selected: {{ selectedDate | json }}</p>
317
`
318
})
319
export class BasicDatepickerComponent {
320
selectedDate: NgbDate;
321
322
constructor(private calendar: NgbCalendar) {
323
this.selectedDate = calendar.getToday();
324
}
325
326
onDateSelect(date: NgbDate) {
327
console.log('Date selected:', date);
328
}
329
}
330
```
331
332
### Input Datepicker
333
334
```typescript
335
@Component({
336
template: `
337
<div class="input-group">
338
<input
339
class="form-control"
340
placeholder="yyyy-mm-dd"
341
name="dp"
342
[(ngModel)]="selectedDate"
343
ngbDatepicker
344
#d="ngbDatepicker"
345
readonly>
346
<button
347
class="btn btn-outline-secondary bi bi-calendar3"
348
type="button"
349
(click)="d.toggle()">
350
</button>
351
</div>
352
`
353
})
354
export class InputDatepickerComponent {
355
selectedDate: NgbDate;
356
}
357
```
358
359
### Custom Day Template
360
361
```typescript
362
@Component({
363
template: `
364
<ngb-datepicker
365
[(ngModel)]="selectedDate"
366
[dayTemplate]="customDay">
367
</ngb-datepicker>
368
369
<ng-template #customDay let-date="date" let-disabled="disabled">
370
<span class="custom-day" [class.weekend]="isWeekend(date)">
371
{{ date.day }}
372
</span>
373
</ng-template>
374
`
375
})
376
export class CustomDayTemplateComponent {
377
selectedDate: NgbDate;
378
379
constructor(private calendar: NgbCalendar) {}
380
381
isWeekend(date: NgbDate): boolean {
382
const dayOfWeek = this.calendar.getWeekday(date);
383
return dayOfWeek === 6 || dayOfWeek === 7; // Saturday or Sunday
384
}
385
}
386
```