> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/motss/app-datepicker/llms.txt > Use this file to discover all available pages before exploring further. # Quickstart > Get from zero to a working datepicker in minutes # Quickstart Get up and running with app-datepicker in minutes. This guide walks you through installation, basic setup, and common configuration patterns to have a beautiful Material Design datepicker working in your application quickly. ## Installation First, install app-datepicker using your preferred package manager: ```bash npm theme={null} npm install app-datepicker@next ``` ```bash yarn theme={null} yarn add app-datepicker@next ``` ```bash pnpm theme={null} pnpm add app-datepicker@next ``` The `@next` tag installs version 6.x (currently at RC 33), which is the actively developed version with the latest features and improvements. ## Basic HTML usage The simplest way to get started is with a CDN import. No build tools required: Create an `index.html` file with this basic structure: ```html index.html theme={null} My Date Picker

Select a Date

``` Listen for date selection and display the value: ```html index.html theme={null} My Date Picker

Select a Date

Selected: 2024-03-15

``` Open the file in your browser and you'll see a fully functional Material Design datepicker! ## Usage with a bundler (npm/yarn/pnpm) For production applications, use app-datepicker with a module bundler like Vite, Webpack, or Rollup. ```bash theme={null} npm install app-datepicker@next lit ``` ```typescript Lit component theme={null} import { LitElement, html, css } from 'lit'; import { customElement, state } from 'lit/decorators.js'; import 'app-datepicker'; @customElement('my-app') export class MyApp extends LitElement { static styles = css` :host { display: block; padding: 20px; } app-date-picker { margin: 20px 0; } `; @state() private selectedDate = '2024-03-15'; private handleDateUpdate(e: CustomEvent) { const { value, valueAsDate } = e.detail; this.selectedDate = value; console.log('Date selected:', value, valueAsDate); } render() { return html`

Choose Your Date

Selected date: ${this.selectedDate}

`; } } ``` ```javascript Vanilla JavaScript theme={null} import 'app-datepicker'; // Create and configure the picker const picker = document.createElement('app-date-picker'); picker.value = '2024-03-15'; picker.min = '2024-01-01'; picker.max = '2024-12-31'; // Add event listener picker.addEventListener('date-updated', (event) => { const { value, valueAsDate, valueAsNumber } = event.detail; console.log('Selected:', value); console.log('As Date:', valueAsDate); console.log('As Number:', valueAsNumber); }); // Add to page document.body.appendChild(picker); ``` ```typescript React (with wrapper) theme={null} import { useEffect, useRef, useState } from 'react'; import 'app-datepicker'; function DatePicker() { const pickerRef = useRef(null); const [selectedDate, setSelectedDate] = useState('2024-03-15'); useEffect(() => { const picker = pickerRef.current; if (!picker) return; const handleDateUpdate = (e: CustomEvent) => { setSelectedDate(e.detail.value); }; picker.addEventListener('date-updated', handleDateUpdate); return () => { picker.removeEventListener('date-updated', handleDateUpdate); }; }, []); return (

Select a Date

Selected: {selectedDate}

); } ``` Ensure your bundler is configured to handle ES modules. For Vite: ```javascript vite.config.js theme={null} import { defineConfig } from 'vite'; export default defineConfig({ build: { target: 'es2021', }, }); ``` ## Component variants app-datepicker provides three component variants for different use cases: Inline calendar component for embedding directly in your UI Material Design text field with integrated datepicker dropdown Modal dialog containing the datepicker ### Using date-picker-input Perfect for form fields: ```typescript theme={null} import 'app-datepicker/app-date-picker-input'; // In your HTML/template ``` ### Using date-picker-dialog Great for mobile experiences: ```typescript theme={null} import 'app-datepicker/app-date-picker-dialog'; // Show the dialog const dialog = document.querySelector('app-date-picker-dialog'); dialog.show(); // Listen for dialog events dialog.addEventListener('closing', (event) => { const action = event.detail.action; // 'set', 'cancel', or 'reset' if (action === 'set') { console.log('Date confirmed:', dialog.value); } }); ``` ## Common configuration patterns ### Date constraints Restrict selectable dates with `min` and `max`: ```html theme={null} ``` ### Disabling specific dates Disable weekends and specific dates: ```html theme={null} ``` **disabledDays**: `0` = Sunday, `1` = Monday, ..., `6` = Saturday **disabledDates**: Comma-separated list of dates in `YYYY-MM-DD` format ### Internationalization Set the locale for proper date formatting and first day of week: ```html German (Monday start) theme={null} ``` ```html US English (Sunday start) theme={null} ``` ```html Japanese theme={null} ``` ### Week numbers Display ISO week numbers: ```html theme={null} ``` ### Start view Control which view shows first - calendar or year grid: ```html Calendar view (default) theme={null} ``` ```html Year grid view theme={null} ``` The year grid view is perfect for date of birth pickers where users need to select a year first. ## Event handling All components emit these events: ### date-updated Fired when a date is selected: ```typescript theme={null} picker.addEventListener('date-updated', (event) => { const { value, // '2024-03-15' (ISO string) valueAsDate, // Date object valueAsNumber,// Unix timestamp (ms) isKeypress, // true if selected via keyboard key // Key name if keyboard selection } = event.detail; console.log('Selected date:', value); }); ``` ### first-updated Fired once when the component first renders: ```typescript theme={null} picker.addEventListener('first-updated', (event) => { const { value, valueAsDate, valueAsNumber, focusableElements } = event.detail; console.log('Picker initialized with:', value); }); ``` ## Complete working example Here's a complete example with multiple features: ```typescript theme={null} import { LitElement, html, css } from 'lit'; import { customElement, state } from 'lit/decorators.js'; import 'app-datepicker'; @customElement('vacation-planner') export class VacationPlanner extends LitElement { static styles = css` :host { display: block; max-width: 400px; margin: 40px auto; padding: 24px; background: #f5f5f5; border-radius: 8px; } h1 { margin-top: 0; color: #333; } app-date-picker { margin: 20px 0; /* Custom theme colors */ --app-primary: #1976d2; --app-on-primary: #ffffff; --app-surface: #ffffff; } .info { padding: 16px; background: white; border-radius: 4px; margin-top: 16px; } .info p { margin: 8px 0; color: #666; } `; @state() private startDate = ''; @state() private daysUntil = 0; private handleDateSelect(e: CustomEvent) { const { value, valueAsDate } = e.detail; this.startDate = value; // Calculate days until vacation const today = new Date(); const vacation = valueAsDate; const diff = Math.ceil((vacation.getTime() - today.getTime()) / (1000 * 60 * 60 * 24)); this.daysUntil = diff; } render() { const today = new Date().toISOString().split('T')[0]; const nextYear = new Date(); nextYear.setFullYear(nextYear.getFullYear() + 1); const maxDate = nextYear.toISOString().split('T')[0]; return html`

Plan Your Vacation

${this.startDate ? html`

Vacation Start: ${this.startDate}

Days Until: ${this.daysUntil} days

${this.daysUntil < 0 ? html`

This date has passed!

` : ''}

` : html`

Select your vacation start date

`} `; } } ``` ## Value formats app-datepicker provides three ways to work with date values: ```typescript theme={null} const picker = document.querySelector('app-date-picker'); // Set value (ISO string format: YYYY-MM-DD) picker.value = '2024-03-15'; // Get value as ISO string console.log(picker.value); // '2024-03-15' // Get value as Date object console.log(picker.valueAsDate); // Date object // Get value as Unix timestamp (milliseconds) console.log(picker.valueAsNumber); // 1710460800000 ``` The `value` property must always be in `YYYY-MM-DD` format. Invalid formats will be rejected and the previous valid value will be retained. ## Styling Customize the appearance using CSS custom properties: ```css theme={null} app-date-picker { /* Primary color - selected date */ --app-primary: #6200ee; --app-on-primary: #ffffff; /* Surface colors - background */ --app-surface: #ffffff; --app-on-surface: #000000; /* Hover and focus states */ --app-hover: #f3e5f5; --app-focus: #7c4dff; /* Today indicator */ --app-today: #1976d2; --app-on-today: #ffffff; } ``` ## Next steps Now that you have a working datepicker, explore more advanced features: Explore all properties, methods, and events for app-date-picker Learn how to customize colors, spacing, and themes Use the date picker with a Material Design text field Display the date picker in a modal dialog Check out the [live demo](https://motss.xyz/demos/app-datepicker) to see all features in action with configurable code snippets.