app-date-picker

Main date picker component with calendar and year grid views

Overview

The app-date-picker component provides a Material Design date picker with calendar and year grid views. It supports customizable date ranges, disabled dates, week numbers, and full keyboard navigation.

Installation

npm install app-datepicker

Import

import 'app-datepicker/app-date-picker';

Or import from specific path:

import 'app-datepicker/dist/date-picker/app-date-picker.js';

Usage

Basic

<app-date-picker></app-date-picker>

Properties

value · string · default: "today"

Selected date in ISO 8601 format (yyyy-MM-dd), e.g. 2024-02-02. Can also accept full ISO format like 2024-02-02T00:00:00.000Z.

min · string · default: "1970-01-01"

Minimum selectable date. When not set or undefined, defaults to 1970-01-01. Accepts ISO 8601 format.

max · string · default: "2100-12-31"

Maximum selectable date. When not set or undefined, defaults to 2100-12-31. Accepts ISO 8601 format.

locale · string · default: "system default"

ISO 639 language code for localization, e.g. en-US, fr-FR, ja-JP. Defaults to system locale.

firstDayOfWeek · number · default: "0"

First day of the week (0-6, where 0 is Sunday). Accepts values between 0 and 6 inclusive.

showWeekNumber · boolean · default: "false"

When true, displays a column of week numbers on the left side of the calendar.

weekNumberType · string · default: "first-4-day-week"

How week numbers are calculated. Options:

• first-4-day-week - ISO 8601 week numbering
• first-day-of-year - Week 1 starts January 1
• first-full-week - First complete week is week 1

startView · string · default: "calendar"

Initial view to render. Options: calendar or yearGrid.

disabledDates · string · default: ""

Comma-separated dates to disable. Accepts ISO 8601 format: 2024-02-02,2024-12-25.

disabledDays · string · default: ""

Comma-separated days of week to disable (0-6). Example: 0,6 disables weekends.

Label Properties

todayLabel · string · default: "Today"

Tooltip text for today’s date in the calendar.

selectedDateLabel · string · default: "Selected date"

Tooltip text for the selected date.

nextMonthLabel · string · default: "Next month"

Tooltip for next month navigation button.

previousMonthLabel · string · default: "Previous month"

Tooltip for previous month navigation button.

chooseYearLabel · string · default: "Choose year"

Tooltip for year dropdown button in calendar view.

chooseMonthLabel · string · default: "Choose month"

Tooltip for month dropdown button in year grid view.

selectedYearLabel · string · default: "Selected year"

Tooltip for selected year in year grid.

toyearLabel · string · default: "Toyear"

Tooltip for current year in year grid.

weekLabel · string · default: "Week"

Tooltip for week number column header.

shortWeekLabel · string · default: "Wk"

Abbreviated label for week number column header.

weekNumberTemplate · string · default: "Week %s"

Template for week number tooltips. %s is replaced with week number.

Read-only Properties

valueAsDate · Date

Selected date as JavaScript Date object, e.g. new Date('2024-02-02').

valueAsNumber · number

Selected date in milliseconds since ECMAScript epoch.

Events

date-updated

Fires when the selected date changes.

interface DateUpdatedDetail {
  isKeypress: boolean;
  value: string;           // ISO 8601 format: "2024-02-02"
  valueAsDate: Date;
  valueAsNumber: number;
  key?: string;            // Present if triggered by keyboard
}

datePicker.addEventListener('date-updated', (event) => {
  console.log('Selected date:', event.detail.value);
  console.log('As Date:', event.detail.valueAsDate);
  console.log('Keyboard?', event.detail.isKeypress);
});

first-updated

Fires when the picker completes its first render.

interface FirstUpdatedDetail {
  focusableElements: HTMLElement[];
  value: string;
  valueAsDate: Date;
  valueAsNumber: number;
}

datePicker.addEventListener('first-updated', (event) => {
  console.log('Initial value:', event.detail.value);
  console.log('Focusable elements:', event.detail.focusableElements);
});

year-updated

Fires when the selected year changes in the year grid view.

interface YearUpdatedDetail {
  year: number;
}

datePicker.addEventListener('year-updated', (event) => {
  console.log('Selected year:', event.detail.year);
});

CSS Custom Properties

Theme Colors

--app-primary · color · default: "#6200ee"

Primary background color.

--app-on-primary · color · default: "#fff"

Text color on primary background.

--app-surface · color · default: "#fff"

Background color of picker surface.

--app-on-surface · color · default: "#000"

Text color on surface.

State Colors

--app-hover · color · default: "#6200ee"

Border color for hover state.

--app-on-hover · color · default: "#000"

Text color for hover state.

--app-focus · color · default: "#000"

Border color for focus state.

--app-on-focus · color · default: "#000"

Text color for focus state.

--app-on-disabled · color · default: "rgba(0, 0, 0, .38)"

Text color for disabled state.

--app-selected-hover · color · default: "#6200ee"

Border color when selected and hovered.

--app-selected-on-hover · color · default: "#fff"

Text color when selected and hovered.

--app-selected-focus · color · default: "#000"

Border color when selected and focused.

--app-selected-on-focus · color · default: "#fff"

Text color when selected and focused.

Today & Special States

--app-today · color · default: "#000"

Border color of today’s date.

--app-on-today · color · default: "#000"

Text color of today’s date.

--app-on-weekday · color · default: "#8c8c8c"

Text color for weekday headers.

--app-on-week-number · color · default: "#8c8c8c"

Text color for week numbers.

Sizing

--app-shape · dimension · default: "4px"

Border radius of the picker.

--date-picker-min-width · dimension · default: "calc((16px * 2) + (32px * 7))"

Minimum width of picker.

--date-picker-mx-width · dimension · default: "calc((16px * 2) + (32px * 7))"

Maximum width of picker.

--date-picker-min-height · dimension · default: "calc(52px + 4px + (32px * 7))"

Minimum height of picker.

--date-picker-max-height · dimension · default: "calc(52px + 4px + (32px * 7))"

Maximum height of picker.

CSS Shadow Parts

Use ::part() to style internal elements:

app-date-picker::part(header) {
  background: var(--custom-header-bg);
}

app-date-picker::part(calendar-day) {
  font-weight: bold;
}

app-date-picker::part(today) {
  border-color: red;
}

Available Parts

• header - Picker header containing month/year selector
• body - Picker body (calendar or year-grid)
• calendar - Calendar container
• table - Calendar table
• caption - Calendar caption
• weekdays - Weekday headers row
• weekday - Individual weekday header cell
• weekday-value - Weekday text content
• week-number - Week number cell
• calendar-day - Calendar day cell
• today - Today’s date
• year-grid - Year grid container
• year - Year button
• toyear - Current year

Keyboard Navigation

Calendar View

• Arrow Keys - Navigate between dates
• Home - First day of current week
• End - Last day of current week
• Page Up - Previous month
• Page Down - Next month
• Alt + Page Up - Previous year
• Alt + Page Down - Next year
• Enter / Space - Select focused date
• Tab - Move to next focusable element

Year Grid View

• Arrow Keys - Navigate between years
• Home - First year in range
• End - Last year in range
• Enter / Space - Select year and return to calendar

Example: JavaScript Integration

const datePicker = document.querySelector('app-date-picker');

// Set date programmatically
datePicker.value = '2024-12-25';

// Get date as Date object
console.log(datePicker.valueAsDate);

// Get date as timestamp
console.log(datePicker.valueAsNumber);

// Listen for changes
datePicker.addEventListener('date-updated', (e) => {
  console.log('New date:', e.detail.value);
});

// Set date range
datePicker.min = '2024-01-01';
datePicker.max = '2024-12-31';

// Disable weekends
datePicker.disabledDays = '0,6';

// Change locale
datePicker.locale = 'fr-FR';

TypeScript

import type { AppDatePicker } from 'app-datepicker/app-date-picker';

const datePicker = document.querySelector('app-date-picker') as AppDatePicker;

if (datePicker) {
  datePicker.value = '2024-12-25';
  const date: Date = datePicker.valueAsDate;
}