Skip to Content
✨ Just dropped my UI Library — still cooking up some magic! Stay tuned & maybe… hire me  or sponsor me 😉 
DocumentationDatePicker

DatePicker

A comprehensive date picker component with advanced features including time selection, smart positioning, and business calendar functionality. Designed for modern applications with portal rendering and intelligent date handling.

Install Dependencies

npx
quickcode-ui add DatePicker

Default Usage

The DatePicker provides a clean interface for date selection with intuitive month/year navigation and automatic positioning to prevent viewport overflow.

Default DatePicker

Date & Time Selection

Enable time selection for scheduling applications with integrated hour/minute inputs and AM/PM toggle functionality.

Date & Time Selection

Business Calendar Features

Advanced calendar functionality with holiday detection, special event highlighting, weekend restrictions, and business logic enforcement.

Business Calendar

Holidays (New Year, Independence Day, Christmas)
Product Launch (Sep 15)
Quarterly Review (Oct 31)
• Weekends disabled • Holidays disabled • Past Date disabled

Component Architecture

The DatePicker utilizes portal rendering to ensure the calendar overlay never gets clipped by parent containers with overflow restrictions. The component automatically calculates optimal positioning based on available viewport space, switching between top and bottom placement as needed.

Props

PropTypeDefaultDescription
valueDate | nullnullControlled date value
defaultValueDateundefinedDefault date for uncontrolled usage
onChange(date: Date | null) => voidundefinedCallback when date selection changes
disabledbooleanfalseDisables the entire date picker
placeholderstring"Select date"Placeholder text for empty state
includeTimebooleanfalseEnables time selection with hour/minute inputs
minDateDateundefinedEarliest selectable date
maxDateDateundefinedLatest selectable date
holidaysArray<{year: number, month: number, day: number}>[]Holiday dates to highlight and optionally disable
specialDaysArray<{date: DateObj, className?: string, label?: string, disabled?: boolean}>[]Custom highlighted dates with styling
disabledDatesArray<{year: number, month: number, day: number}>[]Specific dates to disable
disableWeekendsbooleanfalseDisables Saturday and Sunday selection
disableHolidaysbooleanfalseMakes holiday dates non-selectable
showLegendbooleantrueShows color legend for holidays and special events
classNamestringundefinedAdditional classes for the root container
triggerClassNamestringundefinedAdditional classes for the input trigger
contentClassNamestringundefinedAdditional classes for the calendar popup
format(date: Date) => stringAuto formatCustom date formatting function

Advanced Features

Smart Positioning System

The DatePicker uses an intelligent positioning algorithm that prevents the calendar from being cut off by viewport boundaries. It automatically switches between top and bottom placement based on available space and handles scroll events to maintain proper positioning.

Holiday and Event Management

Define holidays and special events with custom styling and tooltips. The component supports business logic like disabling weekends and holidays while providing visual indicators for important dates.

Time Integration

When time selection is enabled, the component seamlessly integrates hour/minute inputs with proper validation and 12-hour format conversion. Time changes are immediately reflected in the selected date value.

Accessibility Standards

The DatePicker implements comprehensive keyboard navigation, screen reader support, and proper ARIA labeling. All interactive elements are focusable and provide appropriate feedback for assistive technologies.

Technical Implementation

Built with React 18+ and TypeScript for type safety. Utilizes Framer Motion for smooth animations and portal rendering for reliable positioning. The component follows modern React patterns with proper state management and event handling.

Perfect for applications requiring sophisticated date selection with business rules, scheduling interfaces, or any scenario where standard HTML date inputs are insufficient.

Last updated on