vaadin/vaadin-date-picker

The Web Component providing a date selection field with scrollable month calendar. Part of the Vaadin components.

<vaadin-date-picker>

⚠️ Starting from Vaadin 20, the source code and issues for this component are migrated to the vaadin/web-components monorepository. This repository contains the source code and releases of <vaadin-date-picker> for the Vaadin versions 10 to 19.

<vaadin-date-picker> is a Web Component providing a date selection field which includes a scrollable month calendar view, part of the Vaadin components.

Live Demo ↗ | API documentation ↗

[](https://www.webcomponents.org/element/vaadin/va

<vaadin-date-picker label="Label" placeholder="Placeholder">
</vaadin-date-picker>

Installation

The Vaadin components are distributed as Bower and npm packages. Please note that the version range is the same, as the API has not changed. You should not mix Bower and npm versions in the same application, though.

Unlike the official Polymer Elements, the converted Polymer 3 compatible Vaadin components are only published on npm, not pushed to GitHub repositories.

Polymer 2 and HTML Imports Compatible Version

Install vaadin-date-picker:

bower i vaadin/vaadin-date-picker --save

Once installed, import it in your application:

<link rel="import" href="bower_components/vaadin-date-picker/vaadin-date-picker.html">

Polymer 3 and ES Modules Compatible Version

Install vaadin-date-picker:

npm i @vaadin/vaadin-date-picker --save

Once installed, import it in your application:

import '@vaadin/vaadin-date-picker/vaadin-date-picker.js';

Getting started

Vaadin components use the Lumo theme by default.

To use the Material theme, import the correspondent file from the theme/material folder.

Entry points

• The components with the Lumo theme:

  theme/lumo/vaadin-date-picker.html theme/lumo/vaadin-date-picker-light.html

• The components with the Material theme:

  theme/material/vaadin-date-picker.html theme/material/vaadin-date-picker-light.html

• Alias for theme/lumo/vaadin-date-picker.html theme/lumo/vaadin-date-picker-light.html:

  vaadin-date-picker.html vaadin-date-picker-light.html

Running demos and tests in a browser

1. Fork the vaadin-date-picker repository and clone it locally.

2. Make sure you have npm and Bower and Polymer installed.

3. When in the vaadin-date-picker directory, run npm install and then bower install to install dependencies.

4. Run npm start, browser will automatically open the component API documentation.

5. You can also open demo or in-browser tests by adding demo or test to the URL, for example:

• http://127.0.0.1:3000/components/vaadin-date-picker/demo
• http://127.0.0.1:3000/components/vaadin-date-picker/test

Running tests from the command line

1. When in the vaadin-date-picker directory, run npm test (this will execute:"test": "wct") (tests will be fetched from the test/basics.html file)

Following the coding style

We are using ESLint for linting JavaScript code. You can check if your code is following our standards by running npm run lint, which will automatically lint all .js files as well as JavaScript snippets inside .html files.

Big Thanks

Cross-browser Testing Platform and Open Source <3 Provided by Sauce Labs.

Contributing

To contribute to the component, please read the guideline first.

License

Apache License 2.0

Vaadin collects development time usage statistics to improve this product. For details and to opt-out, see https://github.com/vaadin/vaadin-usage-statistics.

vaadin-date-picker's Issues

Fix the toolbar arrow head on Galaxy S5

When scrolling the month view, the arrow head in the toolbar turns even if you don't swipe.

Footer and (fullscreen) header

Footer with a "cancel" button and a fullscreen header with value label and a clear button. Today button is a separate task.

Integration with `iron-form`

iron-form support initial plan:

• Add Polymer.IronFormElementBehavior and Polymer.IronValidatableBehavior
• Separate properties for selectedDate (Date object, default null) and value (formatted String, empty by default)
  • both writeable, updating each other if needed
  • value might also support Date assignment
• valueFormat property. Use input field format when empty.
• Date formatting depends on locale. Update value on locale change.

Integrate <vaadin-date-picker-overlay> to <vaadin-date-picker>

Replace iron-list with vaadin-scroller

Replace iron-list with a custom vaadin-scroller component.

Focus color should not show in mobile/after hitting "today"

Fix the ghost click issue

Making a selection will produce a "ghost click" that might focus an underlying input component after the overlay gets closed.

Add initial styling

We'll use fixed colors for now. Using CSS variables seems to have some issues with current implementation on all other browsers than Chrome. Trying to reduce those issues into a simple test case for Polymer.

Clear icon is shown when bound to a null value

I would expect that just an empty field is shown for both null and empty values.

Field value is difficult to read on iOS/Android because of gray background

Field value is difficult to read with white text on gray background.

Keyboard navigation

This feature is required before we can start working on ARIA support #70

https://www.w3.org/TR/wai-aria-practices/#datepicker

Prevent dropdown from overflowing out of the viewport

Screenreader support

A visually impaired user should be able to select a specific date with the help of a screenreader, using the keyboard.

After #196, the user should still be able to navigate the calendar list and to choose a specific date using that instead of just typing in a valid date in the input field.

Should be validated at least on Windows and macOS.

Phase 1 DoD

• The team should be able to select a specific date with the help of a screenreader, using the keyboard, with the following:
  • macOS VoiceOver on Chrome, Firefox and Safari
  • JAWS (free trial) and NVDA on Windows
  • iOS VoiceOver
  • Android Talkback

Phase 2 DoD

• A visually impaired outside user should be able to select a specific date (perhaps ask on the previously mentioned Reddit thread for help)
  • We assume this is just a validation for the work, and doesn’t require much extra work from us

Blocker: Scroller scrollTop is 0 on second open (IE11)

This is probably the same issue we encountered randomly in UX tests with iPad. On IE11 it's quite apparent as it reproduces every time (open the dropdown twice)

declarative locale not working

<vaadin-date-picker locale='fi'> does not show finish, but document.querySelector('vaadin-date-picker').locale = 'fi' ` works

Binding value to a YYYY-MM-DD value fails

Setting a YYYY-MM-DD value manually works, but if using Polymer data binding or programmatically setting the same string value, it does not get converted to a Date which causes and exception in date comparison (_dateEquals in vaadin-month-calendar.html)

Add localization support

Localization (autodetection, 1st day of week, months, weekdays, date format, ...).

Nice idea would be to have each locale as a pluggable package. This would enable easy contributions to the component by providing new locales.

Themability

The component should use colors from the paper-styles.

A couple of notices also related to the calendar and clear icons.

• Anton: Currently the target size are 24px × 24px. Material design guideline suggest at least 48px × 48px. But that would feel too big to align with an input field.
• Anton: Would be nice to have a ripple effect for icons.

Date grid partly hidden on narrow viewports when year scroller is visible

Sunday is not showing now when year scroller is toggled visible on narrow mobile screens, which can be confusing to the user. Needs a new UI design.

Write Asciidoc documentation

Scroll to a custom initial position when opening

Remove the year toolbar

Remove the year toolbar and revise the whole date grid design accordingly.

Date picker initial mockup of the stretched layout with year toolbar removed.

Add localization support for non moment words

vaadin-locale-aware should consider other cases not only the moment library which only covers month and day names.

Overlay detaches from field when scrolling

If you scroll while the overlay is open, it floats on top of the document instead of staying attached to the field. See video: https://dl.dropboxusercontent.com/u/182925/video/date-picker-overlay.mov

Close the overlay when tapping on already selected date

Use media queries to make the component responsive

Currently the vaadin-date-picker does work in _updateAlignmentAndPosition function to determine whether to open in "full screen mode" or not.

In addition the vaadin-date-picker-overlay has a _desktopMode property to determine if the year scroller should be always visible.

We should look into having nice media queries that also make the component responsive in regards to changes in the device orientation and browser viewport size changes.

Dropdown overflows browser window on elements demo page

For some reason the top date picker overflows, but the latter one doesn't. https://vaadin.com/elements/-/element/vaadin-date-picker

Today shortcut

icon or text ?
localization

Make sure page-up/down doesn't skip a month

If January 31th has the keyboard focus and you hit page-down to hop to february, it should focus 28th (or whatever happens to be the last date). Currently it hops over to march so it's a bug.

According to WAI-ARIA spec:
Page Up - Moves to the same date in the previous month.
Page Down - Moves to the same date in the next month.

Improve keyboard accessibility

For example Today shortcut or clearing the value should be doable with keyboard.

Add fixed date formatting for the MVP

The date should be formatted in yyyy-mm-dd format.

locale-ready fired multiple times

Changing the locale makes the event be fired more than once

DX user testing findings

• Document "value-changed" as an event in the API documentation
• Document valid date formats (both in API docs and in asciidoc) #51
• Clarify in the documentation that value is not dependent on locale (relates to previous point)
• Document supported locales (what moment.js provides), both in API docs and in asciidoc
  • List of locales

Disabled and read-only

Add year navigation

Let’s start by drawing mockups of the few new options that we’ve discussed (in addition to the previous separate year list view):

• Year scroller next to the month scroller, always visible if there is enough horizontal screen space
  • Ensure proper touch targets for the year numbers (users can tap in between years as well to jump to "june/july" immediately)
• When not enough horizontal space:
  • Have the year scroller become visible on top of the month scroller. Once scrolling stops, hide it after a short delay
  • Have an explicit toggling for the year scroller (the year number in the header)
    • The year scroller overlaps the month scroller
    • The year scroller pushes the month scroller sideways

Create MVP

MVP Features

• Month calendar view.
• Allow navigation between months.
• Allow picking a date from the month calendar (mouse/touch).
• Allow clearing of the selected value.
• Scroll to the selected date in month view when opening (current day by default).
• Allow two-way Polymer data-binding (value-changed event).
• Locale for the MVP is fixed to en-us.
• Asciidoc documentation

Feature backlog

1.0

• Replace iron-list with vaadin-scroller #33
• Refactor dropdown alignment/position, with a responsive breakpoint #34
  • Validate our layout design with mobile devices
• Year navigation #35
• Localization #36

---

• Today shortcut #40
• Setting the initial position of month view (without setting the value) #46
• Integration with iron-form #51
• Themability #55
• Keyboard navigation #76

---

Future

• Min/max date #197
• Keyboard input and related input validation #196 #238
• Week numbers
• Accessibility, screenreader support (ARIA) #70
• Disabled dates #646
• Range selection #2
• Selecting multiple dates
• Selecting repeating dates (weekly/monthly/yearly)
• Allow customizing the date cells
• Inline date picker
• Adding custom content to the dropdown (custom footer, etc)

Test the performance and rendering on older devices

UX tests revealed some serious performance and rendering issues at least with Sony Xperia Z5 and iPad 2.

Needs more investigation.

Empty slots in the beginning of month allow selection

Clear button

Refactor dropdown alignment/position

Refactor dropdown alignment/position, with a responsive breakpoint.

Feature backlog

A component for selecting a date or multiple dates/a range of dates.

Features

1.0

• Select a single date
• Date input by pointer and/or keyboard
  • Calendar picker, with quick access to all months and years
    • Optional week numbers
    • Start week from Sunday or Monday
• Accessibility
  • Keyboard focus and navigation handling
  • WAI-ARIA role attributes
• Localization (a way to replace all texts in the picker UI)
  • Provide one language (English) by default
• Customizable theme (cross-scope styling support)

Related tasks

• UI design

Future

• Custom locale which automatically sets the UI texts and date formatting
• Custom date formatting
• Textual input
  • Input validation
• Disabled/disallowed dates
  • A range (from–to is disabled)
  • Until a certain date (e.g. only allow future dates)
  • Starting from a certain date (e.g. only allow past dates)
• Select multiple dates or date ranges
  • Select a full week (or any predefined range/set)
• Customizable styling for days/months/years

Implement <vaadin-month-calendar>

Date picker is shown under toolbar in paper-header-panel on iOS

Improve the clear X placement in the UI

Many test users confused the clearing functionality to closing the popup.

Modal paper-dialog cuts of date picker

vaadin-date-picker gets cut off by modal paper-dialog. Needs overflow: visible; on the paper-dialog to work properly. Workaround should be documented unless we can think of a good solution.

Wrong date gets selected when giving a string value

<vaadin-date-picker label="Birthday" value="2000-01-01"></vaadin-date-picker> results in

Mac Chrome / Pacific time zone

Usability improvements prototyping

Prototype and ask user feedback (lightweight UX testing) would the following changes improve the date picker usability:

• tweak mouse scroll speed to less sensitive (issue origin) (#102)
• replace year scroll dots with month names (issue origin) (#138)
  • At the same time, consider adding another breakpoint above 375px and increase the width and font-size of the year scroller
• stack year numbers stacked more closely vertically (issue origin) (#138)
• ARIA spec regarding year browse with keyboard shortcut (prototype if needed, issue origin) (Shift+Page Up/Down already work)
• replace month grid with e.g. big year number overlay while scrolling (scrolling speed distracting eyesight, issue origin)

Add calendar icon

Add calendar icon to the input field as a visual indicator of the possibility to open the calendar view.

Implement <vaadin-date-picker-overlay>