@alexfriesen/ngx-mat-timepicker

# @alexfriesen/ngx-mat-timepicker [![npm][badge-npm-version]][url-npm] [![MIT licensed][badge-licence]][url-licence] [![Build state][badge-ci-state]][url-ci-state] [![Size][badge-bundle]][url-bundle] A simple time picker module using Angular Material: it provides an Android style dialog for time selection and a handy input for time selection in Material style. <img width="371" alt="ngx-mat-datepicker preview" src="https://github.com/user-attachments/assets/53b98eb1-51a6-46b5-8dd1-a405ded668a0" /> ## Table of contents - [Getting started](#getting-started) - [Internationalization](#internationalization) - [Documentation](#documentation) - [NgxMatTimepicker](#ngxMatTimepicker) - [NgxMatTimepickerComponent](#ngxMatTimepickercomponent) - [NgxMatTimepickerFieldComponent](#ngxMatTimepickerfieldcomponent) - [NgxMatTimepickerToggleComponent](#ngxMatTimepickertogglecomponent) - [NgxMatTimepickerToggleIconDirective](#ngxMatTimepickertoggleicondirective) - [Development](#development) - [Tests](#tests) - [License](#license) ## Getting started Install timepicker through npm: ```bash npm i --save @alexfriesen/ngx-mat-timepicker ``` Next import the timepicker module into your app's module: ```typescript import { NgModule } from '@angular/core'; import { NgxMatTimepickerModule } from '@alexfriesen/ngx-mat-timepicker'; @NgModule({ imports: [NgxMatTimepickerModule], }) export class MyModule {} ``` Finally connect the timepicker to an input via a template property: ```html <input [ngxMatTimepicker]="picker" /> <ngx-mat-timepicker #picker /> ``` The timepicker opens once you click on the input ## Internationalization Timepicker supports locales in format `BCP 47`. It has `en-US` locale by default. To override default locale: ```typescript import { NgModule } from '@angular/core'; import { NgxMatTimepickerModule } from '@alexfriesen/ngx-mat-timepicker'; @NgModule({ imports: [NgxMatTimepickerModule.setLocale('en-GB')], }) export class MyModule {} ``` ## Theming This Package relies on an existing Angular Material Theme: ```scss @import '@angular/material/prebuilt-themes/indigo-pink.css'; ``` or ```scss @use '@angular/material' as mat; @include mat.all-component-themes($my-theme); ``` ## Documentation #### API reference for Angular Material Timepicker ```typescript import { NgxMatTimepickerModule } from '@alexfriesen/ngx-mat-timepicker'; ``` #### NgxMatTimepicker Directive responsible for managing the timepicker popup and setting value to input Selector: `ngxMatTimepicker` **Properties** | Name | Description | | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | @Input() ngxMatTimepicker: NgxMatTimepickerComponent | The timepicker that this input is associated with. | | @Input() color: ThemePalette | The material palette to use. | | @Input() disabled: boolean | Weather the timepicker popup should be disabled. | | @Input() value: string | Set a default value and time for a timepicker. The format of the time is in 12 hours notation `11:00 PM` or in 24 hours notation `23:00`. A Date string won't work. | | @Input() format: number | `12` or `24` . 12h/24h view for hour selection clock . `12` (AM/PM) format by default. | | @Input() min: string or DateTime | Set min time for timepicker (`11:15 pm` ) | | @Input() max: string or DateTime | Set max time for timepicker (`11:15 pm` ) | | @Input() disableClick: boolean | Set `true` to disable opening timepicker by clicking on the input | #### NgxMatTimepickerLocaleService This service allows to **change the locale anytime**. You can inject this in your component or extend and provide your version, in order to provide your current locale to all the pickers! At this time is **semi-static**, which means you can't change the locale for pickers that are already opened. But **new pickers will always get the updated locale**. #### NgxMatTimepickerComponent Component responsible for visualisation the timepicker Selector: `ngx-mat-timepicker` **Properties** | Name | Description | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | @Input() cancelBtnTmpl: TemplateRef<Node> | Set if you want to change cancel button to your custom one. | | @Input() confirmBtnTmpl: TemplateRef<Node> | Set if you want to change confirm button to your custom one. | | @Input() editableHintTmpl: TemplateRef<Node> | Set if you want to change dial hint to your custom one. Works only if `enableKeyboardInput = true` | | @Input() ESC: boolean | Disable or enable closing timepicker by ESC. | | @Input() enableKeyboardInput: boolean | To disable or enable changing time through a keyboard on the timepicker dial without interaction with a clock face. Set `false` by default | | @Input() minutesGap: number | To define a gap between minutes. Set `1` by default | | @Input() defaultTime: string | Set default time for a timepicker. `12:00 AM` by default | | @Input() preventOverlayClick: boolean | Set `true` to prevent closing the timepicker by overlay click. Uses `false` by default | | @Input() disableAnimation: boolean | Set `true` to prevent opening and closing timepicker animation. Uses `false` by default | | @Input() hoursOnly: boolean | Set `true` to prevent switching to minutes automatically once hour is selected. Uses `false` by default | | @Input() theme: NgxMatTimepickerTheme | Custom css properties which will override the defaults | | @Input() timepickerClass: string | To provide a custom css class for the timepicker | | @Output() timeSet: EventEmitter\<string\> | Emits time when that was set. | | @Output() opened: EventEmitter\<null\> | Emits after timepicker was opened. | | @Output() closed: EventEmitter\<null\> | Emits after timepicker was closed. | | @Output() hourSelected: EventEmitter\<number\> | Emits after hour was selected. | | @Output() timeChanged: EventEmitter\<string\> | Emits once time was changed. | #### NgxMatTimepickerFieldComponent The timepicker as a control. Selector: `ngx-mat-timepicker-field` **Properties** | Name | Description | | ----------------------------------------------------- | --------------------------------------------------------------------------- | | @Input() disabled: boolean | Whether the timepicker is disabled | | @Input() floatLabel: 'never' or 'always' or 'auto' | Whether the labels of the fields should float, default to never | | @Input() toggleIcon: TemplateRef\<HTMLObjectElement\> | Provide custom `svg` icon for toggle button | | @Input() buttonAlign: 'right' or 'left' | Positioning toggle button (`right` by default) | | @Input() clockTheme: NgxMatTimepickerTheme | Custom css properties which will override timepicker clock | | @Input() controlOnly: boolean | Hide or display toggle button with the timepicker clock | | @Input() format: number | `12` or `24` . Set format for timepicker. `12` (AM/PM) format by default. | | @Input() cancelBtnTmpl: TemplateRef\<Node\> | Set if you want to change cancel button for timepicker to your custom one. | | @Input() confirmBtnTmpl: TemplateRef\<Node\> | Set if you want to change confirm button for timepicker to your custom one. | | @Input() min: string or DateTime | Set min time for timepicker (`11:15 pm` ) | | @Input() max: string or DateTime | Set max time for timepicker (`11:15 pm` ) | | @Output() timeChanged: EventEmitter\<string\> | Emit a new time once it is changed. | #### NgxMatTimepickerToggleComponent Component responsible for opening the timepicker. Selector: `ngx-mat-timepicker-toggle` **Properties** | Name | Description | | --------------------------------------- | ----------------------------------------------- | | @Input() for: NgxMatTimepickerComponent | Timepicker instance that the button will toggle | | @Input() disabled: boolean | Whether the toggle button is disabled | #### NgxMatTimepickerToggleIconDirective Can be used to override the icon of a `NgxMatTimepickerToggleComponent`. Selector: `[ngxMatTimepickerToggleIcon]` **Properties** | Name | Description | | ----------------------------------------------------- | ------------------------------------------------------ | | @Input() ngxMatTimepickerTheme: NgxMatTimepickerTheme | Custom css properties which will override the defaults | ### Demo <a href="https://alexfriesen.github.io/ngx-mat-timepicker/">Demo</a> ```terminal $ npm $ npm start ``` Run `npm test` to run tests once. ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details ### Thanks to [LayZeeDK](https://github.com/LayZeeDK) - For his great work on the unit tests and upgrades for v15 "legacy" [Agranom](https://github.com/Agranom) for setting up the original repo. [badge-bundle]: https://img.shields.io/bundlephobia/minzip/@alexfriesen/ngx-mat-timepicker [badge-ci-state]: https://github.com/alexfriesen/ngx-mat-timepicker/actions/workflows/main.yml/badge.svg [badge-licence]: https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square [badge-npm-downloads]: https://img.shields.io/npm/dm/@alexfriesen/ngx-mat-timepicker.svg?style=flat-square [badge-npm-version]: https://img.shields.io/npm/v/@alexfriesen/ngx-mat-timepicker.svg?style=flat-square [url-bundle]: https://img.shields.io/bundlephobia/minzip/@alexfriesen/ngx-mat-timepicker [url-ci-state]: https://github.com/alexfriesen/ngx-mat-timepicker/actions [url-licence]: https://github.com/alexfriesen/ngx-mat-timepicker/blob/master/LICENSE [url-npm]: https://www.npmjs.com/package/@alexfriesen/ngx-mat-timepicker