> ## 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.
# Basic Usage
> Learn how to import and use app-datepicker components in your application
## Component Variants
app-datepicker provides three main component variants, each optimized for different use cases:
Standalone calendar picker component
Calendar picker inside a modal dialog
Text field with integrated calendar picker
## Installation
```bash npm theme={null}
npm install app-datepicker
```
```bash yarn theme={null}
yarn add app-datepicker
```
```bash pnpm theme={null}
pnpm add app-datepicker
```
## Importing Components
### Basic Date Picker
The `app-date-picker` component renders a standalone calendar interface.
```typescript theme={null}
import 'app-datepicker/dist/date-picker/app-date-picker.js';
// In your HTML or Lit template
const template = html`
`;
```
```html theme={null}
```
### Date Picker Dialog
The `app-date-picker-dialog` wraps the calendar in a Material Design dialog with action buttons.
```typescript theme={null}
import 'app-datepicker/dist/date-picker-dialog/app-date-picker-dialog.js';
const template = html`
`;
```
The dialog component requires Material Web Components (`@material/mwc-dialog` and `@material/mwc-button`) as peer dependencies.
### Date Picker Input
The `app-date-picker-input` provides a text field that opens a calendar picker when clicked.
```typescript theme={null}
import 'app-datepicker/dist/date-picker-input/app-date-picker-input.js';
const template = html`
`;
```
The input component extends Material Web Components' `TextField`, inheriting all its styling and functionality.
## Setting Values
All components share the same value interface:
```typescript theme={null}
// Set value as ISO date string (YYYY-MM-DD)
picker.value = '2024-03-15';
```
```typescript theme={null}
// Read value as Date object
const dateValue = picker.valueAsDate;
console.log(dateValue); // Date object
```
```typescript theme={null}
// Read value as timestamp
const timestamp = picker.valueAsNumber;
console.log(timestamp); // Unix timestamp in milliseconds
```
The `value` property must be in `YYYY-MM-DD` format. Setting `null` or empty string resets to the last valid date. To reset to today's date, set `value = undefined`.
## Common Properties
These properties are available on all three components:
### Date Range
```typescript theme={null}
// Set minimum and maximum selectable dates
picker.min = '2024-01-01';
picker.max = '2024-12-31';
```
### Start View
```typescript theme={null}
// Control initial view: 'calendar' (default) or 'yearGrid'
picker.startView = 'calendar'; // Shows month calendar
picker.startView = 'yearGrid'; // Shows year selector
```
From `src/constants.ts:22`:
```typescript theme={null}
export const startViews = ['calendar', 'yearGrid'] as const;
```
### Week Numbers
```typescript theme={null}
// Display ISO week numbers
picker.showWeekNumber = true;
picker.weekNumberType = 'first-4-day-week'; // ISO 8601 standard
```
## Event Handling
### Date Updated Event
Fired when the user selects a date:
```typescript theme={null}
picker.addEventListener('date-updated', (event) => {
const { value, valueAsDate, valueAsNumber, isKeypress, key } = event.detail;
console.log('Selected date:', value); // '2024-03-15'
console.log('As Date object:', valueAsDate); // Date object
console.log('As timestamp:', valueAsNumber); // Unix timestamp
console.log('Via keyboard:', isKeypress); // true/false
console.log('Key pressed:', key); // Key name if keyboard
});
```
From `src/typings.ts:18-23`:
```typescript theme={null}
export interface CustomEventDetail {
['date-updated']: CustomEventAction<'date-updated', CustomEventDetailDateUpdated>;
['first-updated']: CustomEventAction<'first-updated', CustomEventDetailFirstUpdated>;
['year-updated']: CustomEventAction<'year-updated', CustomEventDetailYearUpdated>;
}
interface CustomEventDetailDateUpdated extends KeyEvent, DatePickerValues {}
```
### First Updated Event
Fired once when the component first renders:
```typescript theme={null}
picker.addEventListener('first-updated', (event) => {
const { value, valueAsDate, valueAsNumber, focusableElements } = event.detail;
console.log('Initial value:', value);
console.log('Focusable elements:', focusableElements);
});
```
### Dialog-Specific Events
For `app-date-picker-dialog` only:
```typescript theme={null}
dialog.addEventListener('opening', () => {
console.log('Dialog is opening');
});
dialog.addEventListener('opened', () => {
console.log('Dialog opened');
});
dialog.addEventListener('closing', (event) => {
console.log('Dialog closing with action:', event.detail.action);
// action can be 'set', 'cancel', or 'reset'
});
dialog.addEventListener('closed', () => {
console.log('Dialog closed');
});
```
### Input-Specific Events
For `app-date-picker-input` only:
```typescript theme={null}
input.addEventListener('opened', () => {
console.log('Picker surface opened');
});
input.addEventListener('closed', () => {
console.log('Picker surface closed');
});
```
## Programmatic Control
### Dialog Methods
```typescript theme={null}
// Show the dialog
dialog.show();
// Hide the dialog
dialog.hide();
// Check if open
if (dialog.open) {
console.log('Dialog is visible');
}
```
### Input Methods
```typescript theme={null}
// Open the picker programmatically
input.showPicker();
// Close the picker
input.closePicker();
// Reset to empty value
input.reset();
```
## Complete Example
Here's a complete example using Lit:
```typescript theme={null}
import { LitElement, html, css } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import 'app-datepicker/dist/date-picker/app-date-picker.js';
@customElement('my-date-app')
export class MyDateApp extends LitElement {
static styles = css`
:host {
display: block;
padding: 16px;
}
app-date-picker {
--app-primary: #6200ee;
--app-on-primary: #fff;
}
`;
@state()
private selectedDate = '';
private handleDateUpdate(event: CustomEvent) {
this.selectedDate = event.detail.value;
console.log('New date selected:', this.selectedDate);
}
render() {
return html`
Select a Date
${this.selectedDate ? html`
Selected: ${this.selectedDate}
` : ''}
`;
}
}
```
Always use the `.property=${value}` syntax in Lit templates for boolean and object properties to ensure proper binding.
## Next Steps
Learn how to localize the date picker for different languages and regions
Customize the appearance with CSS custom properties
Explore disabled dates, week numbers, and custom formatters
View complete API documentation