@devslab/vue-date-rail

Live demo · Edit on StackBlitz

Horizontal infinite-scroll date rail (day / month strip) picker for Vue 3. Built for mobile-first apps — delivery tracking, booking, scheduling — where a horizontally scrollable strip of days beats a calendar popup.

한국어 README

Features

• Infinite scroll — days load on demand as you scroll toward either end, with scroll-position compensation (no visual jump when past dates are prepended)
• <DateRail> + <MonthRail> — day strip and month strip, sharing one theming system
• Headless core — the infinite-scroll logic is exposed as a useDateRail() composable; bring your own markup if the default cells don't fit
• i18n via Intl — pass any BCP 47 locale (ko, en, ja, de, ar, …); no locale files to import
• min/max dates & disabled dates — range clamping stops the infinite scroll at the boundary
• Marker slot — render event dots/badges under any date cell
• Keyboard navigation — ← / → move a day (month), Home jumps to today
• Desktop-friendly scrolling — vertical mouse wheel is translated to horizontal scroll, and mouse drag-to-scroll works out of the box (touch uses native scrolling)
• Themeable — plain CSS custom properties (--vdr-*), no preprocessor, dark-mode friendly
• Tailwind-ready — unstyled + cellClass props and data-selected / data-today / data-disabled attributes for utility-CSS styling
• Zero dependencies — only vue as a peer dependency

Install

npm install @devslab/vue-date-rail

Quick start

<script setup lang="ts">
import { ref } from 'vue';
import { DateRail } from '@devslab/vue-date-rail';
import '@devslab/vue-date-rail/style.css';

const date = ref(new Date());
</script>

<template>
  <DateRail v-model="date" locale="ko" />
</template>

Or register globally:

import { DateRailPlugin } from '@devslab/vue-date-rail';
app.use(DateRailPlugin); // registers <DateRail> and <MonthRail>

<DateRail>

<DateRail
  v-model="date"
  locale="en"
  :initial-past-days="30"
  :initial-future-days="30"
  :load-more-days="14"
  :min-date="minDate"
  :max-date="maxDate"
  :disabled-date="(d) => d.getDay() === 0"
>
  <template #marker="{ date }">
    <span v-if="hasEvent(date)" class="dot" />
  </template>
</DateRail>

Props

Prop	Type	Default	Description
modelValue	Date	— (required)	Selected date (v-model). Emitted normalized to local midnight.
locale	string	'en'	BCP 47 locale for Intl-based labels.
formatters	Partial<RailFormatters>	—	Override individual label formatters.
initialPastDays	number	30	Days rendered before today on init.
initialFutureDays	number	30	Days rendered after today on init.
loadMoreDays	number	14	Days appended per infinite-scroll load.
minDate / maxDate	Date	—	Clamp the scrollable/selectable range.
disabledDate	(date: Date) => boolean	—	Disable individual dates.
autoScroll	boolean	true	Auto-center the selected cell when modelValue changes.
showMonth	boolean	true	Show the month line in each cell (e.g. "Jul").
showWeekday	boolean	true	Show the weekday line in each cell (e.g. "Tue").
ariaLabel	string	'Select date'	Accessible label for the rail.
unstyled	boolean	false	Skip default visual styles (structure only) for utility-CSS styling.
cellClass	string | (ctx) => string	—	Extra classes per cell; the function receives { date, selected, today, disabled }.

Events

Event	Payload
update:modelValue	Date	v-model update (local midnight)
change	Date	Fired alongside update:modelValue

Slots

Slot	Props	Description
cell	{ date, selected, today, disabled }	Replace the entire cell content.
marker	{ date }	Rendered under the day number — event dots, badges.

Exposed methods

Method	Description
scrollToSelected(behavior?)	Center the selected cell.
scrollToToday()	Select today (emits update:modelValue) and center it.
reset()	Regenerate the range around the current modelValue.

<MonthRail>

<MonthRail
  v-model="month"
  locale="ko"
  :past-months="12"
  :future-months="12"
/>

modelValue is always emitted normalized to the first of the month. If modelValue falls outside the pastMonths/futureMonths window, the range extends automatically. Slot item ({ month, selected, current }) replaces the pill content.

Headless: useDateRail()

All the infinite-scroll mechanics without the default markup:

<script setup lang="ts">
import { onMounted } from 'vue';
import { useDateRail, dateKey } from '@devslab/vue-date-rail';

const { containerRef, dates, handleScroll, initialize } =
  useDateRail({ initialPastDays: 14, loadMoreDays: 7 });

onMounted(() => initialize());
</script>

<template>
  <div
    ref="containerRef"
    style="display: flex; overflow-x: auto"
    @scroll.passive="handleScroll"
  >
    <button v-for="d in dates" :key="dateKey(d)" :data-vdr-key="dateKey(d)">
      {{ d.getDate() }}
    </button>
  </div>
</template>

Cells must carry data-vdr-key="YYYY-MM-DD" (use the exported dateKey) for scrollToDate to find them.

Theming

Override CSS custom properties on any ancestor (all have built-in fallbacks):

.my-app {
  --vdr-accent: #4f82b5; /* selected / today / focus */
  --vdr-accent-hover: #416d99;
  --vdr-cell-bg: #f4f5f7;
  --vdr-cell-hover-bg: #e8eaee;
  --vdr-text: #1f2937;
  --vdr-text-selected: #ffffff;
  --vdr-today-bg: #eef4fa;
  --vdr-radius: 12px;
  --vdr-gap: 8px;
  --vdr-cell-min-width: 56px;
  --vdr-fs-day: 1.25rem;
  --vdr-month-border: #d6d9de; /* MonthRail pill */
}

Dark mode is just another set of overrides — see demo/App.vue.

Tailwind CSS (and friends)

Every cell exposes data-selected / data-today / data-disabled attributes, so you can style states with Tailwind's data-* variants. Combine with unstyled to drop the default look entirely:

<DateRail
  v-model="date"
  unstyled
  cell-class="flex flex-col items-center min-w-14 rounded-xl px-2 py-2
    bg-gray-100 hover:bg-gray-200
    data-selected:bg-blue-600 data-selected:text-white
    data-today:ring-2 data-today:ring-blue-400
    data-disabled:opacity-30"
/>

Or compute classes per state with a function: :cell-class="({ selected }) => selected ? '...' : '...'". <MonthRail> offers the same via unstyled + item-class and data-selected / data-current. This works the same way with UnoCSS or any attribute-variant utility framework.

Family

• vue-month-spinner-picker — iOS-style drum-roll month picker (bottom sheet), the modal sibling of <MonthRail>
• More open source from devslab

License

Apache-2.0