@duetds/date-picker
Advanced tools
Duet Date Picker is an open source version of Duet Design System’s Date Picker. It’s a Web Component that lets user pick a single date using a special calendar like date picker interface.
Duet Date Picker is an open source version of Duet Design System’s Date Picker. It’s a Web Component that lets user pick a date using a special calendar like date picker interface. Duet Date Picker can be implemented and used across any JavaScript framework or no framework at all. We accomplish this by using standardized web platform APIs and Web Components.
Date Picker allows you to set a minimum and a maximum allowed date. These settings can be combined or used alone, depending on the need. Please note that the date values must be passed in IS0-8601 format: YYYY-MM-DD.
Features
Simple, semantic markup. Weighs only 1.3kb minified and Gzip’ed. Doesn’t require any external library. Uses CSS3 transitions and touch events. Supports RequireJS and multiple instances. Removes the 300ms delay between a physical tap and the click event. Makes it possible to use CSS3 transitions with height: auto. Built with accessibility in mind, meaning that everything works on screen readers and with JavaScript disabled, too. Works in all major desktop and mobile browsers, including IE 6 and up. Free to use under the MIT license.
Integrating Duet Date Picker to a project without a JavaScript framework is very straight forward. If you’re working on a simple HTML page, you can start using the components immediately by adding this script tag to the <head>:
<script type="module" src="https://cdn.jsdelivr.net/npm/@duetds/date-picker@1.0.0/dist/duet/duet.esm.js"></script>
Once included, the component can be used in your markup like any other regular HTML element:
<label for="date">Choose a date</label>
<duet-date-picker identifier="date"></duet-date-picker>
Before moving further, please make sure you have Node.js installed on your machine. You can install the latest version through their website. If you’re planning on using Duet Date Picker in a project that doesn’t yet use Node Package Manager, you’ll have to first create a package.json file. To do so, run npm init and follow the steps provided.
Once finished, you can install Duet Date Picker by running:
# WEB COMPONENT for HTML, Ember, Vue.js, React, Angular and Vanilla JS:
npm install @duetds/date-picker
Once you’ve installed @duetds/date-picker package into your project, it’s recommended to create a copy task that copies Duet Date Picker component from node_modules to a location you’ve specified. One such tool that can do this is NCP. You can install ncp by running:
npm install ncp --save-dev
Once installed, add a script to your package.json that copies the component library from Duet’s package into a location you’ve specified:
"scripts": {
"copy:duet-date-picker": "ncp node_modules/@duetds/date-picker/dist src/SPECIFY_PATH"
}
You can call this script while starting up your app to make sure you’ve always got the latest code copied over. If you’re using an UNIX-like environment, you can use & as the separator:
"start": "copy:duet-date-picker & dev"
Otherwise, if you need a cross-platform solution, use npm-run-all module:
"start": "npm-run-all copy:duet-date-picker dev"
Once you have a copy task in place and have copied Duet Date Picker over, you can put script tag similar to this in the <head> of your index.html:
<script type="module" src="SPECIFY_YOUR_PATH/duet.esm.js"></script>
Once included, Duet Date Picker can be used in your basic HTML markup as in the following example:
<label for="date">Choose a date</label>
<duet-date-picker identifier="date"></duet-date-picker>
Please note: we favor the usage of CDN like JSDelivr over the above approach. Scroll to the top of the readme to find the correct script tags.
To get started, first install Duet Date Picker package:
npm install @duetds/date-picker
Before you can use Duet Date Picker in Angular, you must import and add Angular’s CUSTOM_ELEMENTS_SCHEMA. This allows the use of Web Components in HTML markup, without the compiler producing errors. The CUSTOM_ELEMENTS_SCHEMA needs to be included in any module that uses custom elements. Typically, this can be added to AppModule:
// ...
// Import custom elements schema
import { CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
@NgModule({
// ...
// Add custom elements schema to NgModule
schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class AppModule { }
The final step is to load and register Duet Date Picker in the browser. @duetds/date-picker includes a main function that handles this. That function is called defineCustomElements() and it needs to be called once during the bootstrapping of your application. One convenient place to do this is in main.ts as such:
// Import Duet Date Picker
import { defineCustomElements } from "@duetds/date-picker/dist/loader";
// ...
// Register Duet Date Picker
defineCustomElements(window);
Once included, Duet Date Picker can be used in your HTML markup as in the following example:
<label for="date">Choose a date</label>
<duet-date-picker identifier="date"></duet-date-picker>
Once included, components could also be referenced in your code using ViewChild and ViewChildren as shown in the Stencil.js documentation.
To integrate @duetds/date-picker into a Vue.js application, edit src/main.js to include:
// Import Duet Date Picker
import { defineCustomElements } from "@duetds/date-picker/dist/loader";
// ...
// configure Vue.js to ignore Duet Date Picker
Vue.config.ignoredElements = [/duet-\w*/];
// Register Duet Date Picker
defineCustomElements(window);
new Vue({
render: h => h(App)
}).$mount("#app");
Once included, Duet Date Picker can be used in your HTML markup as in the following example:
<label for="date">Choose a date</label>
<duet-date-picker identifier="date"></duet-date-picker>
With an application built using the create-react-app script the easiest way to include Duet Date Picker is to call defineCustomElements(window) from the index.js file:
// Import Duet Date Picker
import { defineCustomElements } from "@duetds/components/dist/loader";
// ...
// Register Duet Date Picker
defineCustomElements(window);
Once included, components can be used in render() function like this:
import React, { Component } from "react";
import duetRef from "@duetds/date-picker/dist/collection/utils/react";
export class ReactExample extends Component {
value = "Default Value";
onDateChanged(event) {
// value changed callback (event.detail = value)
}
render() {
return (
<duet-date-picker ref={
duetRef({
value: this.value
}, {
duetChange: event => this.onDateChanged(event)
})
}>
</duet-date-picker>
);
}
}
In the above example duetHref binds properties and events to our custom element and returns the event. It can be used in React.js’ ref attribute like this:
<duet-date-picker ref={
duetRef({
prop1: "a"
}, {
event: () => this.handleEvent()
})
}>
</duet-date-picker>
The above example is a one time binding for properties and will not update automatically. If you need updates on properties you’ll have to save element references and update them manually:
<duet-date-picker ref={
el => { this.element = duetRef({
prop1: "a" }, {
event: () => this.handleEvent()
})(el)
}>
</duet-date-picker>
Using the above reference you can update prop1 using:
this.element.prop1 = "b"
Following the steps above will enable your web components to be used in React, however there are some additional complexities that must also be considered. Custom Elements Everywhere describes them well.
Duet Date Picker can be easily integrated into Ember thanks to the ember-cli-stencil addon that handles:
vendor.jsassets directoryStart by installing the Ember addon:
ember install ember-cli-stencil
When you build your application, Stencil collections in your dependencies will be automatically discovered and pulled into your application. For more information, see ember-cli-stencil documentation.
We encourage the use of DOM events, but additionally provide custom events to make handling of certain event types easier. All custom events are documented in this same readme if you scroll down a little.
Duet Date Picker provides e.g. a custom event called duetChange. This custom event includes an object called detail which includes for example the selected date:
// Select the date picker component
var date = document.querySelector("duet-date-picker")
// Listen for when date is selected
date.addEventListener("duetChange", function(e) {
console.log("selected date", e.detail.valueAsDate)
})
The console output for the above code looks like this:
selected date Sat Aug 15 2020 00:00:00 GMT+0300 (Eastern European Summer Time)
Duet Date Picker uses CSS Custom Properties to make it easy to theme the picker. We provide the following Custom Properties that you can override with your own styles:
:root {
--duet-color-primary: #005fcc;
--duet-color-text: #333;
--duet-color-button: #f5f5f5;
--duet-color-surface: #fff;
--duet-color-overlay: rgba(0, 0, 0, 0.8);
--duet-font: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
--duet-font-normal: 400;
--duet-font-bold: 600;
--duet-radius: 4px;
--duet-z-index: 600;
}
Additionally, you can override Duet Date Picker’s default styles by using e.g. .duet-date__input selector in your own stylesheet.
Duet Date Picker package includes a hydrate app that is a bundle of the same components, but compiled so that they can be hydrated on a NodeJS server and generate static HTML and CSS. To get started, import the hydrate app into your server’s code like so:
import hydrate from "@duetds/date-picker/hydrate"
If you are using for example Eleventy, you could now add a transform into .eleventy.js configuration file that takes content as an input and processes it using Duet’s hydrate app:
eleventyConfig.addTransform("hydrate", async(content, outputPath) => {
if (process.env.ELEVENTY_ENV == "production") {
if (outputPath.endsWith(".html")) {
try {
const results = await hydrate.renderToString(content, {
clientHydrateAnnotations: true,
removeScripts: false,
removeUnusedStyles: false
})
return results.html
} catch (error) {
return error
}
}
}
return content
})
The above transform gives you server side rendered components that function without JavaScript. Please note that you need to separately pre-render the content for each theme you want to support.
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
disabled | disabled | Makes the date picker input component disabled. This prevents users from being able to interact with the input, and conveys its inactive state to assistive technologies. | boolean | false |
identifier | identifier | Adds a unique identifier for the date picker input. | string | "" |
language | language | The currently active language. This setting changes the month/year/day names and button labels as well as all screen reader labels. | "en" | "fi" | "sv" | "en" |
max | max | Minimum date allowed to be picked. Must be in IS0-8601 format: YYYY-MM-DD This setting can be used alone or together with the min property. | string | "" |
min | min | Minimum date allowed to be picked. Must be in IS0-8601 format: YYYY-MM-DD. This setting can be used alone or together with the max property. | string | "" |
name | name | Name of the date picker input. | string | "" |
role | role | Defines a specific role attribute for the date picker input. | string | undefined |
value | value | Date value. Must be in IS0-8601 format: YYYY-MM-DD | string | "" |
| Event | Description | Type |
|---|---|---|
duetBlur | Event emitted the date picker input is blurred. | CustomEvent<{ component: "duet-date-picker"; }> |
duetChange | Event emitted when a date is selected. | CustomEvent<{ component: "duet-date-picker"; valueAsDate: Date; value: string; }> |
duetFocus | Event emitted the date picker input is focused. | CustomEvent<{ component: "duet-date-picker"; }> |
hide(moveFocusToButton?: boolean) => Promise<void>Hide the calendar modal. Set moveFocusToButton to false to prevent focus
returning to the date picker's button. Default is true.
Type: Promise<void>
setFocus() => Promise<void>Sets focus on the date picker's input. Use this method instead of the global focus().
Type: Promise<void>
show() => Promise<void>Show the calendar modal, moving focus to the calendar inside.
Type: Promise<void>
1.0.0: Initial release!Licensed under the MIT license.
FAQs
Duet Date Picker is an open source version of Duet Design System’s accessible date picker.
The npm package @duetds/date-picker receives a total of 3,636 weekly downloads. As such, @duetds/date-picker popularity was classified as popular.
We found that @duetds/date-picker demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.