Datepicker will help you with date selection. It can be used either inline with NgbDatepicker component or as a popup on any input element with NgbInputDatepicker directive. It also comes with the list of services to do formatting, calendars and i18n.

We try to keep API of our components simple, but introduce extension points, so you could enrich and reuse them. Here is a short example of the vacation range picker that displays holidays with tooltips and disables weekends.

To understand the concepts behind the datepicker, here are some topics to look at:

  1. Basic usage
  2. Getting/setting a date
  3. Moving around
  4. Date model and format
  5. Day display customization
  6. Disabling and limiting dates
  7. Range selection
  8. Alternative calendars
  9. Internationalization
  10. Keyboard shortcuts

Basic Usage

Datepicker can be used either inline or inside of the popup.

In the example below the template variable #d will point to the instance of the NgbDatepicker component in the first case. In the second it will point to the instance of the NgbInputDatepicker directive that will handle the popup containing inline datepicker.

See the NgbDatepicker API and the NgbInputDatepicker API for details on all available inputs, outputs and methods. You can customize the number of displayed months, the way navigation between months and years looks like, week numbers, etc.

If you have a very specific case of the datepicker popup, you could always create you own one and use the inline datepicker inside.

Handling the popup

It's up to you do decide when the datepicker popup should be opened and closed. The API contains .open(), .close() and .toggle() methods.

By default the popup element is attached after the input in the DOM. You have also the option of attaching it to the document body by setting the [container] input to 'body'

The popup will be closed when pressing the Escape key and when a date is selected via keyboard or mouse. It can stay open after date selection if you set [autoClose] input to false

Getting/setting a date

You have several ways of knowing when user selects a date. The date is selected either by clicking on it, pressing Space or Enter, typing text in the input or programmatically.

Datepicker is integrated with Angular forms and works with both reactive and template-driven forms. So you could use [(ngModel)], [formControl], formControlName, etc. Using ngModel will allow you both to get and set selected value.

The model, however, will NOT be a native javascript date, see the following section for more info.

Alternatively you could use the (dateSelect) or (select) outputs. The difference from ngModel is that outputs will continue emitting the same value, if user clicks on the same date. NgModel will do it only once.

Moving around

Date selection and navigation are two different things. You might have a date selected in January, but August currently displayed.

Datepicker fully supports keyboard navigation and screen readers. You can navigate between controls using Tab (focus will be trapped in the popup), move date focus with arrow keys, home, page up/down and use Shift modifier for faster navigation.

From the API, you could tell datepicker to open a specific month initially via the [startDate] input or via the .navigateTo() method

Disabling and limiting dates

You can limit the dates available for navigation and selection using [minDate] and [maxDate] inputs. If you don't specify any of them, you'll have infinite navigation and the year select box will display [-10, +10] years from currently visible month.

If you want to disable some dates for selection (ex. weekends), you have to provide the [markDisabled] function that will mark certain dates not selectable. It will be called for each newly visible day when you navigate between months.

Date model and format

Note: this should change in the near future with using native Date for all public APIs

Datepicker uses NgbDateStruct as a model and not the native Date object. It's a simple data structure with 3 fields. Also note that months start with 1 (as in ISO 8601).

You can tell datepicker to use the native javascript date adapter (bundled with ng-bootstrap) as in the custom date adapter example. For now the adapter works only for the form integration, so for instance (ngModelChange) will return a native date object. All other APIs continue to use NgbDateStruct

You can also create your own adapters if necessary by extending and implementing the NgbDateAdapter methods.

Input date parsing and formatting

In the case of the NgbInputDatepicker you should be able to parse and format the text entered in the input. This is not as easy task as it seems, because you have to account for various formats and locales. For now internally there is a service that does default formatting using ISO 8601 format.

If the entered input value is invalid, the form model will contain the entered text.

Day display customization

You can completely replace how each date is rendered by providing a custom template and rendering anything you want inside. You'll get a date context available inside the template with info on whether current date is disabled, selected, focused, etc.

For more info on what is provided in the template context, see the DayTemplateContext API

Range selection

The datepicker model is a single date, however you still can implement range selection functionality. With (select) and (dateSelect) outputs you'll know which dates are being selected and with the [dayTemplate] input you can customize the way any particular date looks. If you want to use the NgbDatepickerInput, you can also tell the popup to stay open by tuning the [autoClose] input. Check the range selection example and the initial demo on this page for more details.

If you can't use the NgbDatepickerInput directive, you should create your own popup and use NgbDatepicker inside of it. In this case we'll handle everything related to date selection and navigation for you and you can create a completely customized popup with any data model you want.

Alternative calendars

Internally datepicker uses NgbCalendar implementation for the Gregorian calendar. This could be extended to support and calendar that has notion of days, months and years.

For instance, there are other Islamic calendar implementations available:

To use any of them, simply provide a different calendar implementation

Internationalization

Since the 2.0.0 release datepicker will use the application locale if it is present to get translations of weekdays and month names. The internal service that does translation is called NgbDatepickerI18n and you could provide your own implementation if necessary.

The next/previous button labels can be translated using the standard Angular i18n mechanism. For example, previous month label is extracted under the ngb.datepicker.previous-month name.

Keyboard shortcuts

Space / Enter Selects currently focused date if it is not disabled
Escape Closes the datepicker popup (unless [autoClose] is false)
Arrow(Up|Down|Left|Right) Moves day focus inside the months view
Shift + Arrow(Up|Down|Left|Right) Selects currently focused date (if it is not disabled)
Home Moves focus to the the first day of currently opened first month
End Moves focus to the the last day of currently opened last month
Shift + Home Moves focus to the minDate (if set)
Shift + End Moves focus to the maxDate (if set)
PageDown Moves focus to the previous month
PageUp Moves focus to the next month
Shift + PageDown Moves focus to the previous year
Shift + PageUp Moves focus to the next year