{"id":13728721,"url":"https://github.com/cswarb/ngx-aircal","last_synced_at":"2025-05-08T00:32:21.513Z","repository":{"id":33535676,"uuid":"151642083","full_name":"cswarb/ngx-aircal","owner":"cswarb","description":"ngx-aircal is a modern, configurable and lightweight Angular date range picker.","archived":false,"fork":false,"pushed_at":"2023-03-02T16:51:03.000Z","size":2482,"stargazers_count":7,"open_issues_count":21,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-07-08T23:03:33.727Z","etag":null,"topics":["angular","calendar","component","date","daterange","daterangepicker","ngx-aircal","plugin"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cswarb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-10-04T22:10:22.000Z","updated_at":"2022-02-18T23:48:31.000Z","dependencies_parsed_at":"2023-02-15T08:15:53.483Z","dependency_job_id":null,"html_url":"https://github.com/cswarb/ngx-aircal","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cswarb%2Fngx-aircal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cswarb%2Fngx-aircal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cswarb%2Fngx-aircal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cswarb%2Fngx-aircal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cswarb","download_url":"https://codeload.github.com/cswarb/ngx-aircal/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":213757088,"owners_count":15634118,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["angular","calendar","component","date","daterange","daterangepicker","ngx-aircal","plugin"],"created_at":"2024-08-03T02:00:48.908Z","updated_at":"2024-08-03T02:02:26.523Z","avatar_url":"https://github.com/cswarb.png","language":"TypeScript","funding_links":[],"categories":["UI Components"],"sub_categories":["Form"],"readme":"# ngx-aircal\n\n![version](https://img.shields.io/npm/v/ngx-aircal.svg?colorB=00a699)\n![license](https://img.shields.io/github/license/cswarb/ngx-aircal.svg?colorB=00a699)\n![weight](https://img.shields.io/bundlephobia/minzip/ngx-aircal.svg?colorB=00a699)\n![build](https://img.shields.io/travis/cswarb/ngx-aircal.svg?colorB=00a699)\n\n![Aircal](/projects/ngx-aircal/aircal.png?raw=true \"Aircal\")\n\n## Description\nngx-aircal is a modern, configurable and lightweight Angular date range picker.\n\n## Notes\n\n- When setting the dateFormat option, be aware that you must use [Unicode tokens](https://date-fns.org/v2.0.0-alpha.27/docs/Unicode-Tokens)\n\n## How do I install the library?\n\nTo install this component to an external project, follow the procedure:\n\n```\nnpm install ngx-aircal --save\n```\n\n## How do I import the calendar?\nAdd 'NgxAircalModule' module to your imports array in your module\n\n```ts\nimport { NgxAircalModule } from \"ngx-aircal\";\n```\n\n```ts\n@NgModule({\n  imports: [\n     ...,\n    NgxAircalModule\n})\n```\n\n## How do I use the calendar?\n\nAdd the following to your html template. ngx-aircal uses a data attribute selector to keep your HTML valid:\n\n```html\n\u003cdiv data-ngx-aircal [options]=\"calendarOptions\" \n    name=\"dateRange\" \n    [(ngModel)]=\"dateRange\"\n    (onDateRangeCommitted)=\"onDateRangeCommitted($event)\" \n    (onDateRangeChanged)=\"onDateRangeChanged($event)\"\n    (onCalendarViewChanged)=\"onCalendarViewChanged($event)\" \n    (onInputFieldChanged)=\"onInputFieldChanged($event)\"\n    (onDateRangeInitialised)=\"onDateRangeInitialised($event)\"\n    (onDateRangeCleared)=\"onDateRangeCleared($event)\"\u003e\n\u003c/div\u003e\n```\n\n### Options\n\nInitialise an options object as a component property. Now, pass this to the calendar component:\n\n```ts\nimport { AircalOptions } from \"ngx-aircal\";\n```\n\n```ts\nexport class AppComponent {\n    ...\n    public calendarOptions: AircalOptions = new AircalOptions();\n    ...\n}\n```\n\nYou can update options by passing an object into the constructor:\n\n```ts\nexport class AppComponent {\n    ...\n    public calendarOptions: AircalOptions = new AircalOptions({\n      inlineMode: true,\n      daysSelectedCounterVisible: false\n    });\n    ...\n}\n```\n\n\n| Option name | Default value | Type | Description |\n| ------------- | ------------- | ----- | --- |\n| defaultStart | new Date() | Date | Set the default start view when the calendar is opened |\n| inlineMode | false | Boolean | Display the calendar without the input field |\n| disable | false | Boolean | Disable the ability to set the date and apply it |\n| singlePicker | false | Boolean | Use a single range picker instead of a double to save space |\n| startDate | null | Date | Set a starting date. If no end is provided, then the datepicker will be in highlighted mode on the UI, ready for an end date selection. |\n| endDate | null | Date | Set an end date. If no start date is set, it will fall back to become the start date. |\n| dayLabels | new AircalDayLabels() | AircalDayLabels | Set the label values for each day of the week |\n| selectionShortcuts | { \"7.days\": \"7 Days\", \"14.days\": \"14 Days\", \"1.months\": \"1 Month\", \"6.months\": \"6 Months\", \"1.years\": \"1 Year\" } | Object | Options and values to pass to the quick selection component when _selectionShortcutVisible_ is true. Key is the value parsed by the plugin, and the value is what is shown in the input dropdown. Separate the key length and duration values by a '.'. It can parse different durations. e.g. \"7.weeks\": \"7 Weeks\" |\n| dateFormat | \"dd/MM/yyyy\" | String | Format the date displayed in the input, and given in the callback response. Format is Unicode Technical Standard #35. Uses date-fns library to format the dates. When setting the dateFormat option, be aware that you must use [Unicode tokens](https://date-fns.org/v2.0.0-alpha.27/docs/Unicode-Tokens) |\n| previousMonthWrapAround | true | Boolean | Should dates be shown in the previous month spaces |\n| nextMonthWrapAround | true | Boolean | Should dates be shown in the next month spaces |\n| daysSelectedCounterVisible | true | Boolean | Should the calendar display the number of days selected |\n| selectionShortcutVisible | false | Boolean | Should the range shortcut be visible |\n| backgroundVisible | true | Boolean | Make the background transparent |\n| width | \"\" | String | Overwrite the width set in the css |\n| height | \"\" | String | Overwrite the width set in the css |\n| applyText | \"Apply\" | String | Change the text to commit the date range |\n| autoApplyAndClose | false | Boolean | When an end date is selected (or a start date if a start and end already exist), automatically apply the date selection and close the calendar |\n| includeExamplePlaceholder | true | Boolean | Show an placeholder example for the input field. Dynamically generates example dates based on _dateFormat_ option |\n| autoCloseWhenApplied | false | Boolean | Close the calendar when the apply button is pressed |\n| clearText | \"Clear\" | String | Change the text to clear the date range |\n| highlightToday | true | Boolean | Highlight the cell colour for today |\n| showClearBtn | true | Boolean | Should the clear button be shown on the UI |\n| showApplyBtn | true | Boolean | Should the apply button be shown on the UI |\n| minYear | 1000 | Number | The minimum year selectable |\n| maxYear | 9999 | Number | The maximum year selectable |\n| disablePreviousSelection | false | Boolean | Disable the previous selection arrow |\n| disableForwardSelection | false | Boolean | Disable the next selection arrow |\n| disableFromHereBackwards | null | Date | Disable the cells from being selected from the date supplied going backwards |\n| disableFromHereForwards | null | Date | Disable the cells from being selected from the date supplied going forwards |\n| indicateInvalidDateRange | true | Boolean | Indicate whether or not to show the red border on the input field |\n| hasArrow | true | Boolean | Should the calendar have the arrow pointer |\n| arrowBias | \"left\" | arrowBias | What edge should the arrow display on |\n| calendarPosition | calendarBias | \"bottom\" | Where does the calendar display in relation to the input |\n| allowQuicksetMonth | false | Boolean | Allow the quick selection on months by clicking the month |\n| allowQuicksetYear | false | Boolean | Allow the quick selection of years by clicking the year |\n| allowUserInputField | true | Boolean | Should the default view be an input field, or just a button that contains text |\n| allowInfiniteEndDate | false | Boolean | Allow no end date to be set |\n| closeOnOutsideClick | false | Boolean | Allow the calendar to be closed by clicking outside the component |\n| icons | {leftArrow: null, rightArrow: null } | { leftArrow?: null \\| string, rightArrow?: null \\| string } | Option to provide a base64 image to replace the existing arrows on the main calendar |\n\n## Models\n\nYou can use ngModel or a reactive form to work with the calendar.\n\n### ngModel\n\nDefine an object with 2 props, __startDate__, and __endDate__. Both properties must be of type 'Date'.\n\n```ts\nngOnInit() {\n\tthis.dateRange = {\n    startDate: new Date(\n      2018,\n      6,\n      27\n    ), \n    endDate: new Date(\n      2018,\n      8,\n      27\n    )\n  };\n}\n```\n\nYour should pass in the object into the ngModel _box of bananas_ on your template:\n\n```html\n\u003cdiv data-ngx-aircal [options]=\"calendarOptions\" [(ngModel)]=\"dateRange\"\u003e\u003c/div\u003e\n```\n\n### Reactive forms\n\n```ts\nngOnInit() {\n  this.form = this._FormBuilder.group({\n    dateRange: [{\n      startDate: new Date(\n        2018,\n        6,\n        27\n      ),\n      endDate: new Date(\n        2018,\n        8,\n        27\n      )\n    }, Validators.required]\n  }); \n}\n```\n\nAdd the following inside your template:\n\n```html\n\u003cform [formGroup]=\"myForm\"\u003e\n    \u003cdiv data-ngx-aircal [options]=\"calendarOptions\" formControlName=\"dateRange\"\u003e\u003c/div\u003e\n\u003c/form\u003e\n```\n\n## Events, callbacks \u0026amp; responses\n\nThere are many callbacks you can use to communicate with your parent component. A full list of callbacks is below.\n\n```html\n\u003cdiv data-ngx-aircal [options]=\"calendarOptions\" \n    name=\"dateRange\" \n    [(ngModel)]=\"dateRange\"\n    (onDateRangeCommitted)=\"onDateRangeCommitted($event)\" \n    (onDateRangeChanged)=\"onDateRangeChanged($event)\"\n    (onCalendarViewChanged)=\"onCalendarViewChanged($event)\" \n    (onInputFieldChanged)=\"onInputFieldChanged($event)\"\n    (onDateRangeInitialised)=\"onDateRangeInitialised($event)\"\n    (onDateRangeCleared)=\"onDateRangeCleared($event)\"\u003e\n\u003c/div\u003e\n```\n\nNote the event name, and the provided callback function, which takes in $event as a parameter:\n\n```html\n(onDateRangeCommitted)=\"onDateRangeCommitted($event)\"\n```\n\nThe plugin will respond with a specific set of properties - either:\n\n```ts\nclass AircalResponse {\n    public startDate: Date;\n    public endDate: Date;\n    public formattedStartDate: string;\n    public formattedEndDate: string;\n}\n\nclass AircalInputResponse {\n    public startDate: Date;\n    public endDate: Date;\n    public formattedStartDate: string;\n    public formattedEndDate: string;\n    public isRangeValid: boolean;\n}\n```\n\nExample usage:\n\n```ts\npublic onDateRangeChanged(event: AircalResponse) {\n\tthis.updatePageResults(event.startDate, event.endDate);\n}\n```\n\n##### List of callbacks\n\nAll callbacks will return __AircalResponse__ or __AircalInputResponse__ type. __AircalInputResponse__ has an extra boolean value to show you if the date is valid.\n\n| Callback name | Response type | Description |\n| ------------- | ------------- | ----- |\n| onDateRangeCommitted | AircalResponse | When the range is committed by the user. Normally by the apply button, but in case __showApplyBtn__ is false, it will respond automatically when the end date is selected |\n| onDateRangeChanged | AircalResponse | When the start or end date is changed by the user. |\n| onCalendarViewChanged | AircalResponse | When the view is changed left or right using the arrows |\n| onInputFieldChanged  | AircalInputResponse | When the user modifies the input field. |\n| onDateRangeInitialised  | AircalResponse | As soon as the component initialises, a response will be returned for consistency. |\n| onDateRangeCleared  | AircalResponse | When the __showClearBtn__ option is true, and the user presses the button, a response will be returned. |\n\n## Author\n* Author: Chris Swarbrick (chrisswarb)\n\n## Credit\n* Icons by Dave Gandy and Lyolya from www.flaticon.com","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcswarb%2Fngx-aircal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcswarb%2Fngx-aircal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcswarb%2Fngx-aircal/lists"}