Upgrading from Older Versions

Overview

Version 6.0.0 represents a complete rewrite of app-datepicker with modern web technologies. This guide helps you migrate from versions 4.x and 5.x to the latest 6.0.0-rc.33 release.

Version 6.0.0 introduces breaking changes that require code modifications. Please review this guide carefully before upgrading.

Current Version

The latest release is 6.0.0-rc.33 (released March 25, 2023).

Breaking Changes

Lit 3.x Upgrade

Version 6.0.0 has been upgraded to use Lit 3.x, which introduces several breaking changes:

Lit 3.x Breaking Changes

Key changes:

The @lit/reactive-element, lit-element, and lit-html packages are now consolidated into the lit package
Updated decorator syntax and behavior
New reactivity system with improved performance
TypeScript types are now included in the main package

Migration steps:

// Before (v4-5.x)
- import { LitElement, html, css } from 'lit-element';
- import { customElement, property } from 'lit-element/decorators.js';

// After (v6.x)
+ import { LitElement, html, css } from 'lit';
+ import { customElement, property } from 'lit/decorators.js';

See the Lit upgrade guide for complete details.

TypeScript 5.3+ Required

Version 6.0.0 now requires TypeScript 5.3.3 or higher for TypeScript users.

If you’re not using TypeScript, you can ignore this requirement. However, the element is compiled with features targeting ES2021.

Update your package.json:

{
  "devDependencies": {
    "typescript": "^5.3.3"
  }
}

ES2021 Target

The element is now compiled targeting ES2021 features. You may need to transpile the package for older browser support. Supported browsers:

Chrome/Edge 100+
Firefox 96+
Safari 15.4+

Internet Explorer 11 is no longer supported. Use the new Microsoft Edge based on Chromium instead.

Element Naming and Structure

Complete Rewrite with New Architecture

Version 6.0.0 was completely rewritten from the ground up with a new component architecture:Major architectural changes:

Moved from Polymer-style to modern Lit patterns
Improved styling system with CSS custom properties
Enhanced keyboard navigation and accessibility
Better Material Design 2021 compliance
Refactored internal components for better modularity

Key component updates:

DatePickerInput - Enhanced with lazy loading support via .lazyLoad property
DatePickerDialog - Improved dialog behavior with clean slate on re-open
IconButton - Custom implementation to fix rendering bugs in Material Web Components
Year Grid and Month Calendar - Completely refactored with better performance

API Changes

Property and Method Changes

New features added:

DatePickerInput properties:
- disabled - Disable the date picker input
- readonly - Make the input read-only
- valueAsDate - Get/set value as Date object
- valueAsNumber - Get/set value as timestamp

Lazy loading support:

// DatePickerInput now supports lazy loading
datePicker.lazyLoad = true;

Export parts:
- New CSS parts exposed: today, toyear, calendar, yearGrid
- Allows better styling customization through ::part() selector

Behavior changes:

Date picker now always opens in calendar view (not year view)
Dialog re-opens with a clean slate instead of previous state
Improved .layout() method timing for property updates

Styling Changes

CSS Custom Properties

Version 6.0.0 includes major refactoring for Material Design 2021 compatibility:Simplified CSS Custom Properties:The styling system has been simplified and standardized. Many CSS custom properties were consolidated or renamed.Material Design 2021 updates:

Updated shape values (4px border radius)
Improved color system alignment with MD2021
Better scrim color customization
Enhanced styling for disabled and readonly states

Migration example:

/* Review your custom styles and update to use new CSS variables */
app-date-picker {
  /* Some variables may have changed - check component docs */
  --app-date-picker-border-radius: 4px; /* Updated default */
}

Dependency Updates

Material Web Components

Version 6.0.0 uses Material Web Components 0.27.0:

{
  "dependencies": {
    "@material/mwc-base": "^0.27.0",
    "@material/mwc-button": "^0.27.0",
    "@material/mwc-dialog": "^0.27.0",
    "@material/mwc-icon-button": "^0.27.0",
    "@material/mwc-menu": "^0.27.0",
    "@material/mwc-textfield": "^0.27.0"
  }
}

Material Web Components may have their own breaking changes. Review their documentation if you use them directly.

Migration Steps

1. Update Dependencies

Update your package.json:

npm install app-datepicker@next
# or
npm install app-datepicker@6.0.0-rc.33

If using TypeScript:

npm install -D typescript@^5.3.3

2. Update Import Statements

Change all Lit imports to use the consolidated package:

- import { LitElement, html, css } from 'lit-element';
- import { customElement, property } from 'lit-element/decorators.js';
+ import { LitElement, html, css } from 'lit';
+ import { customElement, property } from 'lit/decorators.js';

import 'app-datepicker';

3. Review Property Usage

Check if you’re using any properties that may have changed behavior:

// New properties available in v6
const picker = document.querySelector('app-date-picker-input');

// Access value as Date or timestamp
const date = picker.valueAsDate;
const timestamp = picker.valueAsNumber;

// Enable lazy loading
picker.lazyLoad = true;

// Disable or make readonly
picker.disabled = true;
picker.readonly = true;

4. Update Custom Styles

Review and update any custom CSS:

/* Use new CSS parts for targeted styling */
app-date-picker::part(today) {
  /* Style the today button */
}

app-date-picker::part(calendar) {
  /* Style the calendar container */
}

app-date-picker::part(yearGrid) {
  /* Style the year grid */
}

5. Test Thoroughly

After migration:

Test all date picker interactions - Ensure calendar navigation works
Verify event handlers - Check that date selection events still fire correctly
Test keyboard navigation - Verify accessibility improvements
Check responsive behavior - Test on different screen sizes
Validate form integration - If using in forms, test submission

Version-Specific Notes

From 4.x to 6.x

Major Version Jump

If you’re upgrading from version 4.x, you’re skipping version 5.x entirely. Version 6.0.0-rc.0 was released in November 2021, representing a complete rewrite from version 4.5.1.Key differences from v4:

Complete rewrite with Lit 3.x (v4 used lit-element 2.x)
New component architecture
Better TypeScript support
Improved accessibility
Material Design 2021 updates
Removed Polymer dependencies
Better bundle size and performance

Additional considerations:

Review all component APIs - many internals were refactored
Test all custom event handlers
Verify polyfill requirements (still need Intl.DateTimeFormat)

From 5.x to 6.x

Version 5.x was a transitional branch. The main changes are similar to those from 4.x, with the addition of Lit 3.x upgrade requirements.

Older Versions

Documentation and code for older versions are available on separate branches:

Version 4-5.x branch

Older versions are no longer actively maintained. We recommend upgrading to v6 for bug fixes and new features.

Polyfills

Version 6.0.0 still requires the same polyfills as previous versions:

Required Polyfills

Intl.DateTimeFormat and Array.prototype.find

Intl.DateTimeFormat - Required for date formatting:

<script>
  if (!window.Intl) {
    var script = document.createElement('script');
    script.src = 'https://esm.run/intl@1.2.4/dist/Intl.complete.js';
    script.onload = function() {
      console.info('Intl polyfill loaded');
    };
    script.onerror = console.error;
    document.head.appendChild(script);
  }
</script>

Array.prototype.find - Required for array operations:

<script>
  if (null == Array.prototype.find) {
    Object.defineProperty(Array.prototype, 'find', {
      value: function arrayFind(cb) {
        var filtered = this.filter(cb);
        return !filtered.length ? void 0 : filtered[0];
      },
    });
  }
</script>

Getting Help

If you encounter issues during migration:

Check the changelog - Review CHANGELOG.md for detailed changes
Review API documentation - See the component API references for updated properties
Check GitHub Issues - Search for existing issues
Join Discord - Get community support on the app-datepicker Discord

Summary Checklist

Use this checklist to ensure a smooth migration:

The effort required for migration depends on how extensively you’ve customized the components. Most applications with standard usage should only need dependency and import updates.

Advanced Features

Get Started

Guides

Migration

Upgrading from Older Versions

Overview

Current Version

Breaking Changes

Lit 3.x Upgrade

TypeScript 5.3+ Required

ES2021 Target

Element Naming and Structure

API Changes

Styling Changes

Dependency Updates

Migration Steps

1. Update Dependencies

2. Update Import Statements

3. Review Property Usage

4. Update Custom Styles

5. Test Thoroughly

Version-Specific Notes

From 4.x to 6.x

From 5.x to 6.x

Older Versions

Polyfills

Required Polyfills

Getting Help

Summary Checklist

Get Started

Guides

Migration

​Overview

​Current Version

​Breaking Changes

​Lit 3.x Upgrade

​TypeScript 5.3+ Required

​ES2021 Target

​Element Naming and Structure

​API Changes

​Styling Changes

​Dependency Updates

​Migration Steps

​1. Update Dependencies

​2. Update Import Statements

​3. Review Property Usage

​4. Update Custom Styles

​5. Test Thoroughly

​Version-Specific Notes

​From 4.x to 6.x

​From 5.x to 6.x

​Older Versions

​Polyfills

​Required Polyfills

​Getting Help

​Summary Checklist

Overview

Current Version

Breaking Changes

Lit 3.x Upgrade

TypeScript 5.3+ Required

ES2021 Target

Element Naming and Structure

API Changes

Styling Changes

Dependency Updates

Migration Steps

1. Update Dependencies

2. Update Import Statements

3. Review Property Usage

4. Update Custom Styles

5. Test Thoroughly

Version-Specific Notes

From 4.x to 6.x

From 5.x to 6.x

Older Versions

Polyfills

Required Polyfills

Getting Help

Summary Checklist