@heliomarpm/ion-calendar
TypeScript icon, indicating that this package has built-in type declarations

7.16.4 • Public • Published

screenshot screenshot2

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' | 'moment' | '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' | 'moment' | '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.

paypal url kofi url liberapay url github sponsors url

License

MIT © Heliomar P. Marques 🔝


Package Sidebar

Install

npm i @heliomarpm/ion-calendar

Weekly Downloads

19

Version

7.16.4

License

MIT

Unpacked Size

662 kB

Total Files

52

Last publish

Collaborators

  • heliomarpm