README.md

📅 Ionic Component IonCalendar

live demo: click here

Summary

The @heliomarpm/ion-calendar is a calendar component for Ionic Framework-based applications.
It uses Luxon to handle dates and times, so it's fully compatible with International Organization for Standardization (ISO) 8601 formats.

The main features are:

• Fully customizable layout;
• Customizable date format;
• Multiple selection mode;
• Range selection mode;
• Calendar can be placed in content area or as an overlay;
• Theming using SCSS variables.
• Disable weekdays or weekends.
• Setting days event.
• Setting localization.
• Material design from Ionic Framework.
• Adapted for Ionic dark theme

Support

• @angular/core ^16.+"
• @ionic/angular ^6.+"

Installation

You can install the library using npm or yarn:

npm i @heliomarpm/ion-calendar 
# or 
yarn add @heliomarpm/ion-calendar 

Example Usage

Import module

import { NgModule } from '@angular/core';
import { IonicApp, IonicModule } from '@ionic/angular';
...
import { AppComponent } from './app.component';
import { IonCalendarModule } from '@heliomarpm/ion-calendar';

@NgModule({
  declarations: [AppComponent],
  imports: [
    ...,
    IonicModule.forRoot(),
    IonCalendarModule
  ],
  ...
})
export class AppModule {}

Change Defaults

import { NgModule } from '@angular/core';
import { IonicApp, IonicModule } from '@ionic/angular';
...
import { AppComponent } from './app.component';
import { IonCalendarModule } from '@heliomarpm/ion-calendar';

@NgModule({
  declarations: [AppComponent],
  imports: [
    ...,
    IonicModule.forRoot(),
    // See ICalendarComponentOptions for options
    IonCalendarModule.forRoot({
      doneLabel: 'Confirm',
      closeIcon: true
    })
  ],
  ...
})
export class AppModule {}

Components Mode

Basic

<ion-calendar [(ngModel)]="date"
              (onChange)="onChange($event)"
              [type]="type"
              format="yyyy-MM-dd">
</ion-calendar>

import { Component } from '@angular/core';

@Component({
  selector: 'page-home',
  templateUrl: 'home.html'
})
export class HomePage {
  date: string;
  type: 'string'; // 'string' | 'js-date' | 'luxon' | 'time' | 'object'
  constructor() { }

  onChange($event) {
    console.log($event);
  }
  ...
}

Date range

<ion-calendar [(ngModel)]="dateRange"
              [options]="optionsRange"
              [type]="type"
              [format]="'yyyy-MM-dd'">
</ion-calendar>

import { Component } from '@angular/core';
import { ICalendarComponentOptions } from '@heliomarpm/ion-calendar';

@Component({
  selector: 'page-home',
  templateUrl: 'home.html'
})
export class HomePage {
  dateRange: { from: string; to: string; };
  type: 'string'; // 'string' | 'js-date' | 'luxon' | 'time' | 'object'
  optionsRange: ICalendarComponentOptions = {
    pickMode: 'range'
  };

  constructor() { }
  ...
}

Multi Date

<ion-calendar [(ngModel)]="dateMulti"
              [options]="optionsMulti"
              [type]="type"
              format="yyyy-MM-dd">
</ion-calendar>

import { Component } from '@angular/core';
import { ICalendarComponentOptions } from '@heliomarpm/ion-calendar';

@Component({
  selector: 'page-home',
  templateUrl: 'home.html'
})
export class HomePage {
  dateMulti: string[];
  type: 'string'; // 'string' | 'js-date' | 'luxon' | 'time' | 'object'
  optionsMulti: ICalendarComponentOptions = {
    pickMode: 'multi'
  };

  constructor() { }
  ...
}

Input Properties

Name	Type	Default	Description
options	ICalendarComponentOptions	null	options
format	string	'yyyy-MM-dd'	value format
type	string	'string'	value type
readonly	boolean	false	readonly

Output Events

Name	Type	Description
onChange	EventEmitter	event for model change
onMonthChange	EventEmitter	event for month change when displayMode = month
onWeekChange	EventEmitter	event for month change when displayMode = week
onSelect	EventEmitter	event for click day-button
onSelectStart	EventEmitter	event for click day-button
onSelectEnd	EventEmitter	event for click day-button

ICalendarComponentOptions

Name	Type	Default	Description
from	Date	new Date()	start date
to	Date	0 (Infinite)	end date
color	string	'primary'	'primary', 'secondary','tertiary', 'success', 'warning', 'danger', 'dark', 'medium', 'light', 'custom', 'transparent'
colorSubtitle	string	undefined	'primary', 'secondary','tertiary', 'success', 'warning', 'danger', 'dark', 'medium', 'light', 'custom', 'transparent'
pickMode	string	single	'multi', 'range', 'single'
showToggleButtons	boolean	true	show toggle buttons
monthsTitle	Array	['JAN', 'FEB', ..., 'NOV', 'DEC']	month picker format
showMonthPicker	boolean	true	show month picker
showYearPicker	boolean	true	show year picker
defaultTitle	string	''	default title in days
defaultSubtitle	string	''	default subtitle in days
disableWeeks	Array	[]	week to be disabled (0-6)
monthFormat	string	'MMM yyyy'	month title format
weekdays	Array	['S', 'M', 'T', 'W', 'T', 'F', 'S']	weeks text
weekStart	number	0	set week start day 0 of sundaty, 1 of monday
IDayConfig	Array<IDayConfig>	[]	days configuration
displayMode	string	month	'month', 'week'
showAdjacentMonthDay	boolean	true	show days of adjacent months when displayMode: 'month'
showMonthAdjacentDays	boolean	false	show the month on days adjacent to the selected month when displayMode: 'week'
weeks	number	1	number of week to show in week display mode
locale	ICalendarLocale	{locale: 'en', weekdays: 'initial' }	change calendar locale and set default name to weeks

Modal Mode

Basic

Import ion2-calendar in component controller.

import { Component } from '@angular/core';
import { ModalController } from '@ionic/angular';
import { CalendarModalComponent, ICalendarModalOptions, IDayConfig, ICalendarResult } from '@heliomarpm/ion-calendar';

@Component({
  selector: 'page-home',
  templateUrl: 'home.html'
})
export class HomePage {
  constructor(public modalCtrl: ModalController) {}

  openCalendar() {
    const options: ICalendarModalOptions = {
      title: 'BASIC'
    };

    const myCalendar = await this.modalCtrl.create({
      component: CalendarModalComponent,
      componentProps: { options }
    });

    myCalendar.present();

    const event: any = await myCalendar.onDidDismiss();
    const date: ICalendarResult = event.data;
    if (event.role === 'done') {
      console.log('date:', date); // date selected
    }
  }
}

Date range

Set pickMode to 'range'.

openCalendar() {
  const options: ICalendarModalOptions = {
    pickMode: 'range',
    title: 'RANGE'
  };

  const myCalendar = await this.modalCtrl.create({
    component: CalendarModal,
    componentProps: { options }
  });

  myCalendar.present();

  const event: any = await myCalendar.onDidDismiss();
  const date = event.data;
  const from: ICalendarResult = date.from;
  const to: ICalendarResult = date.to;

  console.log(date, from, to);
}

Multi Date

Set pickMode to 'multi'.

openCalendar() {
  const options = {
    pickMode: 'multi',
    title: 'MULTI'
  };

  const myCalendar = await this.modalCtrl.create({
    component: CalendarModal,
    componentProps: { options }
  });

  myCalendar.present();

  const event: any = await myCalendar.onDidDismiss();
  const date: ICalendarResult = event.data;
  console.log(date);
}

Disable weeks

Use index eg: [0, 6] denote Sunday and Saturday.

openCalendar() {
  const options: ICalendarModalOptions = {
    disableWeeks: [0, 6]
  };

  const myCalendar = await this.modalCtrl.create({
    component: CalendarModal,
    componentProps: { options }
  });

  myCalendar.present();

  const event: any = await myCalendar.onDidDismiss();
  const date: ICalendarResult = event.data;
  console.log(date);
}

Localization

openCalendar() {
  const options: ICalendarModalOptions = {
    locale: { locale: 'zn-CN', weekdays:'short' },
    weekStart: 1,
    monthFormat: 'yyyy 年 MM 月',
    defaultDate: new Date()
  };

  const myCalendar = await this.modalCtrl.create({
    component: CalendarModal,
    componentProps: { options }
  });

  myCalendar.present();

  const event: any = await myCalendar.onDidDismiss();
  const date: ICalendarResult = event.data;
  console.log(date);
}

Days Config

Configure one day.

openCalendar() {
  let holidays: IDayConfig[] = [];
  
  holidays.push({date: new Date(2023, 0, 1), title: '🎉', subTitle: 'New Year'});
  holidays.push({date: new Date(2023, 4, 1), subTitle: 'Labor Day', disable: true});
  holidays.push({date: new Date(2023, 11, 25), subTitle: '🎅', disable: true});

  const options: ICalendarModalOptions = {
    from: new Date(2023, 0, 1),
    to: new Date(2023, 11, 31),
    defaultDate: new Date(),
    efaultScrollTo: new Date(),
    IDayConfig: holidays,
    color: 'success'
  };

  const myCalendar = await this.modalCtrl.create({
    component: CalendarModal,
    componentProps: { options }
  });

  myCalendar.present();

  const event: any = await myCalendar.onDidDismiss();
  const date: ICalendarResult = event.data;
  console.log(date);
}

API

Modal Options

Name	Type	Default	Description
from	Date	new Date()	start date
to	Date	undefined	end date
title	string	'CALENDAR'	title
color	string	'primary'	'primary', 'secondary', 'danger', 'light', 'dark'
defaultScrollTo	Date	from	let the view scroll to the default date
defaultDate	Date	null	default date data, apply to single
defaultDates	Array	null	default dates data, apply to multi
defaultDateRange	{ from: Date, to: Date }	null	default date-range data, apply to range
defaultTitle	string	''	default title in days
defaultSubtitle	string	''	default subtitle in days
cssClass	string	''	Additional classes for custom styles, separated by spaces.
canBackwardsSelected	boolean	false	can backwards selected
pickMode	string	single	'multi', 'range', 'single'
disableWeeks	Array	[]	week to be disabled (0-6)
closeLabel	string	CANCEL	cancel button label
doneLabel	string	DONE	done button label
clearLabel	string	null	clear button label
closeIcon	boolean	false	show cancel button icon
doneIcon	boolean	false	show done button icon
monthFormat	string	'MMM yyyy'	month title format
weekdays	Array	['S', 'M', 'T', 'W', 'T', 'F', 'S']	weeks text
weekStart	number	0 (0 or 1)	set week start day
weeks	number	1	number of weeks will be displayed when displayMode: week
IDayConfig	Array<IDayConfig>	[]	days configuration
step	number	12	month load stepping interval to when scroll
autoDone	boolean	false	done automatically when selecting date
showAdjacentMonthDay	boolean	true	show days of adjacent months

onDidDismiss Output { data } = event

pickMode	Type
single	{ date: ICalendarResult }
range	{ from: ICalendarResult, to: ICalendarResult }
multi	Array<ICalendarResult>

onDidDismiss Output { role } = event

Value	Description
'cancel'	dismissed by click the cancel
'done'	dismissed by click the done button
'backdrop'	dismissed by click the backdrop

IDayConfig

Name	Type	Default	Description
cssClass	string	''	separated by spaces
date	Date	required	configured days
marked	boolean	false	highlight color
disable	boolean	false	disable
title	string	none	displayed title eg: 'today'
subTitle	string	none	subTitle subTitle eg: `'New Year's

ICalendarResult

Name	Type
time	number
secondas	number
dateObj	Date
string	string
year	number
month	number
day	number

Dependencies

• @angular/core: Angular - the core framework
• @ionic/angular: Ionic Angular specific building blocks on top of @ionic/core components.
• luxon: Luxon is a library for working with dates and times in JavaScript.

Contributing

Please make sure to read the Contributing Guide before making a pull request.

Thank you to all the people who already contributed to project!

Made with contrib.rocks.

That said, there's a bunch of ways you can contribute to this project, like by:

• 🪲 Reporting a bug
• 📄 Improving this documentation
• 🚨 Sharing this project and recommending it to your friends
• 💵 Supporting this project on GitHub Sponsors or Ko-fi
• 🌟 Giving a star on this repository

Donate

If you appreciate that, please consider donating to the Developer.

License

MIT © Heliomar P. Marques 🔝

---