# vue-hotel-datepicker: nights, check-in rules and weekly prices in one Vue component

> vue-hotel-datepicker is a Vue 3 date range picker built for booking screens, where the range has to mean a number of nights and the rules around check-in, check-out, minimum stays and weekly prices are part of the input itself. The prop surface is large and the recent releases show the project moving fast on the Vue 3 line.

**ZestfulNation/vue-hotel-datepicker** — A  VueJS v3 responsive date range picker. Displays the number of nights selected and allow several useful options like custom check-in/check-out rules, localization support and more.

- Repository: https://github.com/ZestfulNation/vue-hotel-datepicker
- Website: https://zestfulnation.github.io/vue-hotel-datepicker/
- Stars: 837 · Forks: 208
- Language: Vue
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/zestfulnation-vue-hotel-datepicker

## A range picker where the range means a number of nights

Most date pickers treat a range as two dates. vue-hotel-datepicker treats it as a stay. The component displays the number of nights selected, and it carries the constraints a booking screen needs: a minimum and maximum length of stay, rules about whether a check-out can land on the check-in date, the option to allow half days, and per period pricing.

That makes it a component for hotel, rental and appointment interfaces rather than a generic calendar. It is written for Vue 3, MIT licensed, and published to npm as vue-hotel-datepicker. The current package version is 5.1.3.

One thing to know up front about how the project publishes its own documentation. The installation and props sections of the README file are wrapped in an HTML comment, so what you see in the repository text is not what a reader gets on GitHub. The live documentation lives at the project's documentation site, zestfulnation.github.io/vue-hotel-datepicker, with a separate demo page for examples. The prop names discussed below come from the props table inside that block, so they are the same names the docs use.

The component also exposes two modes of visibility. Set through the modelValue prop it behaves like a popup attached to an input, and with alwaysVisible enabled it renders the calendar directly in the page.

## Installing the package and rendering the first calendar

The package installs like any other npm dependency:

```bash
npm install vue-hotel-datepicker
```

The same package is available through pnpm and yarn:

```bash
pnpm install vue-hotel-datepicker
```

```bash
yarn add vue-hotel-datepicker
```

Registering the component means importing the JavaScript entry point and the stylesheet separately, which is the usual split for a Vue plugin that ships compiled CSS rather than a SFC style block:

```javascript
import HotelDatePicker from 'vue-hotel-datepicker'
import 'vue-hotel-datepicker/dist/vueHotelDatepicker.css';

export default {
  components: {
    HotelDatePicker,
  },
}
```

The template usage is a single tag with a boolean bound to the visibility prop:

```html
<HotelDatePicker :modelValue="true" />
```

The modelValue prop replaced the older visibility binding in v5 and the project marks that as a breaking change, so code migrating from vue-hotel-datepicker@4.x will need adjusting there rather than in the calendar logic.

Version compatibility is the other half of installation. Since v5.0.0 the component requires Vue 3 with vue: ^3.4.0. The package manifest now depends on vue ^3.5.42, dayjs ^1.11.23, lodash.throttle ^4.1.1 and postcss ^8.5.26, and ships both a CommonJS entry at dist/vueHotelDatepicker.cjs and an ES module entry at dist/vueHotelDatepicker.es.js.

## Length of stay and calendar shape are ordinary props

Everything is configured through props on the element, so there is no separate options object to construct. The stay rules are the ones worth reading first.

minNights sets the shortest selectable range and defaults to 1, while maxNights caps it and accepts 0 or null for no limit. disableCheckoutOnCheckin, false by default, stops the user from picking the same day for check-in and check-out, and halfDay, true by default, allows a stay that starts at noon and ends before noon. singleDaySelection switches the component from a range to one selectable day when set to true.

The calendar's shape is also prop driven. showSingleMonth limits the view to one month, showWeekNumbers adds week numbers, showYear controls whether the year appears next to the month, and yearBeforeMonth moves the year in front of the month. gridStyle false hides the grid around the days, and positionRight puts the calendar to the right of the input rather than below it.

Navigation limits are handled with startDate and endDate, which disable everything outside that window, plus lastDateAvailable, which stops calendar pagination after the month of a given date. firstDayOfWeek sets the first column of the calendar, where Sun is 0 and Mon is 1, and the project notes that you also have to reorder i18n.day-names to match. The format prop takes a date format string and defaults to YYYY-MM-DD.

## Disabling days comes in three shapes, one of them deprecated

Availability rules are where a booking picker either saves you work or creates it, and this component offers three separate mechanisms for it.

disabledDates takes an array of date strings in YYYY-MM-DD format, and every date in the list becomes unselectable. disabledWeekDays takes an object with a key per weekday, from sunday to saturday, where the value says whether that day is disabled or enabled. The third, disabledDaysOfWeek, is marked DEPRECATED in the props table: it takes an array of weekday names and works only because those names are translated, which means its behaviour depends on your locale strings rather than on a fixed key.

If you are starting fresh, disabledWeekDays is the one to use, since it does not depend on translation and it is not on a deprecation path.

The related props decide what happens at the edges. enableCheckout, false by default, allows the check-out to fall on a date that is otherwise disabled, which matters when the arrival day is blocked for check-in but the guest should still be able to leave. displayClearButton, true by default, shows a clear button next to the input when dates are set, and closeDatepickerOnClickOutside, also true by default, closes the popup when the user clicks elsewhere.

## periodDates attach prices and weekly stay rules to a window

The periodDates prop is how pricing enters the calendar. It is an array of windows, each defined by startAt and endAt as YYYY-MM-DD strings, a minimumDuration number, a periodType string and an optional price float.

The periodType values are nightly, weekly_by_saturday and weekly_by_sunday, and the difference is what minimumDuration counts in. A nightly period sets a minimum number of nights, while the weekly types set a minimum stay measured in weeks from the named anchor day.

Three windows in the project's own example cover a summer, split so that one stretch is nightly and the next two are anchored to Saturday and to Sunday:

```js
periodDates: [
  {
    startAt: "2020-06-09",
    endAt: "2020-07-26",
    minimumDuration: 4,
    periodType: "nightly"
  },
  {
    startAt: "2020-07-26",
    endAt: "2020-09-30",
    minimumDuration: 1,
    periodType: "weekly_by_saturday"
  },
```

Turning those prices into visible text needs three more props. showPrice, false by default, displays the price from the periodDates array, priceSymbol, an empty string by default, is placed before the number, and priceDecimals, zero by default, controls the decimals used for weekly periods.

The bookings prop is a separate array for showing existing bookings on the calendar, which is how you would mark dates that are already taken rather than simply unavailable.

## i18n carries the night wording and the tooltip text

Localisation runs through the i18n prop, and the default object shows what you are expected to translate:

```js
i18n: {
  "night": "Night",
  "nights": "Nights",
  "week": "week",
  "weeks": "weeks",
  "day-names": ["Sun", "Mon", "Tue", "Wed", "Thur", "Fri", "Sat"],
  "check-in": "Check-in",
  "check-out": "Check-out",
```

Below those keys the default object also carries month-names, one entry per month, and a tooltip section with halfDayCheckIn, halfDayCheckOut, saturdayToSaturday, sundayToSunday and minimumRequiredPeriod, where the last one is a template string using %{minNightInPeriod} and %{night}.

Two practical consequences follow. The week start and the weekday headers are separate settings, so firstDayOfWeek only lines up the calendar if you reorder day-names yourself. And the tooltip text can be replaced wholesale with the tooltipMessage prop, which the props table says may contain HTML, so it is a place where user supplied content would need escaping on your side.

The hoveringTooltip prop defaults to true and can also be a function, which is how a caller would vary the tooltip per date rather than using the fixed X nights wording.

## A Vue 3 rewrite, a dependency swap and a security release

The release history tells you what kind of library this is. The v5.0.0 line dropped Vue 2, and the project says plainly that Vue 2 users should stay on vue-hotel-datepicker@4.x. The v5.1.1 release in August 2026 was a swap of the date library, dropping the fecha dependency in favour of dayjs, and v5.0.1 in July 2026 was a bugfix. The most recent release, v5.1.3 on 2026-10-14, is labelled a security update, and the last push to the repository was on 2026-10-14 as well.

So the library is current and moving, but it is also young on the Vue 3 line, and it has already changed its date dependency under you once. That is a normal consequence of a major version rewrite rather than a warning sign, and it does mean your own tests should cover the date arithmetic if you rely on minNights, periodDates or half day behaviour.

Building it yourself is straightforward. The package is a Vite project with dev, build and build:demo scripts, unit tests run under vitest, and linting through eslint over src and tests. The published package includes dist, src and the JSON files, and the licence is MIT, which is permissive enough for most commercial use; your counsel should confirm anything beyond that.

## Conclusion

vue-hotel-datepicker fits teams building a booking or availability screen in Vue 3 who want a range picker that understands nights, disabled days and weekly pricing without writing their own calendar logic. It is the wrong choice for a Vue 2 codebase, where the project points you at vue-hotel-datepicker@4.x instead, and for a plain date field, since almost every feature here is scoped to ranges. Verify three things before shipping it: that your Vue version satisfies the ^3.4.0 requirement, that the disabledDaysOfWeek prop being deprecated has not crept into your own code, and that the security release v5.1.3 is the version you install rather than an earlier 5.x build.

## FAQ

### How do I install vue-hotel-datepicker in a Vue 3 project?

Install the package with npm install vue-hotel-datepicker, or the pnpm and yarn equivalents, then import the component and its stylesheet separately. Since v5.0.0 it requires Vue 3 with vue: ^3.4.0, and Vue 2 projects should use vue-hotel-datepicker@4.x.

### How do I set a minimum number of nights for a date range?

Use the minNights prop, which defaults to 1, and maxNights to cap the range, where 0 or null means no limit. Set disableCheckoutOnCheckin if the guest should not be able to check out on the arrival day.

### What is the difference between disabledWeekDays and disabledDaysOfWeek?

disabledWeekDays takes an object with a key per weekday and a boolean value, while disabledDaysOfWeek takes an array of weekday names and is marked DEPRECATED because it depends on the translated names. The project documentation points new code at disabledWeekDays.

### Can vue-hotel-datepicker show nightly prices on the calendar?

Yes. Define windows in the periodDates array with startAt, endAt, minimumDuration, periodType and an optional price, then set showPrice to true, priceSymbol for the prefix and priceDecimals for the decimals of weekly periods. Supported period types are nightly, weekly_by_saturday and weekly_by_sunday.

### Which version of vue-hotel-datepicker should I install after the security update?

The newest tagged release is v5.1.3 from 2026-10-14, described as a security update, so install that rather than an earlier 5.x build. The last push to the repository was on 2026-10-14 as well.

## Sources

- [License: MIT](https://github.com/ZestfulNation/vue-hotel-datepicker/blob/main/LICENSE)
- [Project website](https://zestfulnation.github.io/vue-hotel-datepicker/)
- [README](https://github.com/ZestfulNation/vue-hotel-datepicker/blob/main/README.md)
- [Releases](https://github.com/ZestfulNation/vue-hotel-datepicker/releases)
- [ZestfulNation/vue-hotel-datepicker on GitHub](https://github.com/ZestfulNation/vue-hotel-datepicker)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/zestfulnation-vue-hotel-datepicker