@archpublicwebsite/rangepicker

Custom, lightweight date range picker component for Vue 3 with Tailwind CSS prefix support.

Features

- 🎨 Vue 3 Composition API - Built with modern Vue 3 and TypeScript
- 📦 CSS Prefix Support - All Tailwind classes prefixed with arch- to prevent conflicts with Vuetify/Bootstrap
- 📅 Dayjs Integration - Powerful date manipulation without moment.js bloat
- 🎨 Themeable - Easy color customization via props (HEX colors)
- 📱 Mobile Responsive - Touch-friendly with bottom sheet on mobile
- 🎯 Smart Positioning - Auto-adjusts based on available viewport space
- ♿ Accessible - Keyboard navigation and screen reader support
- 🚀 SSR Compatible - Works perfectly with Nuxt 3
- 🪶 Lightweight - ~49KB CSS (gzipped: 5.3KB), ~40KB JS (gzipped: 9.4KB)

Installation

``bash
npm install @archpublicwebsite/rangepicker


or

pnpm add @archpublicwebsite/rangepicker

or

yarn add @archpublicwebsite/rangepicker
`

Quick Start

Important: You must import both the component AND the CSS file.

`vue



`

$3

Full TypeScript support with exported types for type-safe development:

`vue



`

Why separate CSS import?
- Better performance (CSS cached independently)
- Smaller JS bundle
- No Flash of Unstyled Content (FOUC)
- Industry standard (like Vuetify, Element Plus, etc.)

Tailwind CSS Prefix:
All Tailwind utility classes are prefixed with arch- to prevent conflicts with other CSS frameworks like Vuetify or Bootstrap. Your existing styles won't be affected!

Color Customization

Customize colors easily by passing HEX color values as props. Each rangepicker instance can have its own color scheme:

`vue



`

$3

Use custom fonts to match your brand typography:

`vue



`

$3

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| primary-color | string | - | Main color for selected dates and buttons (HEX format, e.g., #3b82f6) |
| secondary-color | string | - | Color for hover states and secondary elements (HEX format, optional) |
| font-family | string | inherit | Custom font family (e.g., 'Roboto', sans-serif, 'Poppins', sans-serif) |

Features:
- ✅ Scoped per instance - Multiple pickers can have different colors simultaneously
- ✅ No global state - Colors don't conflict between instances
- ✅ HEX format - Standard 3 or 6 digit HEX colors (e.g., #3b82f6, #fff)
- ✅ Auto-conversion - Automatically converts HEX to RGB for CSS variables
- ✅ Optional - Falls back to default theme if not provided
- ✅ Custom fonts - Use any font family, inherits from parent by default

Framework Compatibility

This package is designed to work seamlessly with any Vue 3 framework:

- ✅ Vuetify - No CSS conflicts thanks to arch- prefix
- ✅ Bootstrap - Works alongside Bootstrap utilities
- ✅ Element Plus - Fully compatible
- ✅ Quasar - No issues
- ✅ Plain Vue 3 - Works great standalone
- ✅ Nuxt 3 - SSR compatible

The arch- prefix on all Tailwind classes ensures zero conflicts with other CSS frameworks.

Usage

$3

`vue



`

$3

`vue



`

$3

`vue



`


Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| modelValue | { startDate?: string \| Date \| Dayjs, endDate?: string \| Date \| Dayjs } | {} | Selected date range |
| isOpen | boolean | false | Controls picker visibility |
| variant | 'desktop' \| 'mobile' | 'desktop' | Display variant |
| primaryColor | string | - | Primary color in HEX format (e.g., #3b82f6) |
| secondaryColor | string | - | Secondary color in HEX format (e.g., #60a5fa) |
| minDate | string \| Date \| Dayjs | - | Minimum selectable date |
| maxDate | string \| Date \| Dayjs | - | Maximum selectable date |
| minDays | number | - | Minimum number of days in range |
| maxDays | number | - | Maximum number of days in range |
| valueOfMonths | number | 2 | Number of months to display |
| valueOfColumns | number | 2 | Grid columns for months |
| disabledDates | (string \| Date)[] | [] | Array of disabled dates |
| holidays | (string \| Date)[] | [] | Array of holiday dates |
| format | string | 'YYYY-MM-DD' | Date format |
| delimiter | string | ' - ' | Delimiter between dates |
| placeholder | string | 'Select dates' | Placeholder text |
| label | string | - | Label for the picker |
| showTooltip | boolean | true | Show night count tooltip |
| autoApply | boolean | false | Auto-apply selection |
| position | 'auto' \| 'top' \| 'bottom' | 'auto' | Positioning strategy |
| triggerElement | HTMLElement \| null | - | Trigger element for positioning |

Events

| Event | Payload | Description |
|-------|---------|-------------|
| update:modelValue | { startDate: string, endDate: string } | Emitted when date range changes |
| update:isOpen | boolean | Emitted when picker opens/closes |
| dateSelected | Dayjs | Emitted when a date is clicked |
| rangeSelected | { start: Dayjs, end: Dayjs } | Emitted when range is complete |

TypeScript Support

This package is built with TypeScript and provides full type definitions. All types are automatically exported for your convenience.

$3

`typescript
import type {
RangepickerProps, // Component props interface
RangepickerEmits, // Event emitter interface
DateRange, // Date range object type
CalendarDay, // Internal calendar day type
CalendarMonth // Internal calendar month type
} from '@archpublicwebsite/rangepicker'
`

$3

#### RangepickerProps
Complete props interface with JSDoc documentation. All props are optional with sensible defaults:

`typescript
interface RangepickerProps {
modelValue?: { startDate?: string | Date | Dayjs; endDate?: string | Date | Dayjs }
isOpen?: boolean
variant?: 'desktop' | 'mobile'
minDate?: string | Date | Dayjs
maxDate?: string | Date | Dayjs
minDays?: number
maxDays?: number
close?: boolean
valueOfMonths?: number // default: 2
valueOfColumns?: number // default: 2
disabledDates?: (string | Date)[]
holidays?: (string | Date)[]
format?: string // default: 'YYYY-MM-DD'
delimiter?: string // default: ' - '
placeholder?: string
label?: string
showTooltip?: boolean // default: true
autoApply?: boolean // default: false
position?: 'auto' | 'top' | 'bottom'
triggerElement?: HTMLElement | null
colorStyles?: Record
}
`

#### DateRange
Type for the v-model binding:

`typescript
interface DateRange {
startDate: string
endDate: string
}
`

#### RangepickerEmits
Event emitter types for type-safe event handling:

`typescript
interface RangepickerEmits {
'update:modelValue': [value: { startDate: string; endDate: string }]
'update:isOpen': [value: boolean]
'dateSelected': [date: Dayjs]
'rangeSelected': [start: Dayjs, end: Dayjs]
}
`

$3

#### Type-Safe Component Props

`typescript
import type { RangepickerProps } from '@archpublicwebsite/rangepicker'

// Define props with autocomplete support
const config: Partial = {
format: 'DD/MM/YYYY',
minDays: 2,
maxDays: 30,
autoApply: true,
showTooltip: true
}
`

#### Type-Safe Event Handlers

`typescript
import type { Dayjs } from 'dayjs'

function handleDateSelected(date: Dayjs) {
console.log('Selected:', date.format('YYYY-MM-DD'))
}

function handleRangeSelected(start: Dayjs, end: Dayjs) {
const nights = end.diff(start, 'day')
console.log(Booking: ${nights} nights)
}
`

#### Type-Safe Refs

`typescript
import { ref } from 'vue'
import type { DateRange } from '@archpublicwebsite/rangepicker'

const dateRange = ref({ startDate: '', endDate: '' })
const holidays = ref(['2025-12-25', '2025-01-01'])
const disabledDates = ref([new Date('2025-12-24')])
`

$3

With the exported types, you'll get:

- ✅ Autocomplete - IntelliSense for all props and events
- ✅ Type Checking - Compile-time error detection
- ✅ Documentation - Hover tooltips with prop descriptions and default values
- ✅ Refactoring - Safe rename and refactor operations
- ✅ Error Prevention - Catch typos and incorrect prop usage before runtime

Development

`bash


Install dependencies

pnpm install

Start dev server with demo

pnpm dev

Build package

pnpm build

Type check

pnpm type-check

Preview build

pnpm preview
`

CSS Architecture

The component uses Tailwind CSS with arch- prefix to prevent conflicts with other frameworks:

$3


- ✅ Zero conflicts with Vuetify, Bootstrap, Element Plus, etc.
- ✅ Safe to use alongside any CSS framework
- ✅ All utilities prefixed: .arch-flex, .arch-text-sm, .arch-bg-white, etc.
- ✅ Custom classes untouched: .rangepicker-* classes remain unprefixed

$3

1. Color Props (Easiest):
`vue
primary-color="#3b82f6"
secondary-color="#60a5fa"
/>
`

2. CSS Variables (Global):
`css
:root {
--color-primary: 59 130 246; / RGB format /
--color-secondary: 148 163 184;
}
`

3. Custom CSS Overrides:
`css
/ Override component styles /
.rangepicker-day-selected {
background-color: purple !important;
}
`

Troubleshooting

$3


Make sure you imported the CSS:
`js
import '@archpublicwebsite/rangepicker/style.css'
`

$3

This should NOT happen thanks to the arch- prefix. If you see conflicts, please open an issue.

$3

Ensure vue` is installed as a dependency in your project.

Browser Support

- Chrome/Edge (latest 2 versions)
- Firefox (latest 2 versions)
- Safari (latest 2 versions)
- Mobile Safari (iOS 14+)
- Chrome for Android (latest)

Contributing

See the main repository README for contribution guidelines.

License

MIT © Archipelago International