NgxDatex - Advanced Angular Date Range Picker

A feature-rich, accessible date picker component for Angular applications. Built with modern Angular patterns including signals, standalone components, and CDK overlays.

✨ Features

• 📅 Single Date & Date Range Selection - Support for both single dates and date ranges
• ⏰ Time Picker Integration - Optional time selection with 12/24 hour formats
• 🎨 Customizable Themes - Built-in themes with full customization support
• 🌍 Internationalization - Complete i18n support with multiple locales
• � Mobile Responsive - Optimized for mobile devices with touch support
• ♿ Accessibility - WCAG compliant with full keyboard navigation
• 🔧 Extensive Configuration - Highly configurable with sensible defaults
• � Forms Integration - Full Angular Forms support with ControlValueAccessor
• 🚀 Performance Optimized - Built with Angular signals for optimal performance
• 🎯 TypeScript First - Written in TypeScript with comprehensive type definitions

🚀 Installation

npm install ngx-datex

� Quick Start

1. Import the Component

import { NgxDatex } from 'ngx-datex';

@Component({
  selector: 'app-example',
  imports: [NgxDatex], // For standalone components
  template: ` <ngx-datex [(ngModel)]="selectedRange" [ranges]="predefinedRanges"> </ngx-datex> `,
})
export class ExampleComponent {
  selectedRange: NgxDatexValue | null = null;

  predefinedRanges = {
    Today: [startOfDay(new Date()), endOfDay(new Date())],
    'Last 7 Days': [startOfDay(subDays(new Date(), 6)), endOfDay(new Date())],
    'Last 30 Days': [startOfDay(subDays(new Date(), 29)), endOfDay(new Date())],
  };
}

2. Basic Usage

<!-- Simple date range picker -->
<ngx-datex [(ngModel)]="dateRange" placeholder="Select date range"> </ngx-datex>

<!-- Single date picker -->
<ngx-datex [(ngModel)]="singleDate" [singleDatePicker]="true" placeholder="Select date">
</ngx-datex>

🎛️ Configuration Options

Input Properties

| Property | Type | Default | Description | | ------------------ | ------------------------------ | ---------------------- | ------------------------------------------- | | singleDatePicker | boolean | false | Enable single date selection mode | | timePicker | boolean | false | Enable time selection | | timePicker24Hour | boolean | true | Use 24-hour format for time picker | | autoApply | boolean | false | Auto-apply selection without confirm button | | showDropdowns | boolean | false | Show month/year dropdowns in header | | linkedCalendars | boolean | true | Link left and right calendar navigation | | ranges | Record<string, [Date, Date]> | DEFAULT_RANGES | Predefined date ranges | | minDate | Date \| null | null | Minimum selectable date | | maxDate | Date \| null | null | Maximum selectable date | | locale | NgxDatexLocale | SPANISH_LOCALE | Localization settings | | theme | NgxDatexTheme | MATERIAL_LIGHT_THEME | Theme configuration |

Output Events

| Event | Type | Description | | ------------- | ------------------------------------------ | ----------------------------------- | | dateChange | NgxDatexValue \| null | Emitted when date selection changes | | rangeChange | {startDate: Date, endDate: Date \| null} | Emitted when range changes | | openEvent | void | Emitted when picker opens | | closeEvent | void | Emitted when picker closes |

🎨 Theming

Using Built-in Themes

import { MATERIAL_LIGHT_THEME } from 'ngx-datex';

@Component({
  template: ` <ngx-datex [theme]="materialTheme"></ngx-datex> `,
})
export class ThemedComponent {
  materialTheme = MATERIAL_LIGHT_THEME;
}

Creating Custom Themes

import { NgxDatexTheme } from 'ngx-datex';

const customTheme: NgxDatexTheme = {
  name: 'custom-dark',
  colors: {
    primary: '#bb86fc',
    secondary: '#03dac6',
    background: '#121212',
    surface: '#1e1e1e',
    text: '#ffffff',
    // ... other colors
  },
  typography: {
    fontFamily: 'Roboto, sans-serif',
    fontSize: '14px',
    fontWeight: '400',
    lineHeight: '1.5',
  },
  // ... other theme properties
};

🌍 Internationalization

Using Built-in Locales

import { SPANISH_LOCALE } from 'ngx-datex';

@Component({
  template: ` <ngx-datex [locale]="spanishLocale"></ngx-datex> `,
})
export class LocalizedComponent {
  spanishLocale = SPANISH_LOCALE;
}

Creating Custom Locales

import { NgxDatexLocale } from 'ngx-datex';

const frenchLocale: NgxDatexLocale = {
  direction: 'ltr',
  format: 'DD/MM/YYYY',
  separator: ' - ',
  applyLabel: 'Appliquer',
  cancelLabel: 'Annuler',
  daysOfWeek: ['Lu', 'Ma', 'Me', 'Je', 'Ve', 'Sa', 'Di'],
  monthNames: [
    'Janvier',
    'Février',
    'Mars',
    'Avril',
    'Mai',
    'Juin',
    'Juillet',
    'Août',
    'Septembre',
    'Octobre',
    'Novembre',
    'Décembre',
  ],
  firstDay: 1,
};

📱 Mobile Support

The component automatically adapts to mobile devices with:

• Touch-friendly interface
• Optimized layout for small screens
• Native-like date selection experience
• Responsive design patterns

♿ Accessibility

NgxDatex is built with accessibility in mind:

• Full keyboard navigation support
• ARIA labels and descriptions
• Screen reader compatibility
• High contrast support
• Focus management

🔧 Advanced Usage

With Reactive Forms

import { FormControl, ReactiveFormsModule } from '@angular/forms';

@Component({
  imports: [ReactiveFormsModule, NgxDatex],
  template: `
    <form [formGroup]="form">
      <ngx-datex formControlName="dateRange"></ngx-datex>
    </form>
  `,
})
export class ReactiveFormComponent {
  form = this.fb.group({
    dateRange: new FormControl<NgxDatexValue | null>(null),
  });
}

Custom Date Validation

@Component({
  template: `
    <ngx-datex [isInvalidDate]="isWeekend" [minDate]="minDate" [maxDate]="maxDate"> </ngx-datex>
  `,
})
export class ValidatedComponent {
  minDate = new Date();
  maxDate = addMonths(new Date(), 6);

  isWeekend = (date: Date): boolean => {
    const day = date.getDay();
    return day === 0 || day === 6; // Disable weekends
  };
}

Time Picker Configuration

@Component({
  template: `
    <ngx-datex
      [timePicker]="true"
      [timePicker24Hour]="false"
      [timePickerIncrement]="15"
      [timePickerSeconds]="false"
    >
    </ngx-datex>
  `,
})
export class TimePickerComponent {}

📚 API Reference

Types

NgxDatexValue

interface NgxDatexValue {
  startDate: Date;
  endDate: Date | null;
  label?: string;
}

NgxDatexLocale

interface NgxDatexLocale {
  direction?: 'ltr' | 'rtl';
  format?: string;
  separator?: string;
  applyLabel?: string;
  cancelLabel?: string;
  daysOfWeek?: string[];
  monthNames?: string[];
  firstDay?: number;
}

NgxDatexTheme

interface NgxDatexTheme {
  name: string;
  colors: {
    /* color definitions */
  };
  typography: {
    /* typography settings */
  };
  spacing: {
    /* spacing scale */
  };
  borderRadius: {
    /* border radius values */
  };
  shadows: {
    /* shadow definitions */
  };
}

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by the popular daterangepicker library
• Built with Angular CDK for overlay management
• Uses @formkit/tempo for reliable date operations

📞 Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions