DatePicker
The date picker component allows users to select dates or date ranges. It triggers a dropdown containing the DatePickerWindow when interacting with the input field.
Showcase
This is a helper message
This is a helper message
<LnxDatePicker v-model="..." <-- Pass a reactive variable here to bind its value v-model:start="..." <-- Pass a reactive variable here to bind its value v-model:end="..." <-- Pass a reactive variable here to bind its value @update:modelValue="..." <-- Two way binding of the component @update:start="..." <-- Two way binding of the component start date @update:end="..." <-- Two way binding of the component end date > Pick a date <template #error> This is an error message </template> <template #helper> This is a helper message </template> </LnxDatePicker>
DateBinds the selected start date. Should be used with the `isRange` prop as `true` Default value: undefinedDateBinds the selected end date. Should be used with the `isRange` prop as `true` Default value: undefinedstring[]Names of months to be shown. By default, from the `createLnx` locale Default value: ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']string[]Names of week days to be shown in the header of the month, starting on Sunday. By default, from the `createLnx` locale Default value: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']numberDay to be used as the start of the week, from 0 (Sunday) to 6. By default, from the `createLnx` locale, or Monday Default value: 1stringText for the "select today" button. By default, the `today` text of `createLnx` Default value: "Today"DateValueFormatWhat the v-models hold: a `Date` at 00:00 UTC, or with `iso-date` a `YYYY-MM-DD` text that is `''` when empty Default value: "date"Date | stringThe first date that can be selected, as a `Date` or as `YYYY-MM-DD`. Days before it are disabled, and months and years only when all their days are Default value: undefinedDate | stringThe last date that can be selected, as a `Date` or as `YYYY-MM-DD`. Days after it are disabled, and months and years only when all their days are Default value: undefined((item: Item) => boolean) | nullA function that sets an item as disabled. It adds to `min` and `max` Default value: () => falseCalendarViewTypeWhat is going to be the selection type of the calendar Default value: CALENDAR_VIEW_TYPES.DAYbooleanIf two dates in a range can be selected, or if it's a single date selection Default value: false(date?: Date) => stringHow the date should be shown in the input when selected. By default, as the `createLnx` locale writes dates, or dd-mm-yyyy Default value: undefinedstringThe error message of the input. It is the default value for the `error` slot Default value: undefinedDates and timezones
Selected dates are emitted at 00:00 UTC (for example, 2026-11-05T00:00:00.000Z), and the dates you pass in are read in UTC, so every user sees the same day whatever their timezone. To set a value, use a date at 00:00 UTC such as new Date('2026-11-05') or new Date(Date.UTC(2026, 10, 5)). Avoid new Date() or new Date(2026, 10, 5): they are local times, and in some timezones they fall on another day in UTC.
When to use
- For a date field in a form: the calendar opens below the field and closes once a date is picked.
- When the calendar should stay open on the page, like a filter in a sidebar, use a DatePickerWindow.
Examples
Single date
<LnxDatePicker v-model="deliveryDate" placeholder="Pick a date">
Delivery date
</LnxDatePicker>2
3
Date range
With is-range, bind v-model:start and v-model:end instead of v-model.
<LnxDatePicker v-model:start="tripStart" v-model:end="tripEnd" is-range>
Trip dates
</LnxDatePicker>2
3
Months
calendar-type picks months or years instead of days.
<LnxDatePicker v-model="billingMonth" calendar-type="month">
Billing month
</LnxDatePicker>2
3
Disabled dates
is-item-disabled-fn gets every day, month or year the calendar shows and returns true for the ones that can't be picked.
<LnxDatePicker v-model="appointment" :is-item-disabled-fn="isPastDay">
Appointment
</LnxDatePicker>2
3
const startOfToday = new Date(new Date().toDateString());
function isPastDay(item: Item) {
/* Only days have a `weekDay`; months start at 0, like in `Date` */
return 'weekDay' in item && new Date(item.year, item.month, item.number) < startOfToday;
}2
3
4
5
Dates as text
With value-format="iso-date", the v-models hold 'YYYY-MM-DD' texts ('' when empty) instead of Dates, ready for a form or an API. The day picked is the day stored, whatever the timezone.
v-model: ""
<LnxDatePicker v-model="dueDate" value-format="iso-date">
Due date
</LnxDatePicker>
<p>v-model: {{ JSON.stringify(dueDate) }}</p>2
3
4
Limits
min and max take a Date or a 'YYYY-MM-DD' text. The days outside are disabled, but you can still browse to other months: a month or year is only disabled when all its days are out.
<LnxDatePicker v-model="visit" value-format="iso-date" min="2026-11-05" max="2027-02-15">
Visit
</LnxDatePicker>2
3
API
Props
| Prop | Type | Description |
|---|---|---|
v-model | Date | Binds the selected date to the reactive variable used as prop |
v-model:start | Date | Binds the selected start date. Should be used with the isRange prop as true |
v-model:end | Date | Binds the selected end date. Should be used with the isRange prop as true |
months-names | string[] | Names of months to be shown. By default, from the createLnx localeDefault: ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'] |
week-days-names | string[] | Names of week days to be shown in the header of the month, starting on Sunday. By default, from the createLnx localeDefault: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'] |
first-day-of-week | number | Day to be used as the start of the week, from 0 (Sunday) to 6. By default, from the createLnx locale, or MondayDefault: 1 |
today-text | string | Text for the "select today" button. By default, the today text of createLnxDefault: "Today" |
value-format | DateValueFormat | What the v-models hold: a Date at 00:00 UTC, or with iso-date a YYYY-MM-DD text that is '' when emptyDefault: "date" |
min | Date | string | The first date that can be selected, as a Date or as YYYY-MM-DD. Days before it are disabled, and months and years only when all their days are |
max | Date | string | The last date that can be selected, as a Date or as YYYY-MM-DD. Days after it are disabled, and months and years only when all their days are |
is-item-disabled-fn | ((item: Item) => boolean) | null | A function that sets an item as disabled. It adds to min and maxDefault: () => false |
calendar-type | CalendarViewType | What is going to be the selection type of the calendar Default: CALENDAR_VIEW_TYPES.DAY |
is-range | boolean | If two dates in a range can be selected, or if it's a single date selection Default: false |
allow-deselect | boolean | If clicking over a selected date will deselect it Default: false |
show-format | (date?: Date) => string | How the date should be shown in the input when selected. By default, as the createLnx locale writes dates, or dd-mm-yyyy |
is-loading | boolean | When loading, it is disabled and shows a different content Default: false |
has-error | boolean | Indicates if it should show the error slot Default: false |
custom-validity | string | The error message of the input. It is the default value for the error slot |
Native attributes
| Attribute | Type | Description |
|---|---|---|
placeholder | string | Changes the placeholder of the input |
readonly | boolean | Prevents the input to be edited Default: false |
disabled | boolean | Disables all actions on the input Default: false |
Events
| Event | Payload | Description |
|---|---|---|
update:modelValue | Date | Two way binding of the component |
update:start | Date | Two way binding of the component start date |
update:end | Date | Two way binding of the component end date |
Slots
| Slot | Scope | Description |
|---|---|---|
default | — | Label content of the input |
error | — | Message to be shown when the input has an error |
helper | — | Message to be shown below the input to add extra context |
Types
DateValueFormat
export const DATE_VALUE_FORMATS = {
DATE: 'date', // A Date at 00:00 UTC
ISO_DATE: 'iso-date', // A 'YYYY-MM-DD' text, or '' when empty
} as const;
export type DateValueFormat = ValueOf<typeof DATE_VALUE_FORMATS>;2
3
4
5
CalendarViewType
export const CALENDAR_VIEW_TYPES = {
DAY: 'day',
MONTH: 'month',
YEAR: 'year',
};
export type CalendarViewType = ValueOf<typeof CALENDAR_VIEW_TYPES>;2
3
4
5
6