Primitives

Date Picker

A date picker is a component that allows users to select a date from a calendar and navigate through months and years.

November 2025

SMTWTFS

Import

Import the DatePicker primitives from ng-primitives/date-picker.

import {
  NgpDatePicker,
  NgpDateRangePicker,
  NgpDatePickerLabel,
  NgpDatePickerNextMonth,
  NgpDatePickerPreviousMonth,
  NgpDatePickerGrid,
  NgpDatePickerCell,
  NgpDatePickerRowRender,
  NgpDatePickerCellRender,
  NgpDatePickerDateButton,
} from 'ng-primitives/date-picker';

Usage

Assemble the date-picker directives in your template.

<div ngpDatePicker>
  <div>
    <button ngpDatePickerPreviousMonth>...</button>
    <h2 ngpDatePickerLabel>...</h2>
    <button ngpDatePickerNextMonth>...</button>
  </div>
  <table ngpDatePickerGrid>
    <thead>
      <tr>
        <th scope="col" abbr="Sunday">S</th>
        ...
      </tr>
    </thead>
    <tbody>
      <tr *ngpDatePickerRowRender>
        <td *ngpDatePickerCellRender="let date" ngpDatePickerCell>
          <button ngpDatePickerDateButton>...</button>
        </td>
      </tr>
    </tbody>
  </table>
</div>

Reusable Component

Create a reusable component that uses the date picker directives.

import { Component } from '@angular/core';
import { DatePicker } from './date-picker';

@Component({
  selector: 'app-root',
  imports: [DatePicker],
  template: `
    <app-date-picker />
  `,
})
export default class App {}

Schematics

Generate a reusable date-picker component using the Angular CLI.

ng g ng-primitives:primitive date-picker

Options

  • path: The path at which to create the component file.
  • prefix: The prefix to apply to the generated component selector.
  • componentSuffix: The suffix to apply to the generated component class name.
  • fileSuffix: The suffix to apply to the generated component file name. Defaults to component.
  • exampleStyles: Whether to include example styles in the generated component file. Defaults to true.

Examples

Here are some additional examples of how to use the Date Picker primitives.

Date Range Picker

The date range picker allows users to select a range of dates by selecting the start and end dates.

August 2025

SMTWTFS

API Reference

By default, the date picker uses the native JavaScript Date object, however the date picker is designed to work with any date library. To use a date library, such as Luxon, you need to specify the appropriate date adapter. The date adapter is an abstraction layer that allows components to use date objects from any date library, ensuring compatibility and easy integration. To learn more about the date adapter, see the Date Adapter documentation.

The following directives are available to import from the ng-primitives/date-picker package:

NgpDatePicker

The outermost container for the date picker.

  • Selector: [ngpDatePicker]
  • Exported As: ngpDatePicker
ngpDatePickerMin
T | undefined

The minimum date that can be selected.

ngpDatePickerMax
T | undefined

The maximum date that can be selected.

ngpDatePickerDisabled
boolean

Determine if the date picker is disabled.

ngpDatePickerDateDisabled
(date: T) => boolean

A function that is called to determine if a specific date should be disabled.

ngpDatePickerFirstDayOfWeek
NgpDatePickerFirstDayOfWeekNumber
default: "7 (Sunday)"

Sets which day starts the week in the calendar. Accepts 0-7 where 1=Monday, 2=Tuesday, 3=Wednesday, 4=Thursday, 5=Friday, 6=Saturday, 7=Sunday. Defaults to NgpDatePickerConfig.firstDayOfWeek (default 7 if not overridden). Note: Update calendar header column order when changing from Sunday start.

ngpDatePickerDate
T | undefined

The selected value.

ngpDatePickerFocusedDate
T

The focused value.

ngpDatePickerDateChange
T | undefined

Emit when the date changes.

ngpDatePickerFocusedDateChange
T

Emit when the focused date changes.

Data Attributes

The following data attributes are available on the ngpDatePicker directive:

Attribute Description
data-disabled Applied when the date picker is disabled.

NgpDateRangePicker

  • Selector: [ngpDateRangePicker]
  • Exported As: ngpDateRangePicker
ngpDateRangePickerMin
T | undefined

The minimum date that can be selected.

ngpDateRangePickerMax
T | undefined

The maximum date that can be selected.

ngpDateRangePickerDisabled
boolean

Determine if the date picker is disabled.

ngpDateRangePickerDateDisabled
(date: T) => boolean

A function that is called to determine if a specific date should be disabled.

ngpDateRangePickerFirstDayOfWeek
NgpDatePickerFirstDayOfWeekNumber
default: "7 (Sunday)"

Sets which day starts the week in the calendar. Accepts 0-7 where 1=Monday, 2=Tuesday, 3=Wednesday, 4=Thursday, 5=Friday, 6=Saturday, 7=Sunday. Defaults to NgpDatePickerConfig.firstDayOfWeek (default 7 if not overridden). Note: Update calendar header column order when changing from Sunday start.

ngpDateRangePickerStartDate
T | undefined

The selected start date

ngpDateRangePickerEndDate
T | undefined

The selected end date

ngpDateRangePickerFocusedDate
T

The focused value.

ngpDateRangePickerStartDateChange
T | undefined

Emit when the date changes.

ngpDateRangePickerEndDateChange
T | undefined

Emit when the end date changes.

ngpDateRangePickerFocusedDateChange
T

Emit when the focused date changes.

Data Attributes

The following data attributes are available on the ngpDateRangePicker directive:

Attribute Description
data-disabled Applied when the date range picker is disabled.

NgpDatePickerLabel

The label that displays the current month and year typically in the header of the date picker. This will be announced by screen readers when the date changes.

  • Selector: [ngpDatePickerLabel]
  • Exported As: ngpDatePickerLabel
aria-live
string

Define the aria live attribute.

Data Attributes

The following data attributes are available on the ngpDatePickerLabel directive:

Attribute Description
data-disabled Applied when the date picker is disabled.

NgpDatePickerPreviousMonth

A button that navigates to the previous month.

  • Selector: [ngpDatePickerPreviousMonth]
  • Exported As: ngpDatePickerPreviousMonth

Data Attributes

The following data attributes are available on the ngpDatePickerPreviousMonth directive:

Attribute Description
data-hover Applied when the button is hovered.
data-focus-visible Applied when the button is focused.
data-press Applied when the button is pressed.
data-disabled Applied when the button is disabled.

NgpDatePickerNextMonth

A button that navigates to the next month.

  • Selector: [ngpDatePickerNextMonth]
  • Exported As: ngpDatePickerNextMonth

Data Attributes

The following data attributes are available on the ngpDatePickerNextMonth directive:

Attribute Description
data-hover Applied when the button is hovered.
data-focus-visible Applied when the button is focused.
data-press Applied when the button is pressed.
data-disabled Applied when the button is disabled.

NgpDatePickerGrid

The grid that contains the days of the month.

  • Selector: [ngpDatePickerGrid]
  • Exported As: ngpDatePickerGrid

Data Attributes

The following data attributes are available on the ngpDatePickerGrid directive:

Attribute Description
data-disabled Applied when the date picker is disabled.

NgpDatePickerRowRender

A structural directive that renders a row of weekdays in the date picker grid.

  • Selector: [ngpDatePickerRowRender]
  • Exported As: ngpDatePickerRowRender

NgpDatePickerCellRender

A structural directive that renders a cell in the date picker grid.

  • Selector: *ngpDatePickerCellRender
  • Exported As: ngpDatePickerCellRender

The following context fields are available on the ngpDatePickerCellRender directive:

$implicit
T

The date value for the cell.

NgpDatePickerCell

A cell in the date picker grid.

  • Selector: [ngpDatePickerCell]
  • Exported As: ngpDatePickerCell

Data Attributes

The following data attributes are available on the ngpDatePickerCell directive:

Attribute Description
data-disabled Applied when the cell is disabled.
data-selected Applied when the cell is selected.

NgpDatePickerDateButton

A button that represents a date in the date picker grid.

  • Selector: [ngpDatePickerDateButton]
  • Exported As: ngpDatePickerDateButton

Data Attributes

The following data attributes are available on the ngpDatePickerDateButton directive:

Attribute Description
data-selected Applied when the button is selected.
data-outside-month Applied when the button is outside the current month.
data-today Applied when the button represents the current date.
data-hover Applied when the button is hovered.
data-focus-visible Applied when the button is focused.
data-press Applied when the button is pressed.
data-disabled Applied when the button is disabled.
data-range-start Applied when the button is the start of a date range.
data-range-end Applied when the button is the end of a date range.
data-range-between Applied when the button is between the start and end of a date range.

Accessibility

Adheres to the WAI-ARIA design pattern.

Keyboard Interactions

  • Space - Selects the focused date.
  • Enter - Selects the focused date.
  • ArrowUp - Moves focus to the same day of the previous week.
  • ArrowDown - Moves focus to the same day of the next week.
  • ArrowLeft - Moves focus to the previous day.
  • ArrowRight - Moves focus to the next day.
  • Home - Moves focus to the first day of the month.
  • End - Moves focus to the last day of the month.
  • PageUp - Moves focus to the same date in the previous month.
  • PageDown - Moves focus to the same date in the next month.

Global Configuration

You can configure the default options for all NgpDatePicker and NgpDateRangePicker calendars in your application by using the provideDatePickerConfig function in a providers array.

import { provideDatePickerConfig } from 'ng-primitives/date-picker';

bootstrapApplication(AppComponent, {
  providers: [
    provideDatePickerConfig({
      firstDayOfWeek: 1, // Monday
    }),
  ],
});

NgpDatePickerConfig

firstDayOfWeek
NgpDatePickerFirstDayOfWeekNumber (1-7)

Sets which day starts the week in date picker and date range picker calendars. Accepts 1-7 where:

  • 1=Monday,
  • 2=Tuesday,
  • 3=Wednesday,
  • 4=Thursday,
  • 5=Friday,
  • 6=Saturday,
  • 7=Sunday (default).
Choose based on your users' cultural expectations - most international applications use 1 (Monday), while US applications typically use 7 (Sunday).
Note: When using a non-Sunday start day, update your calendar header column order accordingly.

Copyright © 2025 Angular Primitives