\n\n[![CI/CD Status][github-action-badge]][github-action-link] [![Codecov][codecov-badge]][codecov-project] [![MIT License][license-image]][license-url] \n[![NPM version][npm-version-image]][npm-package] [![Github release][gh-release-badge]][gh-releases] [![Library size][file-size-badge]][raw-distribution-js]\n\n\n\n**Table of Contents**\n\n- [Usage](#usage)\n - [Hint](#hint)\n - [No validation or hint](#no-validation-or-hint)\n - [Prefix icon](#prefix-icon)\n - [Disabled](#disabled)\n - [Required](#required)\n - [Required asterisk `*`](#required-asterisk-)\n - [Clearable](#clearable)\n - [Focused](#focused)\n - [Input Type](#input-type)\n - [Input Attributes](#input-attributes)\n - [Validation timing](#validation-timing)\n - [Component reference](#component-reference)\n - [Usage with Reactive Forms](#usage-with-reactive-forms)\n - [Event Emitters](#event-emitters)\n - [Masks](#masks)\n - [Available Masks](#available-masks)\n - [Sanitize the model value](#sanitize-the-model-value)\n - [Allow decimals in number-based masks](#allow-decimals-in-number-based-masks)\n - [Datepicker](#datepicker)\n - [Filter out available dates](#filter-out-available-dates)\n - [Set a max/min date range](#set-a-maxmin-date-range)\n - [Open calendar to a specific date](#open-calendar-to-a-specific-date)\n - [Open calendar to a specific view](#open-calendar-to-a-specific-view)\n - [Example with dynamic validation](#example-with-dynamic-validation)\n - [Textarea](#textarea)\n - [Rows](#rows)\n- [Test Helpers](#test-helpers)\n\n\n\n\n## Usage\n\nAttach an `NgModel` or `FormControl` to the input:\n\n```html\n\n\n\n```\n\nWe should _almost always_ being using a `FormControl`.\n\n> Note: If you don't need a full form group you can provide a stand-alone control: `myControl = new FormControl();`\n\n\n### Hint\n\nA 'hint' can be displayed below the input on the right-hand side. This should be used for helpful user information such as input\nrequirements.\n\n```html\n\n```\n\n### No validation or hint\n\nA flag to define whether this input field needs validation or hint. If it needs validation or hint, a padding bottom is added for the message, otherwise, no padding at the bottom.\n\n```html\n\n```\n\n### Prefix icon\n\nTo include an icon as a prefix to the input, pass a valid icon name to `prefixIcon`:\n\n```html\n\n```\n\n> See all valid icon possibilities: https://material.io/icons\n\n\n### Disabled\n\nInputs can be disabled by setting the component flag OR by setting the associated `FormControl` to `disabled`.\n\nThe `isDisabled` flag works with both `ngModel` and `FormControl` inputs:\n\n```html\n\n```\n\nWhen using Reactive Forms, controls should be disabled via the control:\n\n```typescript\nmyControl: FormControl = new FormControl({value: null, disabled: true});\n```\n\n\n### Required\n\nWhen using a `FormControl`, set the required validator on the control:\n\n```typescript\nmyControl = new FormControl(null, Validators.required);\n```\n\nWhen using `ngModel`, validations are placed on the input as data-attributes (just like native HTML inputs):\n\n```html\n\n```\n\nIf only the required asterisk is needed rather than validation errors, the `isRequired` flag can be used:\n\n```html\n\n```\n\n\n#### Required asterisk `*`\n\nIf the input should be required, but the required asterisk `*` is not needed, disable it with the\n`hideRequiredMarker` input:\n\n```html\n\n```\n\n> NOTE: We should not hide this visual indicator without a very good reason!\n\n\n### Clearable\n\nIf the input should be easily reset, include the `isClearable` flag to enable a 'clear input'\nbutton: (button will appear as small `x` icon at the far right of the input)\n\n```html\n\n```\n\nWhen the input is cleared, the `cleared` event emitter will be fired with the value `true`.\n\n\n### Focused\n\nAuto-focus the input when the view loads:\n\n```html\n\n```\n\n> NOTE: If multiple inputs within the same view set `isFocused` to true, the _**last one rendered\n> will receive the final focus**_.\n\nThis can also be used to dynamically focus an existing input:\n\n```html\n\n```\n\n```typescript\nmyFocusedFlag = false;\n\ntoggleInputFocus() {\n this.myFocusedFlag = !this.myFocusedFlag;\n}\n```\n\n\n### Input Type\n\nThe input type can be defined with the type input:\n\n```html\n\n```\n\n> For all allowed types, see `TsInputTypes`.\n\n\n### Input Attributes\n\n`autocapitalize`, `autocomplete`, `spellcheck`, `readonly`\n\n```html\n\n```\n\n> For all allowed `autocomplete` types, see `TsInputAutocompleteTypes`.\n\n\n### Validation timing\n\nValidate on change rather than blur:\n\n```html\n\n```\n\n\n### Component reference\n\nTo get a reference to the component class, assign the exported name to a local variable:\n\n```html\n\n```\n\n```typescript\n@ViewChild(TsInputComponent, {static: false})\nmyVar: TsInputComponent;\n\nconsole.log('Component Class: ', this.myVar);\n```\n\n\n### Usage with Reactive Forms\n\nPass in the form control:\n\n```html\n\n```\n\n```typescript\nmyForm = this.formBuilder.group({\n date: [\n null, // If you need a default value, change this `null` to your value\n [\n Validators.required,\n ],\n ],\n});\n```\n\n**NOTE:** If using a form with nested form groups, _each group_ must be created with\n`formBuilder.group` for the form `get` control to work:\n\n```typescript\n// Notice the nested `dateRange` object without using `.group`\nmyForm: FormGroup = this.formBuilder.group({\n dateRange: {\n startDate: [\n new Date(2017, 4, 6),\n ],\n endDate: [\n new Date(2017, 4, 8),\n ],\n },\n});\n\n// THIS WILL FAIL!\nconst range = myForm.get('dateRange');\n\n//////////////////////////////////////////////////\n\n// Notice the nested `dateRange` object IS using `.group`\nmyForm: FormGroup = this.formBuilder.group({\n dateRange: this.formBuilder.group({\n startDate: [\n new Date(2017, 4, 6),\n [\n Validators.required,\n ],\n ],\n endDate: [\n new Date(2017, 4, 8),\n [\n Validators.required,\n ],\n ],\n }),\n});\n\n// Now there is a group for us to 'get'\nconst range = myForm.get('dateRange');\n```\n\n\n### Event Emitters\n\nSupported event emitters:\n\n```html\n\n```\n\n> NOTE: The `selected` input is only available when `datepicker` is true.\n\n\n### Masks\n\nMasks enable the input to enforce specific formatting for values; such as postal codes: `12345-1234`.\n\n\n#### Available Masks\n\n| Mask | Input value | Masked Value |\n|--------------|--------------|------------------|\n| `currency` | `12.34` | `$12.34` |\n| `date` | `12121982` | `12-12-1982` |\n| `number` | `1234.56` | `1,234.56` |\n| `percentage` | `12.4` | `12.4%` |\n| `phone` | `1231231234` | `(123) 123-1234` |\n| `postal` | `123456789` | `12345-6789` |\n\n\n#### Sanitize the model value\n\nMost often you will not want the mask characters to be saved as part of the actual value. By default this component will sanitize the value\nbefore saving it to the model. This can be disabled if needed:\n\n```html\n\n```\n\nThis setup will format the value displayed in the UI: `(123) 456-7890`)while saving the pure value to the model: `1234567890`.\n\n\n#### Allow decimals in number-based masks\n\nBy default, number based masks (`number`, `percentage`) allow decimals. This can be disabled:\n\n```html\n\n```\n\nThis means when the user types `12.34`, the input UI and model value will both be `1234`.\n\n\n### Datepicker\n\nTo add datepicker abilities to an input, set the `datepicker` input:\n\n```html\n\n```\n\n\n#### Filter out available dates\n\nIf, for instance, you need to prohibit weekend days (sat/sun) from being selected you can pass in a\ncustom method to filter dates:\n\n```html\n\n```\n\n```typescript\nmyFilter = (d: Date): boolean => {\n const day = d.getDay();\n // Prevent Saturday and Sunday from being selected.\n return day !== 0 && day !== 6;\n}\n```\n\n\n#### Set a max/min date range\n\nTo define bounds for date selection, pass in a valid `Date` to `minDate` and/or `maxDate`:\n\n```html\n\n```\n\n```typescript\ndate1 = new Date(2017, 2, 1);\ndate2 = new Date(2017, 8, 1);\n```\n\n\n#### Open calendar to a specific date\n\nPass in a `Date` to `openTo`:\n\n```html\n\n```\n\n```typescript\nmyDate = new Date(2017, 5, 12);\n```\n\n\n#### Open calendar to a specific view\n\nBy default, the calendar opens up to show the month view. This can be changed to show the year view initially:\n\n```html\n\n```\n\n`year` and `month` are the only two valid values.\n\n\n#### Example with dynamic validation\n\nWe can recreate a version of the {@link TsDateRangeComponent} using dynamic validation:\n\n```html\n\n```\n\n```typescript\nmyForm = this.formBuilder.group({\n startDate: [\n null,\n [\n Validators.required,\n ],\n ],\n endDate: [\n null,\n [\n Validators.required,\n ],\n ],\n});\n\n// When the startDate changes, we want to set that date as the minDate for the endDate\nrangeStartChange(event: MatDatepickerInputEvent) {\n if (event) {\n // Get the from control\n const control = this.formTwo.get('endDate');\n\n // Set all validators.\n // NOTE: setting validators will clear ALL existing validators, so we must add the required\n // validator here again\n control.setValidators([\n Validators.required,\n this.validatorsService.minDate(event.value),\n ]);\n // Tell the control to update according to the new validators\n control.updateValueAndValidity();\n }\n}\n\n// When the endDate changes, we want to set that date as the maxDate for the startDate\nrangeEndChange(event: MatDatepickerInputEvent) {\n if (event) {\n // Get the from control\n const control = this.formTwo.get('startDate');\n\n // Set all validators.\n // NOTE: setting validators will clear ALL existing validators, so we must add the required\n // validator here again\n control.setValidators([\n Validators.required,\n this.validatorsService.maxDate(event.value),\n ]);\n // Tell the control to update according to the new validators\n control.updateValueAndValidity();\n }\n}\n```\n\n\n### Textarea\n\nSwitch from a standard input to a textarea:\n\n```html\n\n```\n\n#### Rows\n\nThe row count can be dynamically adjusted:\n\n```html\n\n```\n\n\n## Test Helpers\n\nSome helpers are exposed to assist with testing. These are imported from `@terminus/ui-input/testing`;\n\n[[source]][test-helpers-src]\n\n| Function |\n|------------------------|\n| `getAllInputInstances` |\n| `getInputInstance` |\n| `getInputElement` |\n| `sendInput` |\n\n\n\n\n[test-helpers-src]: testing/src/test-helpers.ts\n[license-url]: https://github.com/GetTerminus/terminus-oss/blob/master/LICENSE\n[license-image]: http://img.shields.io/badge/license-MIT-blue.svg\n[codecov-project]: https://codecov.io/gh/GetTerminus/terminus-oss\n[codecov-badge]: https://codecov.io/gh/GetTerminus/terminus-oss/branch/master/graph/badge.svg\n[npm-version-image]: http://img.shields.io/npm/v/@terminus/ui-input.svg\n[npm-package]: https://www.npmjs.com/package/@terminus/ui-input\n[gh-release-badge]: https://img.shields.io/github/release/GetTerminus/terminus-oss.svg\n[gh-releases]: https://github.com/GetTerminus/terminus-ui/releases/\n[github-action-badge]: https://github.com/GetTerminus/terminus-oss/workflows/CI%20Release/badge.svg\n[github-action-link]: https://github.com/GetTerminus/terminus-oss/actions?query=workflow%3A%22CI+Release%22\n[file-size-badge]: http://img.badgesize.io/https://unpkg.com/@terminus/ui-input/bundles/terminus-ui-input.umd.min.js?compression=gzip\n[raw-distribution-js]: https://unpkg.com/@terminus/ui-input/bundles/terminus-ui-input.umd.js\n","readmeFilename":"README.md","description":"
\n\n[![CI/CD Status][github-action-badge]][github-action-link] [![Codecov][codecov-badge]][codecov-project] [![MIT License][license-image]][license-url] \n[![NPM version][npm-version-image]][npm-package] [![Github release][gh-release-badge]][gh-releases] [![Library size][file-size-badge]][raw-distribution-js]\n\n\n\n**Table of Contents**\n\n- [Usage](#usage)\n - [Hint](#hint)\n - [No validation or hint](#no-validation-or-hint)\n - [Prefix icon](#prefix-icon)\n - [Disabled](#disabled)\n - [Required](#required)\n - [Required asterisk `*`](#required-asterisk-)\n - [Clearable](#clearable)\n - [Focused](#focused)\n - [Input Type](#input-type)\n - [Input Attributes](#input-attributes)\n - [Validation timing](#validation-timing)\n - [Component reference](#component-reference)\n - [Usage with Reactive Forms](#usage-with-reactive-forms)\n - [Event Emitters](#event-emitters)\n - [Masks](#masks)\n - [Available Masks](#available-masks)\n - [Sanitize the model value](#sanitize-the-model-value)\n - [Allow decimals in number-based masks](#allow-decimals-in-number-based-masks)\n - [Datepicker](#datepicker)\n - [Filter out available dates](#filter-out-available-dates)\n - [Set a max/min date range](#set-a-maxmin-date-range)\n - [Open calendar to a specific date](#open-calendar-to-a-specific-date)\n - [Open calendar to a specific view](#open-calendar-to-a-specific-view)\n - [Example with dynamic validation](#example-with-dynamic-validation)\n - [Textarea](#textarea)\n - [Rows](#rows)\n- [Test Helpers](#test-helpers)\n\n\n\n\n## Usage\n\nAttach an `NgModel` or `FormControl` to the input:\n\n```html\n\n\n\n```\n\nWe should _almost always_ being using a `FormControl`.\n\n> Note: If you don't need a full form group you can provide a stand-alone control: `myControl = new FormControl();`\n\n\n### Hint\n\nA 'hint' can be displayed below the input on the right-hand side. This should be used for helpful user information such as input\nrequirements.\n\n```html\n\n```\n\n### No validation or hint\n\nA flag to define whether this input field needs validation or hint. If it needs validation or hint, a padding bottom is added for the message, otherwise, no padding at the bottom.\n\n```html\n\n```\n\n### Prefix icon\n\nTo include an icon as a prefix to the input, pass a valid icon name to `prefixIcon`:\n\n```html\n\n```\n\n> See all valid icon possibilities: https://material.io/icons\n\n\n### Disabled\n\nInputs can be disabled by setting the component flag OR by setting the associated `FormControl` to `disabled`.\n\nThe `isDisabled` flag works with both `ngModel` and `FormControl` inputs:\n\n```html\n\n```\n\nWhen using Reactive Forms, controls should be disabled via the control:\n\n```typescript\nmyControl: FormControl = new FormControl({value: null, disabled: true});\n```\n\n\n### Required\n\nWhen using a `FormControl`, set the required validator on the control:\n\n```typescript\nmyControl = new FormControl(null, Validators.required);\n```\n\nWhen using `ngModel`, validations are placed on the input as data-attributes (just like native HTML inputs):\n\n```html\n\n```\n\nIf only the required asterisk is needed rather than validation errors, the `isRequired` flag can be used:\n\n```html\n\n```\n\n\n#### Required asterisk `*`\n\nIf the input should be required, but the required asterisk `*` is not needed, disable it with the\n`hideRequiredMarker` input:\n\n```html\n\n```\n\n> NOTE: We should not hide this visual indicator without a very good reason!\n\n\n### Clearable\n\nIf the input should be easily reset, include the `isClearable` flag to enable a 'clear input'\nbutton: (button will appear as small `x` icon at the far right of the input)\n\n```html\n\n```\n\nWhen the input is cleared, the `cleared` event emitter will be fired with the value `true`.\n\n\n### Focused\n\nAuto-focus the input when the view loads:\n\n```html\n\n```\n\n> NOTE: If multiple inputs within the same view set `isFocused` to true, the _**last one rendered\n> will receive the final focus**_.\n\nThis can also be used to dynamically focus an existing input:\n\n```html\n\n```\n\n```typescript\nmyFocusedFlag = false;\n\ntoggleInputFocus() {\n this.myFocusedFlag = !this.myFocusedFlag;\n}\n```\n\n\n### Input Type\n\nThe input type can be defined with the type input:\n\n```html\n\n```\n\n> For all allowed types, see `TsInputTypes`.\n\n\n### Input Attributes\n\n`autocapitalize`, `autocomplete`, `spellcheck`, `readonly`\n\n```html\n\n```\n\n> For all allowed `autocomplete` types, see `TsInputAutocompleteTypes`.\n\n\n### Validation timing\n\nValidate on change rather than blur:\n\n```html\n\n```\n\n\n### Component reference\n\nTo get a reference to the component class, assign the exported name to a local variable:\n\n```html\n\n```\n\n```typescript\n@ViewChild(TsInputComponent, {static: false})\nmyVar: TsInputComponent;\n\nconsole.log('Component Class: ', this.myVar);\n```\n\n\n### Usage with Reactive Forms\n\nPass in the form control:\n\n```html\n\n```\n\n```typescript\nmyForm = this.formBuilder.group({\n date: [\n null, // If you need a default value, change this `null` to your value\n [\n Validators.required,\n ],\n ],\n});\n```\n\n**NOTE:** If using a form with nested form groups, _each group_ must be created with\n`formBuilder.group` for the form `get` control to work:\n\n```typescript\n// Notice the nested `dateRange` object without using `.group`\nmyForm: FormGroup = this.formBuilder.group({\n dateRange: {\n startDate: [\n new Date(2017, 4, 6),\n ],\n endDate: [\n new Date(2017, 4, 8),\n ],\n },\n});\n\n// THIS WILL FAIL!\nconst range = myForm.get('dateRange');\n\n//////////////////////////////////////////////////\n\n// Notice the nested `dateRange` object IS using `.group`\nmyForm: FormGroup = this.formBuilder.group({\n dateRange: this.formBuilder.group({\n startDate: [\n new Date(2017, 4, 6),\n [\n Validators.required,\n ],\n ],\n endDate: [\n new Date(2017, 4, 8),\n [\n Validators.required,\n ],\n ],\n }),\n});\n\n// Now there is a group for us to 'get'\nconst range = myForm.get('dateRange');\n```\n\n\n### Event Emitters\n\nSupported event emitters:\n\n```html\n\n```\n\n> NOTE: The `selected` input is only available when `datepicker` is true.\n\n\n### Masks\n\nMasks enable the input to enforce specific formatting for values; such as postal codes: `12345-1234`.\n\n\n#### Available Masks\n\n| Mask | Input value | Masked Value |\n|--------------|--------------|------------------|\n| `currency` | `12.34` | `$12.34` |\n| `date` | `12121982` | `12-12-1982` |\n| `number` | `1234.56` | `1,234.56` |\n| `percentage` | `12.4` | `12.4%` |\n| `phone` | `1231231234` | `(123) 123-1234` |\n| `postal` | `123456789` | `12345-6789` |\n\n\n#### Sanitize the model value\n\nMost often you will not want the mask characters to be saved as part of the actual value. By default this component will sanitize the value\nbefore saving it to the model. This can be disabled if needed:\n\n```html\n\n```\n\nThis setup will format the value displayed in the UI: `(123) 456-7890`)while saving the pure value to the model: `1234567890`.\n\n\n#### Allow decimals in number-based masks\n\nBy default, number based masks (`number`, `percentage`) allow decimals. This can be disabled:\n\n```html\n\n```\n\nThis means when the user types `12.34`, the input UI and model value will both be `1234`.\n\n\n### Datepicker\n\nTo add datepicker abilities to an input, set the `datepicker` input:\n\n```html\n\n```\n\n\n#### Filter out available dates\n\nIf, for instance, you need to prohibit weekend days (sat/sun) from being selected you can pass in a\ncustom method to filter dates:\n\n```html\n\n```\n\n```typescript\nmyFilter = (d: Date): boolean => {\n const day = d.getDay();\n // Prevent Saturday and Sunday from being selected.\n return day !== 0 && day !== 6;\n}\n```\n\n\n#### Set a max/min date range\n\nTo define bounds for date selection, pass in a valid `Date` to `minDate` and/or `maxDate`:\n\n```html\n\n```\n\n```typescript\ndate1 = new Date(2017, 2, 1);\ndate2 = new Date(2017, 8, 1);\n```\n\n\n#### Open calendar to a specific date\n\nPass in a `Date` to `openTo`:\n\n```html\n\n```\n\n```typescript\nmyDate = new Date(2017, 5, 12);\n```\n\n\n#### Open calendar to a specific view\n\nBy default, the calendar opens up to show the month view. This can be changed to show the year view initially:\n\n```html\n\n```\n\n`year` and `month` are the only two valid values.\n\n\n#### Example with dynamic validation\n\nWe can recreate a version of the {@link TsDateRangeComponent} using dynamic validation:\n\n```html\n\n```\n\n```typescript\nmyForm = this.formBuilder.group({\n startDate: [\n null,\n [\n Validators.required,\n ],\n ],\n endDate: [\n null,\n [\n Validators.required,\n ],\n ],\n});\n\n// When the startDate changes, we want to set that date as the minDate for the endDate\nrangeStartChange(event: MatDatepickerInputEvent) {\n if (event) {\n // Get the from control\n const control = this.formTwo.get('endDate');\n\n // Set all validators.\n // NOTE: setting validators will clear ALL existing validators, so we must add the required\n // validator here again\n control.setValidators([\n Validators.required,\n this.validatorsService.minDate(event.value),\n ]);\n // Tell the control to update according to the new validators\n control.updateValueAndValidity();\n }\n}\n\n// When the endDate changes, we want to set that date as the maxDate for the startDate\nrangeEndChange(event: MatDatepickerInputEvent) {\n if (event) {\n // Get the from control\n const control = this.formTwo.get('startDate');\n\n // Set all validators.\n // NOTE: setting validators will clear ALL existing validators, so we must add the required\n // validator here again\n control.setValidators([\n Validators.required,\n this.validatorsService.maxDate(event.value),\n ]);\n // Tell the control to update according to the new validators\n control.updateValueAndValidity();\n }\n}\n```\n\n\n### Textarea\n\nSwitch from a standard input to a textarea:\n\n```html\n\n```\n\n#### Rows\n\nThe row count can be dynamically adjusted:\n\n```html\n\n```\n\n\n## Test Helpers\n\nSome helpers are exposed to assist with testing. These are imported from `@terminus/ui-input/testing`;\n\n[[source]][test-helpers-src]\n\n| Function |\n|------------------------|\n| `getAllInputInstances` |\n| `getInputInstance` |\n| `getInputElement` |\n| `sendInput` |\n\n\n\n\n[test-helpers-src]: testing/src/test-helpers.ts\n[license-url]: https://github.com/GetTerminus/terminus-oss/blob/master/LICENSE\n[license-image]: http://img.shields.io/badge/license-MIT-blue.svg\n[codecov-project]: https://codecov.io/gh/GetTerminus/terminus-oss\n[codecov-badge]: https://codecov.io/gh/GetTerminus/terminus-oss/branch/master/graph/badge.svg\n[npm-version-image]: http://img.shields.io/npm/v/@terminus/ui-input.svg\n[npm-package]: https://www.npmjs.com/package/@terminus/ui-input\n[gh-release-badge]: https://img.shields.io/github/release/GetTerminus/terminus-oss.svg\n[gh-releases]: https://github.com/GetTerminus/terminus-ui/releases/\n[github-action-badge]: https://github.com/GetTerminus/terminus-oss/workflows/Release%20CI/badge.svg\n[github-action-link]: https://github.com/GetTerminus/terminus-oss/actions?query=workflow%3A%22CI+Release%22\n[file-size-badge]: http://img.badgesize.io/https://unpkg.com/@terminus/ui-input/bundles/terminus-ui-input.umd.min.js?compression=gzip\n[raw-distribution-js]: https://unpkg.com/@terminus/ui-input/bundles/terminus-ui-input.umd.js\n","readmeFilename":"README.md","description":"
\n\n[![CI/CD Status][github-action-badge]][github-action-link] [![Codecov][codecov-badge]][codecov-project] [![MIT License][license-image]][license-url] \n[![NPM version][npm-version-image]][npm-package] [![Github release][gh-release-badge]][gh-releases] [![Library size][file-size-badge]][raw-distribution-js]\n\n\n\n**Table of Contents**\n\n- [Installation](#installation)\n - [Packages that need to be installed](#packages-that-need-to-be-installed)\n - [Modules that need to be in NgModule](#modules-that-need-to-be-in-ngmodule)\n - [Styles to be added](#styles-to-be-added)\n - [Links to be added](#links-to-be-added)\n- [Usage](#usage)\n - [Hint](#hint)\n - [No validation or hint](#no-validation-or-hint)\n - [Prefix icon](#prefix-icon)\n - [Disabled](#disabled)\n - [Required](#required)\n - [Required asterisk `*`](#required-asterisk-)\n - [Clearable](#clearable)\n - [Focused](#focused)\n - [Input Type](#input-type)\n - [Input Attributes](#input-attributes)\n - [Validation timing](#validation-timing)\n - [Component reference](#component-reference)\n - [Usage with Reactive Forms](#usage-with-reactive-forms)\n - [Event Emitters](#event-emitters)\n - [Masks](#masks)\n - [Available Masks](#available-masks)\n - [Sanitize the model value](#sanitize-the-model-value)\n - [Allow decimals in number-based masks](#allow-decimals-in-number-based-masks)\n - [Datepicker](#datepicker)\n - [Filter out available dates](#filter-out-available-dates)\n - [Set a max/min date range](#set-a-maxmin-date-range)\n - [Open calendar to a specific date](#open-calendar-to-a-specific-date)\n - [Open calendar to a specific view](#open-calendar-to-a-specific-view)\n - [Example with dynamic validation](#example-with-dynamic-validation)\n - [Textarea](#textarea)\n - [Rows](#rows)\n- [Test Helpers](#test-helpers)\n\n\n\n## Installation\n\n### Packages that need to be installed\n\n * @angular/cdk\n * @angular/flex-layout\n * @angular/material\n * @terminus/design-tokens\n * @terminus/ngx-tools\n * @terminus/ui-form-field\n * @terminus/ui-icon\n * @terminus/ui-input\n * @terminus/ui-pipes\n * @terminus/ui-spacing\n * @terminus/ui-styles\n * @terminus/ui-utilities\n * @terminus/ui-validation-messages\n * @terminus/ui-validators\n * date-fns\n * text-mask-addons\n * text-mask-core\n\nUsing `ng add` command can help getting all the dependencies installed:\n\n```bash\n ng add @terminus/ui-input\n```\n\n### Modules that need to be in NgModule\n\n * BrowserAnimationsModule\n * TsInputModule\n * FormsModule\n * ReactiveFormsModule\n\n\n### Styles to be added\n\n At top level `styles.scss`, add these styles:\n\n```css\n@import '~@terminus/design-tokens/css/library-design-tokens.css';\n@import '~@terminus/ui-styles/terminus-ui.css';\n```\n\n### Links to be added\n\nIn order to have material icons shown up correctly, add this to the top level html\n\n```html\n\n```\n\n## Usage\n\nAttach an `NgModel` or `FormControl` to the input:\n\n```html\n\n\n\n```\n\nWe should _almost always_ being using a `FormControl`.\n\n> Note: If you don't need a full form group you can provide a stand-alone control: `myControl = new FormControl();`\n\n\n### Hint\n\nA 'hint' can be displayed below the input on the right-hand side. This should be used for helpful user information such as input\nrequirements.\n\n```html\n\n```\n\n### No validation or hint\n\nA flag to define whether this input field needs validation or hint. If it needs validation or hint, a padding bottom is added for the message, otherwise, no padding at the bottom.\n\n```html\n\n```\n\n### Prefix icon\n\nTo include an icon as a prefix to the input, pass a valid icon name to `prefixIcon`:\n\n```html\n\n```\n\n> See all valid icon possibilities: https://material.io/icons\n\n\n### Disabled\n\nInputs can be disabled by setting the component flag OR by setting the associated `FormControl` to `disabled`.\n\nThe `isDisabled` flag works with both `ngModel` and `FormControl` inputs:\n\n```html\n\n```\n\nWhen using Reactive Forms, controls should be disabled via the control:\n\n```typescript\nmyControl: FormControl = new FormControl({value: null, disabled: true});\n```\n\n\n### Required\n\nWhen using a `FormControl`, set the required validator on the control:\n\n```typescript\nmyControl = new FormControl(null, Validators.required);\n```\n\nWhen using `ngModel`, validations are placed on the input as data-attributes (just like native HTML inputs):\n\n```html\n\n```\n\nIf only the required asterisk is needed rather than validation errors, the `isRequired` flag can be used:\n\n```html\n\n```\n\n\n#### Required asterisk `*`\n\nIf the input should be required, but the required asterisk `*` is not needed, disable it with the\n`hideRequiredMarker` input:\n\n```html\n\n```\n\n> NOTE: We should not hide this visual indicator without a very good reason!\n\n\n### Clearable\n\nIf the input should be easily reset, include the `isClearable` flag to enable a 'clear input'\nbutton: (button will appear as small `x` icon at the far right of the input)\n\n```html\n\n```\n\nWhen the input is cleared, the `cleared` event emitter will be fired with the value `true`.\n\n\n### Focused\n\nAuto-focus the input when the view loads:\n\n```html\n\n```\n\n> NOTE: If multiple inputs within the same view set `isFocused` to true, the _**last one rendered\n> will receive the final focus**_.\n\nThis can also be used to dynamically focus an existing input:\n\n```html\n\n```\n\n```typescript\nmyFocusedFlag = false;\n\ntoggleInputFocus() {\n this.myFocusedFlag = !this.myFocusedFlag;\n}\n```\n\n\n### Input Type\n\nThe input type can be defined with the type input:\n\n```html\n\n```\n\n> For all allowed types, see `TsInputTypes`.\n\n\n### Input Attributes\n\n`autocapitalize`, `autocomplete`, `spellcheck`, `readonly`\n\n```html\n\n```\n\n> For all allowed `autocomplete` types, see `TsInputAutocompleteTypes`.\n\n\n### Validation timing\n\nValidate on change rather than blur:\n\n```html\n\n```\n\n\n### Component reference\n\nTo get a reference to the component class, assign the exported name to a local variable:\n\n```html\n\n```\n\n```typescript\n@ViewChild(TsInputComponent, {static: false})\nmyVar: TsInputComponent;\n\nconsole.log('Component Class: ', this.myVar);\n```\n\n\n### Usage with Reactive Forms\n\nPass in the form control:\n\n```html\n\n```\n\n```typescript\nmyForm = this.formBuilder.group({\n date: [\n null, // If you need a default value, change this `null` to your value\n [\n Validators.required,\n ],\n ],\n});\n```\n\n**NOTE:** If using a form with nested form groups, _each group_ must be created with\n`formBuilder.group` for the form `get` control to work:\n\n```typescript\n// Notice the nested `dateRange` object without using `.group`\nmyForm: FormGroup = this.formBuilder.group({\n dateRange: {\n startDate: [\n new Date(2017, 4, 6),\n ],\n endDate: [\n new Date(2017, 4, 8),\n ],\n },\n});\n\n// THIS WILL FAIL!\nconst range = myForm.get('dateRange');\n\n//////////////////////////////////////////////////\n\n// Notice the nested `dateRange` object IS using `.group`\nmyForm: FormGroup = this.formBuilder.group({\n dateRange: this.formBuilder.group({\n startDate: [\n new Date(2017, 4, 6),\n [\n Validators.required,\n ],\n ],\n endDate: [\n new Date(2017, 4, 8),\n [\n Validators.required,\n ],\n ],\n }),\n});\n\n// Now there is a group for us to 'get'\nconst range = myForm.get('dateRange');\n```\n\n\n### Event Emitters\n\nSupported event emitters:\n\n```html\n\n```\n\n> NOTE: The `selected` input is only available when `datepicker` is true.\n\n\n### Masks\n\nMasks enable the input to enforce specific formatting for values; such as postal codes: `12345-1234`.\n\n\n#### Available Masks\n\n| Mask | Input value | Masked Value |\n|--------------|--------------|------------------|\n| `currency` | `12.34` | `$12.34` |\n| `date` | `12121982` | `12-12-1982` |\n| `number` | `1234.56` | `1,234.56` |\n| `percentage` | `12.4` | `12.4%` |\n| `phone` | `1231231234` | `(123) 123-1234` |\n| `postal` | `123456789` | `12345-6789` |\n\n\n#### Sanitize the model value\n\nMost often you will not want the mask characters to be saved as part of the actual value. By default this component will sanitize the value\nbefore saving it to the model. This can be disabled if needed:\n\n```html\n\n```\n\nThis setup will format the value displayed in the UI: `(123) 456-7890`)while saving the pure value to the model: `1234567890`.\n\n\n#### Allow decimals in number-based masks\n\nBy default, number based masks (`number`, `percentage`) allow decimals. This can be disabled:\n\n```html\n\n```\n\nThis means when the user types `12.34`, the input UI and model value will both be `1234`.\n\n\n### Datepicker\n\nTo add datepicker abilities to an input, set the `datepicker` input:\n\n```html\n\n```\n\n\n#### Filter out available dates\n\nIf, for instance, you need to prohibit weekend days (sat/sun) from being selected you can pass in a\ncustom method to filter dates:\n\n```html\n\n```\n\n```typescript\nmyFilter = (d: Date): boolean => {\n const day = d.getDay();\n // Prevent Saturday and Sunday from being selected.\n return day !== 0 && day !== 6;\n}\n```\n\n\n#### Set a max/min date range\n\nTo define bounds for date selection, pass in a valid `Date` to `minDate` and/or `maxDate`:\n\n```html\n\n```\n\n```typescript\ndate1 = new Date(2017, 2, 1);\ndate2 = new Date(2017, 8, 1);\n```\n\n\n#### Open calendar to a specific date\n\nPass in a `Date` to `openTo`:\n\n```html\n\n```\n\n```typescript\nmyDate = new Date(2017, 5, 12);\n```\n\n\n#### Open calendar to a specific view\n\nBy default, the calendar opens up to show the month view. This can be changed to show the year view initially:\n\n```html\n\n```\n\n`year` and `month` are the only two valid values.\n\n\n#### Example with dynamic validation\n\nWe can recreate a version of the {@link TsDateRangeComponent} using dynamic validation:\n\n```html\n\n```\n\n```typescript\nmyForm = this.formBuilder.group({\n startDate: [\n null,\n [\n Validators.required,\n ],\n ],\n endDate: [\n null,\n [\n Validators.required,\n ],\n ],\n});\n\n// When the startDate changes, we want to set that date as the minDate for the endDate\nrangeStartChange(event: MatDatepickerInputEvent) {\n if (event) {\n // Get the from control\n const control = this.formTwo.get('endDate');\n\n // Set all validators.\n // NOTE: setting validators will clear ALL existing validators, so we must add the required\n // validator here again\n control.setValidators([\n Validators.required,\n this.validatorsService.minDate(event.value),\n ]);\n // Tell the control to update according to the new validators\n control.updateValueAndValidity();\n }\n}\n\n// When the endDate changes, we want to set that date as the maxDate for the startDate\nrangeEndChange(event: MatDatepickerInputEvent) {\n if (event) {\n // Get the from control\n const control = this.formTwo.get('startDate');\n\n // Set all validators.\n // NOTE: setting validators will clear ALL existing validators, so we must add the required\n // validator here again\n control.setValidators([\n Validators.required,\n this.validatorsService.maxDate(event.value),\n ]);\n // Tell the control to update according to the new validators\n control.updateValueAndValidity();\n }\n}\n```\n\n\n### Textarea\n\nSwitch from a standard input to a textarea:\n\n```html\n\n```\n\n#### Rows\n\nThe row count can be dynamically adjusted:\n\n```html\n\n```\n\n\n## Test Helpers\n\nSome helpers are exposed to assist with testing. These are imported from `@terminus/ui-input/testing`;\n\n[[source]][test-helpers-src]\n\n| Function |\n|------------------------|\n| `getAllInputInstances` |\n| `getInputInstance` |\n| `getInputElement` |\n| `sendInput` |\n\n\n\n\n[test-helpers-src]: testing/src/test-helpers.ts\n[license-url]: https://github.com/GetTerminus/terminus-oss/blob/release/LICENSE\n[license-image]: http://img.shields.io/badge/license-MIT-blue.svg\n[codecov-project]: https://codecov.io/gh/GetTerminus/terminus-oss\n[codecov-badge]: https://codecov.io/gh/GetTerminus/terminus-oss/branch/release/graph/badge.svg\n[npm-version-image]: http://img.shields.io/npm/v/@terminus/ui-input.svg\n[npm-package]: https://www.npmjs.com/package/@terminus/ui-input\n[gh-release-badge]: https://img.shields.io/github/release/GetTerminus/terminus-oss.svg\n[gh-releases]: https://github.com/GetTerminus/terminus-ui/releases/\n[github-action-badge]: https://github.com/GetTerminus/terminus-oss/workflows/Release%20CI/badge.svg\n[github-action-link]: https://github.com/GetTerminus/terminus-oss/actions?query=workflow%3A%22CI+Release%22\n[file-size-badge]: http://img.badgesize.io/https://unpkg.com/@terminus/ui-input/bundles/terminus-ui-input.umd.min.js?compression=gzip\n[raw-distribution-js]: https://unpkg.com/@terminus/ui-input/bundles/terminus-ui-input.umd.js\n","readmeFilename":"README.md","description":"
\n\n[![CI/CD Status][github-action-badge]][github-action-link] [![Codecov][codecov-badge]][codecov-project] [![MIT License][license-image]][license-url] \n[![NPM version][npm-version-image]][npm-package] [![Library size][file-size-badge]][raw-distribution-js]\n\n\n\n**Table of Contents**\n\n- [Installation](#installation)\n - [Packages that need to be installed](#packages-that-need-to-be-installed)\n - [Modules that need to be in NgModule](#modules-that-need-to-be-in-ngmodule)\n - [CSS imports](#css-imports)\n - [CSS resources](#css-resources)\n- [Usage](#usage)\n - [Hint](#hint)\n - [No validation or hint](#no-validation-or-hint)\n - [Prefix icon](#prefix-icon)\n - [Disabled](#disabled)\n - [Required](#required)\n - [Required asterisk `*`](#required-asterisk-)\n - [Clearable](#clearable)\n - [Focused](#focused)\n - [Input Type](#input-type)\n - [Input Attributes](#input-attributes)\n - [Validation timing](#validation-timing)\n - [Component reference](#component-reference)\n - [Usage with Reactive Forms](#usage-with-reactive-forms)\n - [Event Emitters](#event-emitters)\n - [Masks](#masks)\n - [Available Masks](#available-masks)\n - [Sanitize the model value](#sanitize-the-model-value)\n - [Allow decimals in number-based masks](#allow-decimals-in-number-based-masks)\n - [Datepicker](#datepicker)\n - [Filter out available dates](#filter-out-available-dates)\n - [Set a max/min date range](#set-a-maxmin-date-range)\n - [Open calendar to a specific date](#open-calendar-to-a-specific-date)\n - [Open calendar to a specific view](#open-calendar-to-a-specific-view)\n - [Example with dynamic validation](#example-with-dynamic-validation)\n - [Textarea](#textarea)\n - [Rows](#rows)\n- [Test Helpers](#test-helpers)\n\n\n\n## Installation\n\n### Packages that need to be installed\n\n- `@angular/cdk`\n- `@angular/flex-layout`\n- `@angular/material`\n- `@terminus/design-tokens`\n- `@terminus/ngx-tools`\n- `@terminus/ui-form-field`\n- `@terminus/ui-icon`\n- `@terminus/ui-input`\n- `@terminus/ui-pipes`\n- `@terminus/ui-spacing`\n- `@terminus/ui-styles`\n- `@terminus/ui-utilities`\n- `@terminus/ui-validation-messages`\n- `@terminus/ui-validators`\n- `date-fns`\n- `text-mask-addons`\n- `text-mask-core`\n\nUse the `ng add` command to quickly install all the needed dependencies:\n\n```bash\nng add @terminus/ui-input\n```\n\n### Modules that need to be in NgModule\n\n- `BrowserAnimationsModule`\n- `TsInputModule`\n- `FormsModule`\n- `ReactiveFormsModule`\n\n### CSS imports\n\nIn your top level stylesheet, add these imports:\n\n```css\n@import '~@terminus/design-tokens/css/library-design-tokens.css';\n@import '~@terminus/ui-styles/terminus-ui.css';\n``` \n\n### CSS resources\n\nLoad the needed font families by adding this link to the `` of your application:\n\n```css\n\n```\n\n## Usage\n\nAttach an `NgModel` or `FormControl` to the input:\n\n```html\n\n\n\n```\n\nWe should _almost always_ being using a `FormControl`.\n\n> Note: If you don't need a full form group you can provide a stand-alone control: `myControl = new FormControl();`\n\n### Hint\n\nA 'hint' can be displayed below the input on the right-hand side. This should be used for helpful user information such as input\nrequirements.\n\n```html\n\n```\n\n### No validation or hint\n\nA flag to define whether this input field needs validation or hint. If it needs validation or hint, a padding bottom is added for the message, otherwise, no padding at the bottom.\n\n```html\n\n```\n\n### Prefix icon\n\nTo include an icon as a prefix to the input, pass a valid icon name to `prefixIcon`:\n\n```html\n\n```\n\n> See all valid icon possibilities: https://material.io/icons\n\n### Disabled\n\nInputs can be disabled by setting the component flag OR by setting the associated `FormControl` to `disabled`.\n\nThe `isDisabled` flag works with both `ngModel` and `FormControl` inputs:\n\n```html\n\n```\n\nWhen using Reactive Forms, controls should be disabled via the control:\n\n```typescript\nmyControl: FormControl = new FormControl({value: null, disabled: true});\n```\n\n### Required\n\nWhen using a `FormControl`, set the required validator on the control:\n\n```typescript\nmyControl = new FormControl(null, Validators.required);\n```\n\nWhen using `ngModel`, validations are placed on the input as data-attributes (just like native HTML inputs):\n\n```html\n\n```\n\nIf only the required asterisk is needed rather than validation errors, the `isRequired` flag can be used:\n\n```html\n\n```\n\n#### Required asterisk `*`\n\nIf the input should be required, but the required asterisk `*` is not needed, disable it with the\n`hideRequiredMarker` input:\n\n```html\n\n```\n\n> NOTE: We should not hide this visual indicator without a very good reason!\n\n### Clearable\n\nIf the input should be easily reset, include the `isClearable` flag to enable a 'clear input'\nbutton: (button will appear as small `x` icon at the far right of the input)\n\n```html\n\n```\n\nWhen the input is cleared, the `cleared` event emitter will be fired with the value `true`.\n\n### Focused\n\nAuto-focus the input when the view loads:\n\n```html\n\n```\n\n> NOTE: If multiple inputs within the same view set `isFocused` to true, the _**last one rendered\n> will receive the final focus**_.\n\nThis can also be used to dynamically focus an existing input:\n\n```html\n\n```\n\n```typescript\nmyFocusedFlag = false;\n\ntoggleInputFocus() {\n this.myFocusedFlag = !this.myFocusedFlag;\n}\n```\n\n### Input Type\n\nThe input type can be defined with the type input:\n\n```html\n\n```\n\n> For all allowed types, see `TsInputTypes`.\n\n### Input Attributes\n\n`autocapitalize`, `autocomplete`, `spellcheck`, `readonly`\n\n```html\n\n```\n\n> For all allowed `autocomplete` types, see `TsInputAutocompleteTypes`.\n\n### Validation timing\n\nValidate on change rather than blur:\n\n```html\n\n```\n\n### Component reference\n\nTo get a reference to the component class, assign the exported name to a local variable:\n\n```html\n\n```\n\n```typescript\n@ViewChild(TsInputComponent, {static: false})\nmyVar: TsInputComponent;\n\nconsole.log('Component Class: ', this.myVar);\n```\n\n### Usage with Reactive Forms\n\nPass in the form control:\n\n```html\n\n```\n\n```typescript\nmyForm = this.formBuilder.group({\n date: [\n null, // If you need a default value, change this `null` to your value\n [\n Validators.required,\n ],\n ],\n});\n```\n\n**NOTE:** If using a form with nested form groups, _each group_ must be created with\n`formBuilder.group` for the form `get` control to work:\n\n```typescript\n// Notice the nested `dateRange` object without using `.group`\nmyForm: FormGroup = this.formBuilder.group({\n dateRange: {\n startDate: [\n new Date(2017, 4, 6),\n ],\n endDate: [\n new Date(2017, 4, 8),\n ],\n },\n});\n\n// THIS WILL FAIL!\nconst range = myForm.get('dateRange');\n\n//////////////////////////////////////////////////\n\n// Notice the nested `dateRange` object IS using `.group`\nmyForm: FormGroup = this.formBuilder.group({\n dateRange: this.formBuilder.group({\n startDate: [\n new Date(2017, 4, 6),\n [\n Validators.required,\n ],\n ],\n endDate: [\n new Date(2017, 4, 8),\n [\n Validators.required,\n ],\n ],\n }),\n});\n\n// Now there is a group for us to 'get'\nconst range = myForm.get('dateRange');\n```\n\n### Event Emitters\n\nSupported event emitters:\n\n```html\n\n```\n\n> NOTE: The `selected` input is only available when `datepicker` is true.\n\n### Masks\n\nMasks enable the input to enforce specific formatting for values; such as postal codes: `12345-1234`.\n\n#### Available Masks\n\n| Mask | Input value | Masked Value |\n|--------------|--------------|------------------|\n| `currency` | `12.34` | `$12.34` |\n| `date` | `12121982` | `12-12-1982` |\n| `number` | `1234.56` | `1,234.56` |\n| `percentage` | `12.4` | `12.4%` |\n| `phone` | `1231231234` | `(123) 123-1234` |\n| `postal` | `123456789` | `12345-6789` |\n\n\n#### Sanitize the model value\n\nMost often you will not want the mask characters to be saved as part of the actual value. By default this component will sanitize the value\nbefore saving it to the model. This can be disabled if needed:\n\n```html\n\n```\n\nThis setup will format the value displayed in the UI: `(123) 456-7890`)while saving the pure value to the model: `1234567890`.\n\n#### Allow decimals in number-based masks\n\nBy default, number based masks (`number`, `percentage`) allow decimals. This can be disabled:\n\n```html\n\n```\n\nThis means when the user types `12.34`, the input UI and model value will both be `1234`.\n\n### Datepicker\n\nTo add datepicker abilities to an input, set the `datepicker` input:\n\n```html\n\n```\n\n\n#### Filter out available dates\n\nIf, for instance, you need to prohibit weekend days (sat/sun) from being selected you can pass in a\ncustom method to filter dates:\n\n```html\n\n```\n\n```typescript\nmyFilter = (d: Date): boolean => {\n const day = d.getDay();\n // Prevent Saturday and Sunday from being selected.\n return day !== 0 && day !== 6;\n}\n```\n\n#### Set a max/min date range\n\nTo define bounds for date selection, pass in a valid `Date` to `minDate` and/or `maxDate`:\n\n```html\n\n```\n\n```typescript\ndate1 = new Date(2017, 2, 1);\ndate2 = new Date(2017, 8, 1);\n```\n\n#### Open calendar to a specific date\n\nPass in a `Date` to `openTo`:\n\n```html\n\n```\n\n```typescript\nmyDate = new Date(2017, 5, 12);\n```\n\n#### Open calendar to a specific view\n\nBy default, the calendar opens up to show the month view. This can be changed to show the year view initially:\n\n```html\n\n```\n\n`year` and `month` are the only two valid values.\n\n#### Example with dynamic validation\n\nWe can recreate a version of the {@link TsDateRangeComponent} using dynamic validation:\n\n```html\n\n```\n\n```typescript\nmyForm = this.formBuilder.group({\n startDate: [\n null,\n [\n Validators.required,\n ],\n ],\n endDate: [\n null,\n [\n Validators.required,\n ],\n ],\n});\n\n// When the startDate changes, we want to set that date as the minDate for the endDate\nrangeStartChange(event: MatDatepickerInputEvent) {\n if (event) {\n // Get the from control\n const control = this.formTwo.get('endDate');\n\n // Set all validators.\n // NOTE: setting validators will clear ALL existing validators, so we must add the required\n // validator here again\n control.setValidators([\n Validators.required,\n this.validatorsService.minDate(event.value),\n ]);\n // Tell the control to update according to the new validators\n control.updateValueAndValidity();\n }\n}\n\n// When the endDate changes, we want to set that date as the maxDate for the startDate\nrangeEndChange(event: MatDatepickerInputEvent) {\n if (event) {\n // Get the from control\n const control = this.formTwo.get('startDate');\n\n // Set all validators.\n // NOTE: setting validators will clear ALL existing validators, so we must add the required\n // validator here again\n control.setValidators([\n Validators.required,\n this.validatorsService.maxDate(event.value),\n ]);\n // Tell the control to update according to the new validators\n control.updateValueAndValidity();\n }\n}\n```\n\n### Textarea\n\nSwitch from a standard input to a textarea:\n\n```html\n\n```\n\n#### Rows\n\nThe row count can be dynamically adjusted:\n\n```html\n\n```\n\n## Test Helpers\n\nSome helpers are exposed to assist with testing. These are imported from `@terminus/ui-input/testing`;\n\n[[source]][test-helpers-src]\n\n| Function |\n|------------------------|\n| `getAllInputInstances` |\n| `getInputInstance` |\n| `getInputElement` |\n| `sendInput` |\n\n\n\n[test-helpers-src]: testing/src/test-helpers.ts\n[license-url]: https://github.com/GetTerminus/terminus-oss/blob/release/LICENSE\n[license-image]: http://img.shields.io/badge/license-MIT-blue.svg\n[codecov-project]: https://codecov.io/gh/GetTerminus/terminus-oss\n[codecov-badge]: https://codecov.io/gh/GetTerminus/terminus-oss/branch/release/graph/badge.svg\n[npm-version-image]: http://img.shields.io/npm/v/@terminus/ui-input.svg\n[npm-package]: https://www.npmjs.com/package/@terminus/ui-input\n[github-action-badge]: https://github.com/GetTerminus/terminus-oss/workflows/Release%20CI/badge.svg\n[github-action-link]: https://github.com/GetTerminus/terminus-oss/actions?query=workflow%3A%22CI+Release%22\n[file-size-badge]: http://img.badgesize.io/https://unpkg.com/@terminus/ui-input/bundles/terminus-ui-input.umd.min.js?compression=gzip\n[raw-distribution-js]: https://unpkg.com/@terminus/ui-input/bundles/terminus-ui-input.umd.js\n","readmeFilename":"README.md","description":"
\n\n[![CI/CD Status][github-action-badge]][github-action-link] [![Codecov][codecov-badge]][codecov-project] [![MIT License][license-image]][license-url] \n[![NPM version][npm-version-image]][npm-package] [![Library size][file-size-badge]][raw-distribution-js]\n\n\n\n**Table of Contents**\n\n- [Installation](#installation)\n - [Packages that need to be installed](#packages-that-need-to-be-installed)\n - [Modules that need to be in NgModule](#modules-that-need-to-be-in-ngmodule)\n - [CSS imports](#css-imports)\n - [CSS resources](#css-resources)\n- [Usage](#usage)\n - [Hint](#hint)\n - [No validation or hint](#no-validation-or-hint)\n - [Prefix icon](#prefix-icon)\n - [Disabled](#disabled)\n - [Required](#required)\n - [Required asterisk `*`](#required-asterisk-)\n - [Clearable](#clearable)\n - [Focused](#focused)\n - [Input Type](#input-type)\n - [Input Attributes](#input-attributes)\n - [Validation timing](#validation-timing)\n - [Component reference](#component-reference)\n - [Usage with Reactive Forms](#usage-with-reactive-forms)\n - [Event Emitters](#event-emitters)\n - [Masks](#masks)\n - [Available Masks](#available-masks)\n - [Sanitize the model value](#sanitize-the-model-value)\n - [Allow decimals in number-based masks](#allow-decimals-in-number-based-masks)\n - [Datepicker](#datepicker)\n - [Filter out available dates](#filter-out-available-dates)\n - [Set a max/min date range](#set-a-maxmin-date-range)\n - [Open calendar to a specific date](#open-calendar-to-a-specific-date)\n - [Open calendar to a specific view](#open-calendar-to-a-specific-view)\n - [Example with dynamic validation](#example-with-dynamic-validation)\n - [Textarea](#textarea)\n - [Rows](#rows)\n- [Test Helpers](#test-helpers)\n\n\n\n## Installation\n\n### Packages that need to be installed\n\n- `@angular/cdk`\n- `@angular/flex-layout`\n- `@angular/material`\n- `@terminus/design-tokens`\n- `@terminus/ngx-tools`\n- `@terminus/ui-form-field`\n- `@terminus/ui-icon`\n- `@terminus/ui-input`\n- `@terminus/ui-pipes`\n- `@terminus/ui-spacing`\n- `@terminus/ui-styles`\n- `@terminus/ui-utilities`\n- `@terminus/ui-validation-messages`\n- `@terminus/ui-validators`\n- `date-fns`\n- `text-mask-addons`\n- `text-mask-core`\n\nUse the `ng add` command to quickly install all the needed dependencies:\n\n```bash\nng add @terminus/ui-input\n```\n\n### Modules that need to be in NgModule\n\n- `BrowserAnimationsModule`\n- `TsInputModule`\n- `FormsModule`\n- `ReactiveFormsModule`\n\n### CSS imports\n\nIn your top level stylesheet, add these imports:\n\n```css\n@import '~@terminus/design-tokens/css/library-design-tokens.css';\n@import '~@terminus/ui-styles/terminus-ui.css';\n``` \n\n### CSS resources\n\nLoad the needed font families by adding this link to the `` of your application:\n\n```css\n\n```\n\n## Usage\n\nAttach an `NgModel` or `FormControl` to the input:\n\n```html\n\n\n\n```\n\nWe should _almost always_ being using a `FormControl`.\n\n> Note: If you don't need a full form group you can provide a stand-alone control: `myControl = new FormControl();`\n\n### Hint\n\nA 'hint' can be displayed below the input on the right-hand side. This should be used for helpful user information such as input\nrequirements.\n\n```html\n\n```\n\n### No validation or hint\n\nA flag to define whether this input field needs validation or hint. If it needs validation or hint, a padding bottom is added for the message, otherwise, no padding at the bottom.\n\n```html\n\n```\n\n### Prefix icon\n\nTo include an icon as a prefix to the input, pass a valid icon name to `prefixIcon`:\n\n```html\n\n```\n\n> See all valid icon possibilities: https://material.io/icons\n\n### Disabled\n\nInputs can be disabled by setting the component flag OR by setting the associated `FormControl` to `disabled`.\n\nThe `isDisabled` flag works with both `ngModel` and `FormControl` inputs:\n\n```html\n\n```\n\nWhen using Reactive Forms, controls should be disabled via the control:\n\n```typescript\nmyControl: FormControl = new FormControl({value: null, disabled: true});\n```\n\n### Required\n\nWhen using a `FormControl`, set the required validator on the control:\n\n```typescript\nmyControl = new FormControl(null, Validators.required);\n```\n\nWhen using `ngModel`, validations are placed on the input as data-attributes (just like native HTML inputs):\n\n```html\n\n```\n\nIf only the required asterisk is needed rather than validation errors, the `isRequired` flag can be used:\n\n```html\n\n```\n\n#### Required asterisk `*`\n\nIf the input should be required, but the required asterisk `*` is not needed, disable it with the\n`hideRequiredMarker` input:\n\n```html\n\n```\n\n> NOTE: We should not hide this visual indicator without a very good reason!\n\n### Clearable\n\nIf the input should be easily reset, include the `isClearable` flag to enable a 'clear input'\nbutton: (button will appear as small `x` icon at the far right of the input)\n\n```html\n\n```\n\nWhen the input is cleared, the `cleared` event emitter will be fired with the value `true`.\n\n### Focused\n\nAuto-focus the input when the view loads:\n\n```html\n\n```\n\n> NOTE: If multiple inputs within the same view set `isFocused` to true, the _**last one rendered\n> will receive the final focus**_.\n\nThis can also be used to dynamically focus an existing input:\n\n```html\n\n```\n\n```typescript\nmyFocusedFlag = false;\n\ntoggleInputFocus() {\n this.myFocusedFlag = !this.myFocusedFlag;\n}\n```\n\n### Input Type\n\nThe input type can be defined with the type input:\n\n```html\n\n```\n\n> For all allowed types, see `TsInputTypes`.\n\n### Input Attributes\n\n`autocapitalize`, `autocomplete`, `spellcheck`, `readonly`\n\n```html\n\n```\n\n> For all allowed `autocomplete` types, see `TsInputAutocompleteTypes`.\n\n### Validation timing\n\nValidate on change rather than blur:\n\n```html\n\n```\n\n### Component reference\n\nTo get a reference to the component class, assign the exported name to a local variable:\n\n```html\n\n```\n\n```typescript\n@ViewChild(TsInputComponent, {static: false})\nmyVar: TsInputComponent;\n\nconsole.log('Component Class: ', this.myVar);\n```\n\n### Usage with Reactive Forms\n\nPass in the form control:\n\n```html\n\n```\n\n```typescript\nmyForm = this.formBuilder.group({\n date: [\n null, // If you need a default value, change this `null` to your value\n [\n Validators.required,\n ],\n ],\n});\n```\n\n**NOTE:** If using a form with nested form groups, _each group_ must be created with\n`formBuilder.group` for the form `get` control to work:\n\n```typescript\n// Notice the nested `dateRange` object without using `.group`\nmyForm: FormGroup = this.formBuilder.group({\n dateRange: {\n startDate: [\n new Date(2017, 4, 6),\n ],\n endDate: [\n new Date(2017, 4, 8),\n ],\n },\n});\n\n// THIS WILL FAIL!\nconst range = myForm.get('dateRange');\n\n//////////////////////////////////////////////////\n\n// Notice the nested `dateRange` object IS using `.group`\nmyForm: FormGroup = this.formBuilder.group({\n dateRange: this.formBuilder.group({\n startDate: [\n new Date(2017, 4, 6),\n [\n Validators.required,\n ],\n ],\n endDate: [\n new Date(2017, 4, 8),\n [\n Validators.required,\n ],\n ],\n }),\n});\n\n// Now there is a group for us to 'get'\nconst range = myForm.get('dateRange');\n```\n\n### Event Emitters\n\nSupported event emitters:\n\n```html\n\n```\n\n> NOTE: The `selected` input is only available when `datepicker` is true.\n\n### Masks\n\nMasks enable the input to enforce specific formatting for values; such as postal codes: `12345-1234`.\n\n#### Available Masks\n\n| Mask | Input value | Masked Value |\n|--------------|--------------|------------------|\n| `currency` | `12.34` | `$12.34` |\n| `date` | `12121982` | `12-12-1982` |\n| `number` | `1234.56` | `1,234.56` |\n| `percentage` | `12.4` | `12.4%` |\n| `phone` | `1231231234` | `(123) 123-1234` |\n| `postal` | `123456789` | `12345-6789` |\n\n\n#### Sanitize the model value\n\nMost often you will not want the mask characters to be saved as part of the actual value. By default this component will sanitize the value\nbefore saving it to the model. This can be disabled if needed:\n\n```html\n\n```\n\nThis setup will format the value displayed in the UI: `(123) 456-7890`)while saving the pure value to the model: `1234567890`.\n\n#### Allow decimals in number-based masks\n\nBy default, number based masks (`number`, `percentage`) allow decimals. This can be disabled:\n\n```html\n\n```\n\nThis means when the user types `12.34`, the input UI and model value will both be `1234`.\n\n### Datepicker\n\nTo add datepicker abilities to an input, set the `datepicker` input:\n\n```html\n\n```\n\n\n#### Filter out available dates\n\nIf, for instance, you need to prohibit weekend days (sat/sun) from being selected you can pass in a\ncustom method to filter dates:\n\n```html\n\n```\n\n```typescript\nmyFilter = (d: Date): boolean => {\n const day = d.getDay();\n // Prevent Saturday and Sunday from being selected.\n return day !== 0 && day !== 6;\n}\n```\n\n#### Set a max/min date range\n\nTo define bounds for date selection, pass in a valid `Date` to `minDate` and/or `maxDate`:\n\n```html\n\n```\n\n```typescript\ndate1 = new Date(2017, 2, 1);\ndate2 = new Date(2017, 8, 1);\n```\n\n#### Open calendar to a specific date\n\nPass in a `Date` to `openTo`:\n\n```html\n\n```\n\n```typescript\nmyDate = new Date(2017, 5, 12);\n```\n\n#### Open calendar to a specific view\n\nBy default, the calendar opens up to show the month view. This can be changed to show the year view initially:\n\n```html\n\n```\n\n`year` and `month` are the only two valid values.\n\n#### Example with dynamic validation\n\nWe can recreate a version of the {@link TsDateRangeComponent} using dynamic validation:\n\n```html\n\n```\n\n```typescript\nmyForm = this.formBuilder.group({\n startDate: [\n null,\n [\n Validators.required,\n ],\n ],\n endDate: [\n null,\n [\n Validators.required,\n ],\n ],\n});\n\n// When the startDate changes, we want to set that date as the minDate for the endDate\nrangeStartChange(event: MatDatepickerInputEvent) {\n if (event) {\n // Get the from control\n const control = this.formTwo.get('endDate');\n\n // Set all validators.\n // NOTE: setting validators will clear ALL existing validators, so we must add the required\n // validator here again\n control.setValidators([\n Validators.required,\n this.validatorsService.minDate(event.value),\n ]);\n // Tell the control to update according to the new validators\n control.updateValueAndValidity();\n }\n}\n\n// When the endDate changes, we want to set that date as the maxDate for the startDate\nrangeEndChange(event: MatDatepickerInputEvent) {\n if (event) {\n // Get the from control\n const control = this.formTwo.get('startDate');\n\n // Set all validators.\n // NOTE: setting validators will clear ALL existing validators, so we must add the required\n // validator here again\n control.setValidators([\n Validators.required,\n this.validatorsService.maxDate(event.value),\n ]);\n // Tell the control to update according to the new validators\n control.updateValueAndValidity();\n }\n}\n```\n\n### Textarea\n\nSwitch from a standard input to a textarea:\n\n```html\n\n```\n\n#### Rows\n\nThe row count can be dynamically adjusted:\n\n```html\n\n```\n\n## Test Helpers\n\nSome helpers are exposed to assist with testing. These are imported from `@terminus/ui-input/testing`;\n\n[[source]][test-helpers-src]\n\n| Function |\n|------------------------|\n| `getAllInputInstances` |\n| `getInputInstance` |\n| `getInputElement` |\n| `sendInput` |\n\n\n\n[test-helpers-src]: testing/src/test-helpers.ts\n[license-url]: https://github.com/GetTerminus/terminus-oss/blob/release/LICENSE\n[license-image]: http://img.shields.io/badge/license-MIT-blue.svg\n[codecov-project]: https://codecov.io/gh/GetTerminus/terminus-oss\n[codecov-badge]: https://codecov.io/gh/GetTerminus/terminus-oss/branch/release/graph/badge.svg\n[npm-version-image]: http://img.shields.io/npm/v/@terminus/ui-input.svg\n[npm-package]: https://www.npmjs.com/package/@terminus/ui-input\n[github-action-badge]: https://github.com/GetTerminus/terminus-oss/workflows/Release%20CI/badge.svg\n[github-action-link]: https://github.com/GetTerminus/terminus-oss/actions?query=workflow%3A%22CI+Release%22\n[file-size-badge]: http://img.badgesize.io/https://unpkg.com/@terminus/ui-input/bundles/terminus-ui-input.umd.min.js?compression=gzip\n[raw-distribution-js]: https://unpkg.com/@terminus/ui-input/bundles/terminus-ui-input.umd.js\n","readmeFilename":"README.md","description":"
\n\n[![CI/CD Status][github-action-badge]][github-action-link] [![Codecov][codecov-badge]][codecov-project] [![MIT License][license-image]][license-url] \n[![NPM version][npm-version-image]][npm-package] [![Library size][file-size-badge]][raw-distribution-js]\n\n\n\n**Table of Contents**\n\n- [Installation](#installation)\n - [Packages that need to be installed](#packages-that-need-to-be-installed)\n - [Modules that need to be in NgModule](#modules-that-need-to-be-in-ngmodule)\n - [CSS imports](#css-imports)\n - [CSS resources](#css-resources)\n- [Usage](#usage)\n - [Hint](#hint)\n - [No validation or hint](#no-validation-or-hint)\n - [Prefix icon](#prefix-icon)\n - [Disabled](#disabled)\n - [Required](#required)\n - [Required asterisk `*`](#required-asterisk-)\n - [Clearable](#clearable)\n - [Focused](#focused)\n - [Input Type](#input-type)\n - [Input Attributes](#input-attributes)\n - [Validation timing](#validation-timing)\n - [Component reference](#component-reference)\n - [Usage with Reactive Forms](#usage-with-reactive-forms)\n - [Event Emitters](#event-emitters)\n - [Masks](#masks)\n - [Available Masks](#available-masks)\n - [Sanitize the model value](#sanitize-the-model-value)\n - [Allow decimals in number-based masks](#allow-decimals-in-number-based-masks)\n - [Datepicker](#datepicker)\n - [Filter out available dates](#filter-out-available-dates)\n - [Set a max/min date range](#set-a-maxmin-date-range)\n - [Open calendar to a specific date](#open-calendar-to-a-specific-date)\n - [Open calendar to a specific view](#open-calendar-to-a-specific-view)\n - [Example with dynamic validation](#example-with-dynamic-validation)\n - [Textarea](#textarea)\n - [Rows](#rows)\n- [Test Helpers](#test-helpers)\n\n\n\n## Installation\n\n### Packages that need to be installed\n\n- `@angular/cdk`\n- `@angular/flex-layout`\n- `@angular/material`\n- `@terminus/design-tokens`\n- `@terminus/fe-utilities`\n- `@terminus/ui-form-field`\n- `@terminus/ui-icon`\n- `@terminus/ui-input`\n- `@terminus/ui-pipes`\n- `@terminus/ui-spacing`\n- `@terminus/ui-styles`\n- `@terminus/ui-utilities`\n- `@terminus/ui-validation-messages`\n- `@terminus/ui-validators`\n- `date-fns`\n- `text-mask-addons`\n- `text-mask-core`\n\nUse the `ng add` command to quickly install all the needed dependencies:\n\n```bash\nng add @terminus/ui-input\n```\n\n### Modules that need to be in NgModule\n\n- `BrowserAnimationsModule`\n- `TsInputModule`\n- `FormsModule`\n- `ReactiveFormsModule`\n\n### CSS imports\n\nIn your top level stylesheet, add these imports:\n\n```css\n@import '~@terminus/design-tokens/css/library-design-tokens.css';\n@import '~@terminus/ui-styles/terminus-ui.css';\n``` \n\n### CSS resources\n\nLoad the needed font families by adding this link to the `` of your application:\n\n```css\n\n```\n\n## Usage\n\nAttach an `NgModel` or `FormControl` to the input:\n\n```html\n\n\n\n```\n\nWe should _almost always_ being using a `FormControl`.\n\n> Note: If you don't need a full form group you can provide a stand-alone control: `myControl = new FormControl();`\n\n### Hint\n\nA 'hint' can be displayed below the input on the right-hand side. This should be used for helpful user information such as input\nrequirements.\n\n```html\n\n```\n\n### No validation or hint\n\nA flag to define whether this input field needs validation or hint. If it needs validation or hint, a padding bottom is added for the message, otherwise, no padding at the bottom.\n\n```html\n\n```\n\n### Prefix icon\n\nTo include an icon as a prefix to the input, pass a valid icon name to `prefixIcon`:\n\n```html\n\n```\n\n> See all valid icon possibilities: https://material.io/icons\n\n### Disabled\n\nInputs can be disabled by setting the component flag OR by setting the associated `FormControl` to `disabled`.\n\nThe `isDisabled` flag works with both `ngModel` and `FormControl` inputs:\n\n```html\n\n```\n\nWhen using Reactive Forms, controls should be disabled via the control:\n\n```typescript\nmyControl: FormControl = new FormControl({value: null, disabled: true});\n```\n\n### Required\n\nWhen using a `FormControl`, set the required validator on the control:\n\n```typescript\nmyControl = new FormControl(null, Validators.required);\n```\n\nWhen using `ngModel`, validations are placed on the input as data-attributes (just like native HTML inputs):\n\n```html\n\n```\n\nIf only the required asterisk is needed rather than validation errors, the `isRequired` flag can be used:\n\n```html\n\n```\n\n#### Required asterisk `*`\n\nIf the input should be required, but the required asterisk `*` is not needed, disable it with the\n`hideRequiredMarker` input:\n\n```html\n\n```\n\n> NOTE: We should not hide this visual indicator without a very good reason!\n\n### Clearable\n\nIf the input should be easily reset, include the `isClearable` flag to enable a 'clear input'\nbutton: (button will appear as small `x` icon at the far right of the input)\n\n```html\n\n```\n\nWhen the input is cleared, the `cleared` event emitter will be fired with the value `true`.\n\n### Focused\n\nAuto-focus the input when the view loads:\n\n```html\n\n```\n\n> NOTE: If multiple inputs within the same view set `isFocused` to true, the _**last one rendered\n> will receive the final focus**_.\n\nThis can also be used to dynamically focus an existing input:\n\n```html\n\n```\n\n```typescript\nmyFocusedFlag = false;\n\ntoggleInputFocus() {\n this.myFocusedFlag = !this.myFocusedFlag;\n}\n```\n\n### Input Type\n\nThe input type can be defined with the type input:\n\n```html\n\n```\n\n> For all allowed types, see `TsInputTypes`.\n\n### Input Attributes\n\n`autocapitalize`, `autocomplete`, `spellcheck`, `readonly`\n\n```html\n\n```\n\n> For all allowed `autocomplete` types, see `TsInputAutocompleteTypes`.\n\n### Validation timing\n\nValidate on change rather than blur:\n\n```html\n\n```\n\n### Component reference\n\nTo get a reference to the component class, assign the exported name to a local variable:\n\n```html\n\n```\n\n```typescript\n@ViewChild(TsInputComponent, {static: false})\nmyVar: TsInputComponent;\n\nconsole.log('Component Class: ', this.myVar);\n```\n\n### Usage with Reactive Forms\n\nPass in the form control:\n\n```html\n\n```\n\n```typescript\nmyForm = this.formBuilder.group({\n date: [\n null, // If you need a default value, change this `null` to your value\n [\n Validators.required,\n ],\n ],\n});\n```\n\n**NOTE:** If using a form with nested form groups, _each group_ must be created with\n`formBuilder.group` for the form `get` control to work:\n\n```typescript\n// Notice the nested `dateRange` object without using `.group`\nmyForm: FormGroup = this.formBuilder.group({\n dateRange: {\n startDate: [\n new Date(2017, 4, 6),\n ],\n endDate: [\n new Date(2017, 4, 8),\n ],\n },\n});\n\n// THIS WILL FAIL!\nconst range = myForm.get('dateRange');\n\n//////////////////////////////////////////////////\n\n// Notice the nested `dateRange` object IS using `.group`\nmyForm: FormGroup = this.formBuilder.group({\n dateRange: this.formBuilder.group({\n startDate: [\n new Date(2017, 4, 6),\n [\n Validators.required,\n ],\n ],\n endDate: [\n new Date(2017, 4, 8),\n [\n Validators.required,\n ],\n ],\n }),\n});\n\n// Now there is a group for us to 'get'\nconst range = myForm.get('dateRange');\n```\n\n### Event Emitters\n\nSupported event emitters:\n\n```html\n\n```\n\n> NOTE: The `selected` input is only available when `datepicker` is true.\n\n### Masks\n\nMasks enable the input to enforce specific formatting for values; such as postal codes: `12345-1234`.\n\n#### Available Masks\n\n| Mask | Input value | Masked Value |\n|--------------|--------------|------------------|\n| `currency` | `12.34` | `$12.34` |\n| `date` | `12121982` | `12-12-1982` |\n| `number` | `1234.56` | `1,234.56` |\n| `percentage` | `12.4` | `12.4%` |\n| `phone` | `1231231234` | `(123) 123-1234` |\n| `postal` | `123456789` | `12345-6789` |\n\n\n#### Sanitize the model value\n\nMost often you will not want the mask characters to be saved as part of the actual value. By default this component will sanitize the value\nbefore saving it to the model. This can be disabled if needed:\n\n```html\n\n```\n\nThis setup will format the value displayed in the UI: `(123) 456-7890`)while saving the pure value to the model: `1234567890`.\n\n#### Allow decimals in number-based masks\n\nBy default, number based masks (`number`, `percentage`) allow decimals. This can be disabled:\n\n```html\n\n```\n\nThis means when the user types `12.34`, the input UI and model value will both be `1234`.\n\n### Datepicker\n\nTo add datepicker abilities to an input, set the `datepicker` input:\n\n```html\n\n```\n\n\n#### Filter out available dates\n\nIf, for instance, you need to prohibit weekend days (sat/sun) from being selected you can pass in a\ncustom method to filter dates:\n\n```html\n\n```\n\n```typescript\nmyFilter = (d: Date): boolean => {\n const day = d.getDay();\n // Prevent Saturday and Sunday from being selected.\n return day !== 0 && day !== 6;\n}\n```\n\n#### Set a max/min date range\n\nTo define bounds for date selection, pass in a valid `Date` to `minDate` and/or `maxDate`:\n\n```html\n\n```\n\n```typescript\ndate1 = new Date(2017, 2, 1);\ndate2 = new Date(2017, 8, 1);\n```\n\n#### Open calendar to a specific date\n\nPass in a `Date` to `openTo`:\n\n```html\n\n```\n\n```typescript\nmyDate = new Date(2017, 5, 12);\n```\n\n#### Open calendar to a specific view\n\nBy default, the calendar opens up to show the month view. This can be changed to show the year view initially:\n\n```html\n\n```\n\n`year` and `month` are the only two valid values.\n\n#### Example with dynamic validation\n\nWe can recreate a version of the {@link TsDateRangeComponent} using dynamic validation:\n\n```html\n\n```\n\n```typescript\nmyForm = this.formBuilder.group({\n startDate: [\n null,\n [\n Validators.required,\n ],\n ],\n endDate: [\n null,\n [\n Validators.required,\n ],\n ],\n});\n\n// When the startDate changes, we want to set that date as the minDate for the endDate\nrangeStartChange(event: MatDatepickerInputEvent) {\n if (event) {\n // Get the from control\n const control = this.formTwo.get('endDate');\n\n // Set all validators.\n // NOTE: setting validators will clear ALL existing validators, so we must add the required\n // validator here again\n control.setValidators([\n Validators.required,\n this.validatorsService.minDate(event.value),\n ]);\n // Tell the control to update according to the new validators\n control.updateValueAndValidity();\n }\n}\n\n// When the endDate changes, we want to set that date as the maxDate for the startDate\nrangeEndChange(event: MatDatepickerInputEvent) {\n if (event) {\n // Get the from control\n const control = this.formTwo.get('startDate');\n\n // Set all validators.\n // NOTE: setting validators will clear ALL existing validators, so we must add the required\n // validator here again\n control.setValidators([\n Validators.required,\n this.validatorsService.maxDate(event.value),\n ]);\n // Tell the control to update according to the new validators\n control.updateValueAndValidity();\n }\n}\n```\n\n### Textarea\n\nSwitch from a standard input to a textarea:\n\n```html\n\n```\n\n#### Rows\n\nThe row count can be dynamically adjusted:\n\n```html\n\n```\n\n## Test Helpers\n\nSome helpers are exposed to assist with testing. These are imported from `@terminus/ui-input/testing`;\n\n[[source]][test-helpers-src]\n\n| Function |\n|------------------------|\n| `getAllInputInstances` |\n| `getInputInstance` |\n| `getInputElement` |\n| `sendInput` |\n\n\n\n[test-helpers-src]: testing/src/test-helpers.ts\n[license-url]: https://github.com/GetTerminus/terminus-oss/blob/release/LICENSE\n[license-image]: http://img.shields.io/badge/license-MIT-blue.svg\n[codecov-project]: https://codecov.io/gh/GetTerminus/terminus-oss\n[codecov-badge]: https://codecov.io/gh/GetTerminus/terminus-oss/branch/release/graph/badge.svg\n[npm-version-image]: http://img.shields.io/npm/v/@terminus/ui-input.svg\n[npm-package]: https://www.npmjs.com/package/@terminus/ui-input\n[github-action-badge]: https://github.com/GetTerminus/terminus-oss/workflows/Release%20CI/badge.svg\n[github-action-link]: https://github.com/GetTerminus/terminus-oss/actions?query=workflow%3A%22CI+Release%22\n[file-size-badge]: http://img.badgesize.io/https://unpkg.com/@terminus/ui-input/bundles/terminus-ui-input.umd.min.js?compression=gzip\n[raw-distribution-js]: https://unpkg.com/@terminus/ui-input/bundles/terminus-ui-input.umd.js\n","readmeFilename":"README.md","description":"
\n\n[![CI/CD Status][github-action-badge]][github-action-link] [![Codecov][codecov-badge]][codecov-project] [![MIT License][license-image]][license-url] \n[![NPM version][npm-version-image]][npm-package] [![Library size][file-size-badge]][raw-distribution-js]\n\n\n\n**Table of Contents**\n\n- [Installation](#installation)\n - [Packages that need to be installed](#packages-that-need-to-be-installed)\n - [Modules that need to be in NgModule](#modules-that-need-to-be-in-ngmodule)\n - [CSS imports](#css-imports)\n - [CSS resources](#css-resources)\n- [Usage](#usage)\n - [Hint](#hint)\n - [No validation or hint](#no-validation-or-hint)\n - [Prefix icon](#prefix-icon)\n - [Disabled](#disabled)\n - [Required](#required)\n - [Required asterisk `*`](#required-asterisk-)\n - [Clearable](#clearable)\n - [Focused](#focused)\n - [Input Type](#input-type)\n - [Input Attributes](#input-attributes)\n - [Validation timing](#validation-timing)\n - [Component reference](#component-reference)\n - [Usage with Reactive Forms](#usage-with-reactive-forms)\n - [Event Emitters](#event-emitters)\n - [Masks](#masks)\n - [Available Masks](#available-masks)\n - [Sanitize the model value](#sanitize-the-model-value)\n - [Allow decimals in number-based masks](#allow-decimals-in-number-based-masks)\n - [Datepicker](#datepicker)\n - [Filter out available dates](#filter-out-available-dates)\n - [Set a max/min date range](#set-a-maxmin-date-range)\n - [Open calendar to a specific date](#open-calendar-to-a-specific-date)\n - [Open calendar to a specific view](#open-calendar-to-a-specific-view)\n - [Example with dynamic validation](#example-with-dynamic-validation)\n - [Textarea](#textarea)\n - [Rows](#rows)\n- [Test Helpers](#test-helpers)\n\n\n\n## Installation\n\n### Packages that need to be installed\n\n- `@angular/cdk`\n- `@angular/flex-layout`\n- `@angular/material`\n- `@terminus/design-tokens`\n- `@terminus/fe-utilities`\n- `@terminus/ui-form-field`\n- `@terminus/ui-icon`\n- `@terminus/ui-input`\n- `@terminus/ui-pipes`\n- `@terminus/ui-spacing`\n- `@terminus/ui-styles`\n- `@terminus/ui-utilities`\n- `@terminus/ui-validation-messages`\n- `@terminus/ui-validators`\n- `date-fns`\n- `text-mask-addons`\n- `text-mask-core`\n\nUse the `ng add` command to quickly install all the needed dependencies:\n\n```bash\nng add @terminus/ui-input\n```\n\n### Modules that need to be in NgModule\n\n- `BrowserAnimationsModule`\n- `TsInputModule`\n- `FormsModule`\n- `ReactiveFormsModule`\n\n### CSS imports\n\nIn your top level stylesheet, add these imports:\n\n```css\n@import '~@terminus/design-tokens/css/library-design-tokens.css';\n@import '~@terminus/ui-styles/terminus-ui.css';\n``` \n\n### CSS resources\n\nLoad the needed font families by adding this link to the `` of your application:\n\n```css\n\n```\n\n## Usage\n\nAttach an `NgModel` or `FormControl` to the input:\n\n```html\n\n\n\n```\n\nWe should _almost always_ being using a `FormControl`.\n\n> Note: If you don't need a full form group you can provide a stand-alone control: `myControl = new FormControl();`\n\n### Hint\n\nA 'hint' can be displayed below the input on the right-hand side. This should be used for helpful user information such as input\nrequirements.\n\n```html\n\n```\n\n### No validation or hint\n\nA flag to define whether this input field needs validation or hint. If it needs validation or hint, a padding bottom is added for the message, otherwise, no padding at the bottom.\n\n```html\n\n```\n\n### Prefix icon\n\nTo include an icon as a prefix to the input, pass a valid icon name to `prefixIcon`:\n\n```html\n\n```\n\n> See all valid icon possibilities: https://material.io/icons\n\n### Disabled\n\nInputs can be disabled by setting the component flag OR by setting the associated `FormControl` to `disabled`.\n\nThe `isDisabled` flag works with both `ngModel` and `FormControl` inputs:\n\n```html\n\n```\n\nWhen using Reactive Forms, controls should be disabled via the control:\n\n```typescript\nmyControl: FormControl = new FormControl({value: null, disabled: true});\n```\n\n### Required\n\nWhen using a `FormControl`, set the required validator on the control:\n\n```typescript\nmyControl = new FormControl(null, Validators.required);\n```\n\nWhen using `ngModel`, validations are placed on the input as data-attributes (just like native HTML inputs):\n\n```html\n\n```\n\nIf only the required asterisk is needed rather than validation errors, the `isRequired` flag can be used:\n\n```html\n\n```\n\n#### Required asterisk `*`\n\nIf the input should be required, but the required asterisk `*` is not needed, disable it with the\n`hideRequiredMarker` input:\n\n```html\n\n```\n\n> NOTE: We should not hide this visual indicator without a very good reason!\n\n### Clearable\n\nIf the input should be easily reset, include the `isClearable` flag to enable a 'clear input'\nbutton: (button will appear as small `x` icon at the far right of the input)\n\n```html\n\n```\n\nWhen the input is cleared, the `cleared` event emitter will be fired with the value `true`.\n\n### Focused\n\nAuto-focus the input when the view loads:\n\n```html\n\n```\n\n> NOTE: If multiple inputs within the same view set `isFocused` to true, the _**last one rendered\n> will receive the final focus**_.\n\nThis can also be used to dynamically focus an existing input:\n\n```html\n\n```\n\n```typescript\nmyFocusedFlag = false;\n\ntoggleInputFocus() {\n this.myFocusedFlag = !this.myFocusedFlag;\n}\n```\n\n### Input Type\n\nThe input type can be defined with the type input:\n\n```html\n\n```\n\n> For all allowed types, see `TsInputTypes`.\n\n### Input Attributes\n\n`autocapitalize`, `autocomplete`, `spellcheck`, `readonly`\n\n```html\n\n```\n\n> For all allowed `autocomplete` types, see `TsInputAutocompleteTypes`.\n\n### Validation timing\n\nValidate on change rather than blur:\n\n```html\n\n```\n\n### Component reference\n\nTo get a reference to the component class, assign the exported name to a local variable:\n\n```html\n\n```\n\n```typescript\n@ViewChild(TsInputComponent, {static: false})\nmyVar: TsInputComponent;\n\nconsole.log('Component Class: ', this.myVar);\n```\n\n### Usage with Reactive Forms\n\nPass in the form control:\n\n```html\n\n```\n\n```typescript\nmyForm = this.formBuilder.group({\n date: [\n null, // If you need a default value, change this `null` to your value\n [\n Validators.required,\n ],\n ],\n});\n```\n\n**NOTE:** If using a form with nested form groups, _each group_ must be created with\n`formBuilder.group` for the form `get` control to work:\n\n```typescript\n// Notice the nested `dateRange` object without using `.group`\nmyForm: FormGroup = this.formBuilder.group({\n dateRange: {\n startDate: [\n new Date(2017, 4, 6),\n ],\n endDate: [\n new Date(2017, 4, 8),\n ],\n },\n});\n\n// THIS WILL FAIL!\nconst range = myForm.get('dateRange');\n\n//////////////////////////////////////////////////\n\n// Notice the nested `dateRange` object IS using `.group`\nmyForm: FormGroup = this.formBuilder.group({\n dateRange: this.formBuilder.group({\n startDate: [\n new Date(2017, 4, 6),\n [\n Validators.required,\n ],\n ],\n endDate: [\n new Date(2017, 4, 8),\n [\n Validators.required,\n ],\n ],\n }),\n});\n\n// Now there is a group for us to 'get'\nconst range = myForm.get('dateRange');\n```\n\n### Event Emitters\n\nSupported event emitters:\n\n```html\n\n```\n\n> NOTE: The `selected` input is only available when `datepicker` is true.\n\n### Masks\n\nMasks enable the input to enforce specific formatting for values; such as postal codes: `12345-1234`.\n\n#### Available Masks\n\n| Mask | Input value | Masked Value |\n|--------------|--------------|------------------|\n| `currency` | `12.34` | `$12.34` |\n| `date` | `12121982` | `12-12-1982` |\n| `number` | `1234.56` | `1,234.56` |\n| `percentage` | `12.4` | `12.4%` |\n| `phone` | `1231231234` | `(123) 123-1234` |\n| `postal` | `123456789` | `12345-6789` |\n\n\n#### Sanitize the model value\n\nMost often you will not want the mask characters to be saved as part of the actual value. By default this component will sanitize the value\nbefore saving it to the model. This can be disabled if needed:\n\n```html\n\n```\n\nThis setup will format the value displayed in the UI: `(123) 456-7890`)while saving the pure value to the model: `1234567890`.\n\n#### Allow decimals in number-based masks\n\nBy default, number based masks (`number`, `percentage`) allow decimals. This can be disabled:\n\n```html\n\n```\n\nThis means when the user types `12.34`, the input UI and model value will both be `1234`.\n\n### Datepicker\n\nTo add datepicker abilities to an input, set the `datepicker` input:\n\n```html\n\n```\n\n\n#### Filter out available dates\n\nIf, for instance, you need to prohibit weekend days (sat/sun) from being selected you can pass in a\ncustom method to filter dates:\n\n```html\n\n```\n\n```typescript\nmyFilter = (d: Date): boolean => {\n const day = d.getDay();\n // Prevent Saturday and Sunday from being selected.\n return day !== 0 && day !== 6;\n}\n```\n\n#### Set a max/min date range\n\nTo define bounds for date selection, pass in a valid `Date` to `minDate` and/or `maxDate`:\n\n```html\n\n```\n\n```typescript\ndate1 = new Date(2017, 2, 1);\ndate2 = new Date(2017, 8, 1);\n```\n\n#### Open calendar to a specific date\n\nPass in a `Date` to `openTo`:\n\n```html\n\n```\n\n```typescript\nmyDate = new Date(2017, 5, 12);\n```\n\n#### Open calendar to a specific view\n\nBy default, the calendar opens up to show the month view. This can be changed to show the year view initially:\n\n```html\n\n```\n\n`year` and `month` are the only two valid values.\n\n#### Example with dynamic validation\n\nWe can recreate a version of the {@link TsDateRangeComponent} using dynamic validation:\n\n```html\n\n```\n\n```typescript\nmyForm = this.formBuilder.group({\n startDate: [\n null,\n [\n Validators.required,\n ],\n ],\n endDate: [\n null,\n [\n Validators.required,\n ],\n ],\n});\n\n// When the startDate changes, we want to set that date as the minDate for the endDate\nrangeStartChange(event: MatDatepickerInputEvent) {\n if (event) {\n // Get the from control\n const control = this.formTwo.get('endDate');\n\n // Set all validators.\n // NOTE: setting validators will clear ALL existing validators, so we must add the required\n // validator here again\n control.setValidators([\n Validators.required,\n this.validatorsService.minDate(event.value),\n ]);\n // Tell the control to update according to the new validators\n control.updateValueAndValidity();\n }\n}\n\n// When the endDate changes, we want to set that date as the maxDate for the startDate\nrangeEndChange(event: MatDatepickerInputEvent) {\n if (event) {\n // Get the from control\n const control = this.formTwo.get('startDate');\n\n // Set all validators.\n // NOTE: setting validators will clear ALL existing validators, so we must add the required\n // validator here again\n control.setValidators([\n Validators.required,\n this.validatorsService.maxDate(event.value),\n ]);\n // Tell the control to update according to the new validators\n control.updateValueAndValidity();\n }\n}\n```\n\n### Textarea\n\nSwitch from a standard input to a textarea:\n\n```html\n\n```\n\n#### Rows\n\nThe row count can be dynamically adjusted:\n\n```html\n\n```\n\n## Test Helpers\n\nSome helpers are exposed to assist with testing. These are imported from `@terminus/ui-input/testing`;\n\n[[source]][test-helpers-src]\n\n| Function |\n|------------------------|\n| `getAllInputInstances` |\n| `getInputInstance` |\n| `getInputElement` |\n| `sendInput` |\n\n\n\n[test-helpers-src]: testing/src/test-helpers.ts\n[license-url]: https://github.com/GetTerminus/terminus-oss/blob/release/LICENSE\n[license-image]: http://img.shields.io/badge/license-MIT-blue.svg\n[codecov-project]: https://codecov.io/gh/GetTerminus/terminus-oss\n[codecov-badge]: https://codecov.io/gh/GetTerminus/terminus-oss/branch/release/graph/badge.svg\n[npm-version-image]: http://img.shields.io/npm/v/@terminus/ui-input.svg\n[npm-package]: https://www.npmjs.com/package/@terminus/ui-input\n[github-action-badge]: https://github.com/GetTerminus/terminus-oss/workflows/Release%20CI/badge.svg\n[github-action-link]: https://github.com/GetTerminus/terminus-oss/actions?query=workflow%3A%22CI+Release%22\n[file-size-badge]: http://img.badgesize.io/https://unpkg.com/@terminus/ui-input/bundles/terminus-ui-input.umd.min.js?compression=gzip\n[raw-distribution-js]: https://unpkg.com/@terminus/ui-input/bundles/terminus-ui-input.umd.js\n","readmeFilename":"README.md","description":"
\n\n[![CI/CD Status][github-action-badge]][github-action-link] [![Codecov][codecov-badge]][codecov-project] [![MIT License][license-image]][license-url] \n[![NPM version][npm-version-image]][npm-package] [![Library size][file-size-badge]][raw-distribution-js]\n\n\n\n## Table of Contents\n\n- [Installation](#installation)\n - [Packages that need to be installed](#packages-that-need-to-be-installed)\n - [Modules that need to be in NgModule](#modules-that-need-to-be-in-ngmodule)\n - [CSS imports](#css-imports)\n - [CSS resources](#css-resources)\n- [Usage](#usage)\n - [Hint](#hint)\n - [No validation or hint](#no-validation-or-hint)\n - [Prefix icon](#prefix-icon)\n - [Disabled](#disabled)\n - [Required](#required)\n - [Required asterisk `*`](#required-asterisk-)\n - [Clearable](#clearable)\n - [Focused](#focused)\n - [Input Type](#input-type)\n - [Input Attributes](#input-attributes)\n - [Validation timing](#validation-timing)\n - [Component reference](#component-reference)\n - [Usage with Reactive Forms](#usage-with-reactive-forms)\n - [Event Emitters](#event-emitters)\n - [Masks](#masks)\n - [Available Masks](#available-masks)\n - [Sanitize the model value](#sanitize-the-model-value)\n - [Allow decimals in number-based masks](#allow-decimals-in-number-based-masks)\n - [Datepicker](#datepicker)\n - [Filter out available dates](#filter-out-available-dates)\n - [Set a max/min date range](#set-a-maxmin-date-range)\n - [Open calendar to a specific date](#open-calendar-to-a-specific-date)\n - [Open calendar to a specific view](#open-calendar-to-a-specific-view)\n - [Example with dynamic validation](#example-with-dynamic-validation)\n - [Textarea](#textarea)\n - [Rows](#rows)\n- [Test Helpers](#test-helpers)\n\n\n\n## Installation\n\n### Packages that need to be installed\n\n- `@angular/cdk`\n- `@angular/flex-layout`\n- `@angular/material`\n- `@terminus/design-tokens`\n- `@terminus/fe-utilities`\n- `@terminus/ui-form-field`\n- `@terminus/ui-icon`\n- `@terminus/ui-input`\n- `@terminus/ui-pipes`\n- `@terminus/ui-spacing`\n- `@terminus/ui-styles`\n- `@terminus/ui-utilities`\n- `@terminus/ui-validation-messages`\n- `@terminus/ui-validators`\n- `date-fns`\n- `text-mask-addons`\n- `text-mask-core`\n\nUse the `ng add` command to quickly install all the needed dependencies:\n\n```bash\nng add @terminus/ui-input\n```\n\n### Modules that need to be in NgModule\n\n- `BrowserAnimationsModule`\n- `TsInputModule`\n- `FormsModule`\n- `ReactiveFormsModule`\n\n### CSS imports\n\nIn your top level stylesheet, add these imports:\n\n```css\n@import '~@terminus/design-tokens/css/library-design-tokens.css';\n@import '~@terminus/ui-styles/terminus-ui.css';\n``` \n\n### CSS resources\n\nLoad the needed font families by adding this link to the `` of your application:\n\n```css\n\n```\n\n## Usage\n\nAttach an `NgModel` or `FormControl` to the input:\n\n```html\n\n\n\n```\n\nWe should _almost always_ being using a `FormControl`.\n\n> Note: If you don't need a full form group you can provide a stand-alone control: `myControl = new FormControl();`\n\n### Hint\n\nA 'hint' can be displayed below the input on the right-hand side. This should be used for helpful user information such as input\nrequirements.\n\n```html\n\n```\n\n### No validation or hint\n\nA flag to define whether this input field needs validation or hint. If it needs validation or hint, a padding bottom is added for the message, otherwise, no padding at the bottom.\n\n```html\n\n```\n\n### Prefix icon\n\nTo include an icon as a prefix to the input, pass a valid icon instance to `prefixIcon`:\n\n```typescript\nimport { faHome } from '@fortawesome/pro-solid-svg-icons/faHome';\n...\npublic home = faHome;\n```\n\n```html\n\n```\n\n> See all valid icon possibilities: \n\n### Disabled\n\nInputs can be disabled by setting the component flag OR by setting the associated `FormControl` to `disabled`.\n\nThe `isDisabled` flag works with both `ngModel` and `FormControl` inputs:\n\n```html\n\n```\n\nWhen using Reactive Forms, controls should be disabled via the control:\n\n```typescript\nmyControl: FormControl = new FormControl({value: null, disabled: true});\n```\n\n### Required\n\nWhen using a `FormControl`, set the required validator on the control:\n\n```typescript\nmyControl = new FormControl(null, Validators.required);\n```\n\nWhen using `ngModel`, validations are placed on the input as data-attributes (just like native HTML inputs):\n\n```html\n\n```\n\nIf only the required asterisk is needed rather than validation errors, the `isRequired` flag can be used:\n\n```html\n\n```\n\n#### Required asterisk `*`\n\nIf the input should be required, but the required asterisk `*` is not needed, disable it with the\n`hideRequiredMarker` input:\n\n```html\n\n```\n\n> NOTE: We should not hide this visual indicator without a very good reason!\n\n### Clearable\n\nIf the input should be easily reset, include the `isClearable` flag to enable a 'clear input'\nbutton: (button will appear as small `x` icon at the far right of the input)\n\n```html\n\n```\n\nWhen the input is cleared, the `cleared` event emitter will be fired with the value `true`.\n\n### Focused\n\nAuto-focus the input when the view loads:\n\n```html\n\n```\n\n> NOTE: If multiple inputs within the same view set `isFocused` to true, the _**last one rendered\n> will receive the final focus**_.\n\nThis can also be used to dynamically focus an existing input:\n\n```html\n\n```\n\n```typescript\nmyFocusedFlag = false;\n\ntoggleInputFocus() {\n this.myFocusedFlag = !this.myFocusedFlag;\n}\n```\n\n### Input Type\n\nThe input type can be defined with the type input:\n\n```html\n\n```\n\n> For all allowed types, see `TsInputTypes`.\n\n### Input Attributes\n\n`autocapitalize`, `autocomplete`, `spellcheck`, `readonly`\n\n```html\n\n```\n\n> For all allowed `autocomplete` types, see `TsInputAutocompleteTypes`.\n\n### Validation timing\n\nValidate on change rather than blur:\n\n```html\n\n```\n\n### Component reference\n\nTo get a reference to the component class, assign the exported name to a local variable:\n\n```html\n\n```\n\n```typescript\n@ViewChild(TsInputComponent, {static: false})\nmyVar: TsInputComponent;\n\nconsole.log('Component Class: ', this.myVar);\n```\n\n### Usage with Reactive Forms\n\nPass in the form control:\n\n```html\n\n```\n\n```typescript\nmyForm = this.formBuilder.group({\n date: [\n null, // If you need a default value, change this `null` to your value\n [\n Validators.required,\n ],\n ],\n});\n```\n\n**NOTE:** If using a form with nested form groups, _each group_ must be created with\n`formBuilder.group` for the form `get` control to work:\n\n```typescript\n// Notice the nested `dateRange` object without using `.group`\nmyForm: FormGroup = this.formBuilder.group({\n dateRange: {\n startDate: [\n new Date(2017, 4, 6),\n ],\n endDate: [\n new Date(2017, 4, 8),\n ],\n },\n});\n\n// THIS WILL FAIL!\nconst range = myForm.get('dateRange');\n\n//////////////////////////////////////////////////\n\n// Notice the nested `dateRange` object IS using `.group`\nmyForm: FormGroup = this.formBuilder.group({\n dateRange: this.formBuilder.group({\n startDate: [\n new Date(2017, 4, 6),\n [\n Validators.required,\n ],\n ],\n endDate: [\n new Date(2017, 4, 8),\n [\n Validators.required,\n ],\n ],\n }),\n});\n\n// Now there is a group for us to 'get'\nconst range = myForm.get('dateRange');\n```\n\n### Event Emitters\n\nSupported event emitters:\n\n```html\n\n```\n\n> NOTE: The `selected` input is only available when `datepicker` is true.\n\n### Masks\n\nMasks enable the input to enforce specific formatting for values; such as postal codes: `12345-1234`.\n\n#### Available Masks\n\n| Mask | Input value | Masked Value |\n|--------------|--------------|------------------|\n| `currency` | `12.34` | `$12.34` |\n| `date` | `12121982` | `12-12-1982` |\n| `number` | `1234.56` | `1,234.56` |\n| `percentage` | `12.4` | `12.4%` |\n| `phone` | `1231231234` | `(123) 123-1234` |\n| `postal` | `123456789` | `12345-6789` |\n\n#### Sanitize the model value\n\nMost often you will not want the mask characters to be saved as part of the actual value. By default this component will sanitize the value\nbefore saving it to the model. This can be disabled if needed:\n\n```html\n\n```\n\nThis setup will format the value displayed in the UI: `(123) 456-7890`)while saving the pure value to the model: `1234567890`.\n\n#### Allow decimals in number-based masks\n\nBy default, number based masks (`number`, `percentage`) allow decimals. This can be disabled:\n\n```html\n\n```\n\nThis means when the user types `12.34`, the input UI and model value will both be `1234`.\n\n### Datepicker\n\nTo add datepicker abilities to an input, set the `datepicker` input:\n\n```html\n\n```\n\n#### Filter out available dates\n\nIf, for instance, you need to prohibit weekend days (sat/sun) from being selected you can pass in a\ncustom method to filter dates:\n\n```html\n\n```\n\n```typescript\nmyFilter = (d: Date): boolean => {\n const day = d.getDay();\n // Prevent Saturday and Sunday from being selected.\n return day !== 0 && day !== 6;\n}\n```\n\n#### Set a max/min date range\n\nTo define bounds for date selection, pass in a valid `Date` to `minDate` and/or `maxDate`:\n\n```html\n\n```\n\n```typescript\ndate1 = new Date(2017, 2, 1);\ndate2 = new Date(2017, 8, 1);\n```\n\n#### Open calendar to a specific date\n\nPass in a `Date` to `openTo`:\n\n```html\n\n```\n\n```typescript\nmyDate = new Date(2017, 5, 12);\n```\n\n#### Open calendar to a specific view\n\nBy default, the calendar opens up to show the month view. This can be changed to show the year view initially:\n\n```html\n\n```\n\n`year` and `month` are the only two valid values.\n\n#### Example with dynamic validation\n\nWe can recreate a version of the {@link TsDateRangeComponent} using dynamic validation:\n\n```html\n\n```\n\n```typescript\nmyForm = this.formBuilder.group({\n startDate: [\n null,\n [\n Validators.required,\n ],\n ],\n endDate: [\n null,\n [\n Validators.required,\n ],\n ],\n});\n\n// When the startDate changes, we want to set that date as the minDate for the endDate\nrangeStartChange(event: MatDatepickerInputEvent) {\n if (event) {\n // Get the from control\n const control = this.formTwo.get('endDate');\n\n // Set all validators.\n // NOTE: setting validators will clear ALL existing validators, so we must add the required\n // validator here again\n control.setValidators([\n Validators.required,\n this.validatorsService.minDate(event.value),\n ]);\n // Tell the control to update according to the new validators\n control.updateValueAndValidity();\n }\n}\n\n// When the endDate changes, we want to set that date as the maxDate for the startDate\nrangeEndChange(event: MatDatepickerInputEvent) {\n if (event) {\n // Get the from control\n const control = this.formTwo.get('startDate');\n\n // Set all validators.\n // NOTE: setting validators will clear ALL existing validators, so we must add the required\n // validator here again\n control.setValidators([\n Validators.required,\n this.validatorsService.maxDate(event.value),\n ]);\n // Tell the control to update according to the new validators\n control.updateValueAndValidity();\n }\n}\n```\n\n### Textarea\n\nSwitch from a standard input to a textarea:\n\n```html\n\n```\n\n#### Rows\n\nThe row count can be dynamically adjusted:\n\n```html\n\n```\n\n## Test Helpers\n\nSome helpers are exposed to assist with testing. These are imported from `@terminus/ui-input/testing`;\n\n[[source]][test-helpers-src]\n\n| Function |\n|------------------------|\n| `getAllInputInstances` |\n| `getInputInstance` |\n| `getInputElement` |\n| `sendInput` |\n\n\n[test-helpers-src]: testing/src/test-helpers.ts\n[license-url]: https://github.com/GetTerminus/terminus-oss/blob/release/LICENSE\n[license-image]: http://img.shields.io/badge/license-MIT-blue.svg\n[codecov-project]: https://codecov.io/gh/GetTerminus/terminus-oss\n[codecov-badge]: https://codecov.io/gh/GetTerminus/terminus-oss/branch/release/graph/badge.svg\n[npm-version-image]: http://img.shields.io/npm/v/@terminus/ui-input.svg\n[npm-package]: https://www.npmjs.com/package/@terminus/ui-input\n[github-action-badge]: https://github.com/GetTerminus/terminus-oss/workflows/Release%20CI/badge.svg\n[github-action-link]: https://github.com/GetTerminus/terminus-oss/actions?query=workflow%3A%22CI+Release%22\n[file-size-badge]: http://img.badgesize.io/https://unpkg.com/@terminus/ui-input/bundles/terminus-ui-input.umd.min.js?compression=gzip\n[raw-distribution-js]: https://unpkg.com/@terminus/ui-input/bundles/terminus-ui-input.umd.js\n","readmeFilename":"README.md","description":"
\n\n[![CI/CD Status][github-action-badge]][github-action-link] [![Codecov][codecov-badge]][codecov-project] [![MIT License][license-image]][license-url] \n[![NPM version][npm-version-image]][npm-package] [![Library size][file-size-badge]][raw-distribution-js]\n\n\n\n## Table of Contents\n\n- [Installation](#installation)\n - [Packages that need to be installed](#packages-that-need-to-be-installed)\n - [Modules that need to be in NgModule](#modules-that-need-to-be-in-ngmodule)\n - [CSS imports](#css-imports)\n - [CSS resources](#css-resources)\n- [Usage](#usage)\n - [Hint](#hint)\n - [No validation or hint](#no-validation-or-hint)\n - [Prefix icon](#prefix-icon)\n - [Disabled](#disabled)\n - [Required](#required)\n - [Required asterisk `*`](#required-asterisk-)\n - [Clearable](#clearable)\n - [Focused](#focused)\n - [Input Type](#input-type)\n - [Input Attributes](#input-attributes)\n - [Validation timing](#validation-timing)\n - [Component reference](#component-reference)\n - [Usage with Reactive Forms](#usage-with-reactive-forms)\n - [Event Emitters](#event-emitters)\n - [Masks](#masks)\n - [Available Masks](#available-masks)\n - [Sanitize the model value](#sanitize-the-model-value)\n - [Allow decimals in number-based masks](#allow-decimals-in-number-based-masks)\n - [Datepicker](#datepicker)\n - [Filter out available dates](#filter-out-available-dates)\n - [Set a max/min date range](#set-a-maxmin-date-range)\n - [Open calendar to a specific date](#open-calendar-to-a-specific-date)\n - [Open calendar to a specific view](#open-calendar-to-a-specific-view)\n - [Example with dynamic validation](#example-with-dynamic-validation)\n - [Textarea](#textarea)\n - [Rows](#rows)\n- [Test Helpers](#test-helpers)\n\n\n\n## Installation\n\n### Packages that need to be installed\n\n- `@angular/cdk`\n- `@angular/flex-layout`\n- `@angular/material`\n- `@terminus/design-tokens`\n- `@terminus/fe-utilities`\n- `@terminus/ui-form-field`\n- `@terminus/ui-icon`\n- `@terminus/ui-input`\n- `@terminus/ui-pipes`\n- `@terminus/ui-spacing`\n- `@terminus/ui-styles`\n- `@terminus/ui-utilities`\n- `@terminus/ui-validation-messages`\n- `@terminus/ui-validators`\n- `date-fns`\n- `text-mask-addons`\n- `text-mask-core`\n\nUse the `ng add` command to quickly install all the needed dependencies:\n\n```bash\nng add @terminus/ui-input\n```\n\n### Modules that need to be in NgModule\n\n- `BrowserAnimationsModule`\n- `TsInputModule`\n- `FormsModule`\n- `ReactiveFormsModule`\n\n### CSS imports\n\nIn your top level stylesheet, add these imports:\n\n```css\n@import '~@terminus/design-tokens/css/library-design-tokens.css';\n@import '~@terminus/ui-styles/terminus-ui.css';\n``` \n\n### CSS resources\n\nLoad the needed font families by adding this link to the `` of your application:\n\n```css\n\n```\n\n## Usage\n\nAttach an `NgModel` or `FormControl` to the input:\n\n```html\n\n\n\n```\n\nWe should _almost always_ being using a `FormControl`.\n\n> Note: If you don't need a full form group you can provide a stand-alone control: `myControl = new FormControl();`\n\n### Hint\n\nA 'hint' can be displayed below the input on the right-hand side. This should be used for helpful user information such as input\nrequirements.\n\n```html\n\n```\n\n### No validation or hint\n\nA flag to define whether this input field needs validation or hint. If it needs validation or hint, a padding bottom is added for the message, otherwise, no padding at the bottom.\n\n```html\n\n```\n\n### Prefix icon\n\nTo include an icon as a prefix to the input, pass a valid icon instance to `prefixIcon`:\n\n```typescript\nimport { faHome } from '@fortawesome/pro-solid-svg-icons/faHome';\n...\npublic home = faHome;\n```\n\n```html\n\n```\n\n> See all valid icon possibilities: \n\n### Disabled\n\nInputs can be disabled by setting the component flag OR by setting the associated `FormControl` to `disabled`.\n\nThe `isDisabled` flag works with both `ngModel` and `FormControl` inputs:\n\n```html\n\n```\n\nWhen using Reactive Forms, controls should be disabled via the control:\n\n```typescript\nmyControl: FormControl = new FormControl({value: null, disabled: true});\n```\n\n### Required\n\nWhen using a `FormControl`, set the required validator on the control:\n\n```typescript\nmyControl = new FormControl(null, Validators.required);\n```\n\nWhen using `ngModel`, validations are placed on the input as data-attributes (just like native HTML inputs):\n\n```html\n\n```\n\nIf only the required asterisk is needed rather than validation errors, the `isRequired` flag can be used:\n\n```html\n\n```\n\n#### Required asterisk `*`\n\nIf the input should be required, but the required asterisk `*` is not needed, disable it with the\n`hideRequiredMarker` input:\n\n```html\n\n```\n\n> NOTE: We should not hide this visual indicator without a very good reason!\n\n### Clearable\n\nIf the input should be easily reset, include the `isClearable` flag to enable a 'clear input'\nbutton: (button will appear as small `x` icon at the far right of the input)\n\n```html\n\n```\n\nWhen the input is cleared, the `cleared` event emitter will be fired with the value `true`.\n\n### Focused\n\nAuto-focus the input when the view loads:\n\n```html\n\n```\n\n> NOTE: If multiple inputs within the same view set `isFocused` to true, the _**last one rendered\n> will receive the final focus**_.\n\nThis can also be used to dynamically focus an existing input:\n\n```html\n\n```\n\n```typescript\nmyFocusedFlag = false;\n\ntoggleInputFocus() {\n this.myFocusedFlag = !this.myFocusedFlag;\n}\n```\n\n### Input Type\n\nThe input type can be defined with the type input:\n\n```html\n\n```\n\n> For all allowed types, see `TsInputTypes`.\n\n### Input Attributes\n\n`autocapitalize`, `autocomplete`, `spellcheck`, `readonly`\n\n```html\n\n```\n\n> For all allowed `autocomplete` types, see `TsInputAutocompleteTypes`.\n\n### Validation timing\n\nValidate on change rather than blur:\n\n```html\n\n```\n\n### Component reference\n\nTo get a reference to the component class, assign the exported name to a local variable:\n\n```html\n\n```\n\n```typescript\n@ViewChild(TsInputComponent, {static: false})\nmyVar: TsInputComponent;\n\nconsole.log('Component Class: ', this.myVar);\n```\n\n### Usage with Reactive Forms\n\nPass in the form control:\n\n```html\n\n```\n\n```typescript\nmyForm = this.formBuilder.group({\n date: [\n null, // If you need a default value, change this `null` to your value\n [\n Validators.required,\n ],\n ],\n});\n```\n\n**NOTE:** If using a form with nested form groups, _each group_ must be created with\n`formBuilder.group` for the form `get` control to work:\n\n```typescript\n// Notice the nested `dateRange` object without using `.group`\nmyForm: FormGroup = this.formBuilder.group({\n dateRange: {\n startDate: [\n new Date(2017, 4, 6),\n ],\n endDate: [\n new Date(2017, 4, 8),\n ],\n },\n});\n\n// THIS WILL FAIL!\nconst range = myForm.get('dateRange');\n\n//////////////////////////////////////////////////\n\n// Notice the nested `dateRange` object IS using `.group`\nmyForm: FormGroup = this.formBuilder.group({\n dateRange: this.formBuilder.group({\n startDate: [\n new Date(2017, 4, 6),\n [\n Validators.required,\n ],\n ],\n endDate: [\n new Date(2017, 4, 8),\n [\n Validators.required,\n ],\n ],\n }),\n});\n\n// Now there is a group for us to 'get'\nconst range = myForm.get('dateRange');\n```\n\n### Event Emitters\n\nSupported event emitters:\n\n```html\n\n```\n\n> NOTE: The `selected` input is only available when `datepicker` is true.\n\n### Masks\n\nMasks enable the input to enforce specific formatting for values; such as postal codes: `12345-1234`.\n\n#### Available Masks\n\n| Mask | Input value | Masked Value |\n|--------------|--------------|------------------|\n| `currency` | `12.34` | `$12.34` |\n| `date` | `12121982` | `12-12-1982` |\n| `number` | `1234.56` | `1,234.56` |\n| `percentage` | `12.4` | `12.4%` |\n| `phone` | `1231231234` | `(123) 123-1234` |\n| `postal` | `123456789` | `12345-6789` |\n\n#### Sanitize the model value\n\nMost often you will not want the mask characters to be saved as part of the actual value. By default this component will sanitize the value\nbefore saving it to the model. This can be disabled if needed:\n\n```html\n\n```\n\nThis setup will format the value displayed in the UI: `(123) 456-7890`)while saving the pure value to the model: `1234567890`.\n\n#### Allow decimals in number-based masks\n\nBy default, number based masks (`number`, `percentage`) allow decimals. This can be disabled:\n\n```html\n\n```\n\nThis means when the user types `12.34`, the input UI and model value will both be `1234`.\n\n### Datepicker\n\nTo add datepicker abilities to an input, set the `datepicker` input:\n\n```html\n\n```\n\n#### Filter out available dates\n\nIf, for instance, you need to prohibit weekend days (sat/sun) from being selected you can pass in a\ncustom method to filter dates:\n\n```html\n\n```\n\n```typescript\nmyFilter = (d: Date): boolean => {\n const day = d.getDay();\n // Prevent Saturday and Sunday from being selected.\n return day !== 0 && day !== 6;\n}\n```\n\n#### Set a max/min date range\n\nTo define bounds for date selection, pass in a valid `Date` to `minDate` and/or `maxDate`:\n\n```html\n\n```\n\n```typescript\ndate1 = new Date(2017, 2, 1);\ndate2 = new Date(2017, 8, 1);\n```\n\n#### Open calendar to a specific date\n\nPass in a `Date` to `openTo`:\n\n```html\n\n```\n\n```typescript\nmyDate = new Date(2017, 5, 12);\n```\n\n#### Open calendar to a specific view\n\nBy default, the calendar opens up to show the month view. This can be changed to show the year view initially:\n\n```html\n\n```\n\n`year` and `month` are the only two valid values.\n\n#### Example with dynamic validation\n\nWe can recreate a version of the {@link TsDateRangeComponent} using dynamic validation:\n\n```html\n\n```\n\n```typescript\nmyForm = this.formBuilder.group({\n startDate: [\n null,\n [\n Validators.required,\n ],\n ],\n endDate: [\n null,\n [\n Validators.required,\n ],\n ],\n});\n\n// When the startDate changes, we want to set that date as the minDate for the endDate\nrangeStartChange(event: MatDatepickerInputEvent) {\n if (event) {\n // Get the from control\n const control = this.formTwo.get('endDate');\n\n // Set all validators.\n // NOTE: setting validators will clear ALL existing validators, so we must add the required\n // validator here again\n control.setValidators([\n Validators.required,\n this.validatorsService.minDate(event.value),\n ]);\n // Tell the control to update according to the new validators\n control.updateValueAndValidity();\n }\n}\n\n// When the endDate changes, we want to set that date as the maxDate for the startDate\nrangeEndChange(event: MatDatepickerInputEvent) {\n if (event) {\n // Get the from control\n const control = this.formTwo.get('startDate');\n\n // Set all validators.\n // NOTE: setting validators will clear ALL existing validators, so we must add the required\n // validator here again\n control.setValidators([\n Validators.required,\n this.validatorsService.maxDate(event.value),\n ]);\n // Tell the control to update according to the new validators\n control.updateValueAndValidity();\n }\n}\n```\n\n### Textarea\n\nSwitch from a standard input to a textarea:\n\n```html\n\n```\n\n#### Rows\n\nThe row count can be dynamically adjusted:\n\n```html\n\n```\n\n## Test Helpers\n\nSome helpers are exposed to assist with testing. These are imported from `@terminus/ui-input/testing`;\n\n[[source]][test-helpers-src]\n\n| Function |\n|------------------------|\n| `getAllInputInstances` |\n| `getInputInstance` |\n| `getInputElement` |\n| `sendInput` |\n\n\n[test-helpers-src]: testing/src/test-helpers.ts\n[license-url]: https://github.com/GetTerminus/terminus-oss/blob/release/LICENSE\n[license-image]: http://img.shields.io/badge/license-MIT-blue.svg\n[codecov-project]: https://codecov.io/gh/GetTerminus/terminus-oss\n[codecov-badge]: https://codecov.io/gh/GetTerminus/terminus-oss/branch/release/graph/badge.svg\n[npm-version-image]: http://img.shields.io/npm/v/@terminus/ui-input.svg\n[npm-package]: https://www.npmjs.com/package/@terminus/ui-input\n[github-action-badge]: https://github.com/GetTerminus/terminus-oss/workflows/Release%20CI/badge.svg\n[github-action-link]: https://github.com/GetTerminus/terminus-oss/actions?query=workflow%3A%22CI+Release%22\n[file-size-badge]: http://img.badgesize.io/https://unpkg.com/@terminus/ui-input/bundles/terminus-ui-input.umd.min.js?compression=gzip\n[raw-distribution-js]: https://unpkg.com/@terminus/ui-input/bundles/terminus-ui-input.umd.js\n","readmeFilename":"README.md","description":"
\n\n[![CI/CD Status][github-action-badge]][github-action-link] [![Codecov][codecov-badge]][codecov-project] [![MIT License][license-image]][license-url] \n[![NPM version][npm-version-image]][npm-package] [![Library size][file-size-badge]][raw-distribution-js]\n\n\n\n## Table of Contents\n\n- [Installation](#installation)\n - [Packages that need to be installed](#packages-that-need-to-be-installed)\n - [Modules that need to be in NgModule](#modules-that-need-to-be-in-ngmodule)\n - [CSS imports](#css-imports)\n - [CSS resources](#css-resources)\n- [Usage](#usage)\n - [Hint](#hint)\n - [No validation or hint](#no-validation-or-hint)\n - [Prefix icon](#prefix-icon)\n - [Disabled](#disabled)\n - [Required](#required)\n - [Required asterisk `*`](#required-asterisk-)\n - [Clearable](#clearable)\n - [Focused](#focused)\n - [Input Type](#input-type)\n - [Input Attributes](#input-attributes)\n - [Validation timing](#validation-timing)\n - [Component reference](#component-reference)\n - [Usage with Reactive Forms](#usage-with-reactive-forms)\n - [Event Emitters](#event-emitters)\n - [Masks](#masks)\n - [Available Masks](#available-masks)\n - [Sanitize the model value](#sanitize-the-model-value)\n - [Allow decimals in number-based masks](#allow-decimals-in-number-based-masks)\n - [Datepicker](#datepicker)\n - [Filter out available dates](#filter-out-available-dates)\n - [Set a max/min date range](#set-a-maxmin-date-range)\n - [Open calendar to a specific date](#open-calendar-to-a-specific-date)\n - [Open calendar to a specific view](#open-calendar-to-a-specific-view)\n - [Example with dynamic validation](#example-with-dynamic-validation)\n - [Textarea](#textarea)\n - [Rows](#rows)\n- [Test Helpers](#test-helpers)\n\n\n\n## Installation\n\n### Packages that need to be installed\n\n- `@angular/cdk`\n- `@angular/flex-layout`\n- `@angular/material`\n- `@terminus/design-tokens`\n- `@terminus/fe-utilities`\n- `@terminus/ui-form-field`\n- `@terminus/ui-icon`\n- `@terminus/ui-input`\n- `@terminus/ui-pipes`\n- `@terminus/ui-spacing`\n- `@terminus/ui-styles`\n- `@terminus/ui-utilities`\n- `@terminus/ui-validation-messages`\n- `@terminus/ui-validators`\n- `date-fns`\n- `text-mask-addons`\n- `text-mask-core`\n\nUse the `ng add` command to quickly install all the needed dependencies:\n\n```bash\nng add @terminus/ui-input\n```\n\n### Modules that need to be in NgModule\n\n- `BrowserAnimationsModule`\n- `TsInputModule`\n- `FormsModule`\n- `ReactiveFormsModule`\n\n### CSS imports\n\nIn your top level stylesheet, add these imports:\n\n```css\n@import '~@terminus/design-tokens/css/library-design-tokens.css';\n@import '~@terminus/ui-styles/terminus-ui.css';\n``` \n\n### CSS resources\n\nLoad the needed font families by adding this link to the `` of your application:\n\n```css\n\n```\n\n## Usage\n\nAttach an `NgModel` or `FormControl` to the input:\n\n```html\n\n\n\n```\n\nWe should _almost always_ being using a `FormControl`.\n\n> Note: If you don't need a full form group you can provide a stand-alone control: `myControl = new FormControl();`\n\n### Hint\n\nA 'hint' can be displayed below the input on the right-hand side. This should be used for helpful user information such as input\nrequirements.\n\n```html\n\n```\n\n### No validation or hint\n\nA flag to define whether this input field needs validation or hint. If it needs validation or hint, a padding bottom is added for the message, otherwise, no padding at the bottom.\n\n```html\n\n```\n\n### Prefix icon\n\nTo include an icon as a prefix to the input, pass a valid icon instance to `prefixIcon`:\n\n```typescript\nimport { faHome } from '@fortawesome/pro-solid-svg-icons/faHome';\n...\npublic home = faHome;\n```\n\n```html\n\n```\n\n> See all valid icon possibilities: \n\n### Disabled\n\nInputs can be disabled by setting the component flag OR by setting the associated `FormControl` to `disabled`.\n\nThe `isDisabled` flag works with both `ngModel` and `FormControl` inputs:\n\n```html\n\n```\n\nWhen using Reactive Forms, controls should be disabled via the control:\n\n```typescript\nmyControl: FormControl = new FormControl({value: null, disabled: true});\n```\n\n### Required\n\nWhen using a `FormControl`, set the required validator on the control:\n\n```typescript\nmyControl = new FormControl(null, Validators.required);\n```\n\nWhen using `ngModel`, validations are placed on the input as data-attributes (just like native HTML inputs):\n\n```html\n\n```\n\nIf only the required asterisk is needed rather than validation errors, the `isRequired` flag can be used:\n\n```html\n\n```\n\n#### Required asterisk `*`\n\nIf the input should be required, but the required asterisk `*` is not needed, disable it with the\n`hideRequiredMarker` input:\n\n```html\n\n```\n\n> NOTE: We should not hide this visual indicator without a very good reason!\n\n### Clearable\n\nIf the input should be easily reset, include the `isClearable` flag to enable a 'clear input'\nbutton: (button will appear as small `x` icon at the far right of the input)\n\n```html\n\n```\n\nWhen the input is cleared, the `cleared` event emitter will be fired with the value `true`.\n\n### Focused\n\nAuto-focus the input when the view loads:\n\n```html\n\n```\n\n> NOTE: If multiple inputs within the same view set `isFocused` to true, the _**last one rendered\n> will receive the final focus**_.\n\nThis can also be used to dynamically focus an existing input:\n\n```html\n\n```\n\n```typescript\nmyFocusedFlag = false;\n\ntoggleInputFocus() {\n this.myFocusedFlag = !this.myFocusedFlag;\n}\n```\n\n### Input Type\n\nThe input type can be defined with the type input:\n\n```html\n\n```\n\n> For all allowed types, see `TsInputTypes`.\n\n### Input Attributes\n\n`autocapitalize`, `autocomplete`, `spellcheck`, `readonly`\n\n```html\n\n```\n\n> For all allowed `autocomplete` types, see `TsInputAutocompleteTypes`.\n\n### Validation timing\n\nValidate on change rather than blur:\n\n```html\n\n```\n\n### Component reference\n\nTo get a reference to the component class, assign the exported name to a local variable:\n\n```html\n\n```\n\n```typescript\n@ViewChild(TsInputComponent, {static: false})\nmyVar: TsInputComponent;\n\nconsole.log('Component Class: ', this.myVar);\n```\n\n### Usage with Reactive Forms\n\nPass in the form control:\n\n```html\n\n```\n\n```typescript\nmyForm = this.formBuilder.group({\n date: [\n null, // If you need a default value, change this `null` to your value\n [\n Validators.required,\n ],\n ],\n});\n```\n\n**NOTE:** If using a form with nested form groups, _each group_ must be created with\n`formBuilder.group` for the form `get` control to work:\n\n```typescript\n// Notice the nested `dateRange` object without using `.group`\nmyForm: FormGroup = this.formBuilder.group({\n dateRange: {\n startDate: [\n new Date(2017, 4, 6),\n ],\n endDate: [\n new Date(2017, 4, 8),\n ],\n },\n});\n\n// THIS WILL FAIL!\nconst range = myForm.get('dateRange');\n\n//////////////////////////////////////////////////\n\n// Notice the nested `dateRange` object IS using `.group`\nmyForm: FormGroup = this.formBuilder.group({\n dateRange: this.formBuilder.group({\n startDate: [\n new Date(2017, 4, 6),\n [\n Validators.required,\n ],\n ],\n endDate: [\n new Date(2017, 4, 8),\n [\n Validators.required,\n ],\n ],\n }),\n});\n\n// Now there is a group for us to 'get'\nconst range = myForm.get('dateRange');\n```\n\n### Event Emitters\n\nSupported event emitters:\n\n```html\n\n```\n\n> NOTE: The `selected` input is only available when `datepicker` is true.\n\n### Masks\n\nMasks enable the input to enforce specific formatting for values; such as postal codes: `12345-1234`.\n\n#### Available Masks\n\n| Mask | Input value | Masked Value |\n|--------------|--------------|------------------|\n| `currency` | `12.34` | `$12.34` |\n| `date` | `12121982` | `12-12-1982` |\n| `number` | `1234.56` | `1,234.56` |\n| `percentage` | `12.4` | `12.4%` |\n| `phone` | `1231231234` | `(123) 123-1234` |\n| `postal` | `123456789` | `12345-6789` |\n\n#### Sanitize the model value\n\nMost often you will not want the mask characters to be saved as part of the actual value. By default this component will sanitize the value\nbefore saving it to the model. This can be disabled if needed:\n\n```html\n\n```\n\nThis setup will format the value displayed in the UI: `(123) 456-7890`)while saving the pure value to the model: `1234567890`.\n\n#### Allow decimals in number-based masks\n\nBy default, number based masks (`number`, `percentage`) allow decimals. This can be disabled:\n\n```html\n\n```\n\nThis means when the user types `12.34`, the input UI and model value will both be `1234`.\n\n### Datepicker\n\nTo add datepicker abilities to an input, set the `datepicker` input:\n\n```html\n\n```\n\n#### Filter out available dates\n\nIf, for instance, you need to prohibit weekend days (sat/sun) from being selected you can pass in a\ncustom method to filter dates:\n\n```html\n\n```\n\n```typescript\nmyFilter = (d: Date): boolean => {\n const day = d.getDay();\n // Prevent Saturday and Sunday from being selected.\n return day !== 0 && day !== 6;\n}\n```\n\n#### Set a max/min date range\n\nTo define bounds for date selection, pass in a valid `Date` to `minDate` and/or `maxDate`:\n\n```html\n\n```\n\n```typescript\ndate1 = new Date(2017, 2, 1);\ndate2 = new Date(2017, 8, 1);\n```\n\n#### Open calendar to a specific date\n\nPass in a `Date` to `openTo`:\n\n```html\n\n```\n\n```typescript\nmyDate = new Date(2017, 5, 12);\n```\n\n#### Open calendar to a specific view\n\nBy default, the calendar opens up to show the month view. This can be changed to show the year view initially:\n\n```html\n\n```\n\n`year` and `month` are the only two valid values.\n\n#### Example with dynamic validation\n\nWe can recreate a version of the {@link TsDateRangeComponent} using dynamic validation:\n\n```html\n\n```\n\n```typescript\nmyForm = this.formBuilder.group({\n startDate: [\n null,\n [\n Validators.required,\n ],\n ],\n endDate: [\n null,\n [\n Validators.required,\n ],\n ],\n});\n\n// When the startDate changes, we want to set that date as the minDate for the endDate\nrangeStartChange(event: MatDatepickerInputEvent) {\n if (event) {\n // Get the from control\n const control = this.formTwo.get('endDate');\n\n // Set all validators.\n // NOTE: setting validators will clear ALL existing validators, so we must add the required\n // validator here again\n control.setValidators([\n Validators.required,\n this.validatorsService.minDate(event.value),\n ]);\n // Tell the control to update according to the new validators\n control.updateValueAndValidity();\n }\n}\n\n// When the endDate changes, we want to set that date as the maxDate for the startDate\nrangeEndChange(event: MatDatepickerInputEvent) {\n if (event) {\n // Get the from control\n const control = this.formTwo.get('startDate');\n\n // Set all validators.\n // NOTE: setting validators will clear ALL existing validators, so we must add the required\n // validator here again\n control.setValidators([\n Validators.required,\n this.validatorsService.maxDate(event.value),\n ]);\n // Tell the control to update according to the new validators\n control.updateValueAndValidity();\n }\n}\n```\n\n### Textarea\n\nSwitch from a standard input to a textarea:\n\n```html\n\n```\n\n#### Rows\n\nThe row count can be dynamically adjusted:\n\n```html\n\n```\n\n## Test Helpers\n\nSome helpers are exposed to assist with testing. These are imported from `@terminus/ui-input/testing`;\n\n[[source]][test-helpers-src]\n\n| Function |\n|------------------------|\n| `getAllInputInstances` |\n| `getInputInstance` |\n| `getInputElement` |\n| `sendInput` |\n\n\n[test-helpers-src]: testing/src/test-helpers.ts\n[license-url]: https://github.com/GetTerminus/terminus-oss/blob/release/LICENSE\n[license-image]: http://img.shields.io/badge/license-MIT-blue.svg\n[codecov-project]: https://codecov.io/gh/GetTerminus/terminus-oss\n[codecov-badge]: https://codecov.io/gh/GetTerminus/terminus-oss/branch/release/graph/badge.svg\n[npm-version-image]: http://img.shields.io/npm/v/@terminus/ui-input.svg\n[npm-package]: https://www.npmjs.com/package/@terminus/ui-input\n[github-action-badge]: https://github.com/GetTerminus/terminus-oss/workflows/Release%20CI/badge.svg\n[github-action-link]: https://github.com/GetTerminus/terminus-oss/actions?query=workflow%3A%22CI+Release%22\n[file-size-badge]: http://img.badgesize.io/https://unpkg.com/@terminus/ui-input/bundles/terminus-ui-input.umd.min.js?compression=gzip\n[raw-distribution-js]: https://unpkg.com/@terminus/ui-input/bundles/terminus-ui-input.umd.js\n","readmeFilename":"README.md","description":"
\n\n[![CI/CD Status][github-action-badge]][github-action-link] [![Codecov][codecov-badge]][codecov-project] [![MIT License][license-image]][license-url] \n[![NPM version][npm-version-image]][npm-package] [![Library size][file-size-badge]][raw-distribution-js]\n\n\n\n## Table of Contents\n\n- [Installation](#installation)\n - [Packages that need to be installed](#packages-that-need-to-be-installed)\n - [Modules that need to be in NgModule](#modules-that-need-to-be-in-ngmodule)\n - [CSS imports](#css-imports)\n - [CSS resources](#css-resources)\n- [Usage](#usage)\n - [Hint](#hint)\n - [No validation or hint](#no-validation-or-hint)\n - [Prefix icon](#prefix-icon)\n - [Disabled](#disabled)\n - [Required](#required)\n - [Required asterisk `*`](#required-asterisk-)\n - [Clearable](#clearable)\n - [Focused](#focused)\n - [Input Type](#input-type)\n - [Input Attributes](#input-attributes)\n - [Validation timing](#validation-timing)\n - [Component reference](#component-reference)\n - [Usage with Reactive Forms](#usage-with-reactive-forms)\n - [Event Emitters](#event-emitters)\n - [Masks](#masks)\n - [Available Masks](#available-masks)\n - [Sanitize the model value](#sanitize-the-model-value)\n - [Allow decimals in number-based masks](#allow-decimals-in-number-based-masks)\n - [Datepicker](#datepicker)\n - [Filter out available dates](#filter-out-available-dates)\n - [Set a max/min date range](#set-a-maxmin-date-range)\n - [Open calendar to a specific date](#open-calendar-to-a-specific-date)\n - [Open calendar to a specific view](#open-calendar-to-a-specific-view)\n - [Example with dynamic validation](#example-with-dynamic-validation)\n - [Textarea](#textarea)\n - [Rows](#rows)\n- [Test Helpers](#test-helpers)\n\n\n\n## Installation\n\n### Packages that need to be installed\n\n- `@angular/cdk`\n- `@angular/flex-layout`\n- `@angular/material`\n- `@terminus/design-tokens`\n- `@terminus/fe-utilities`\n- `@terminus/ui-form-field`\n- `@terminus/ui-icon`\n- `@terminus/ui-input`\n- `@terminus/ui-pipes`\n- `@terminus/ui-spacing`\n- `@terminus/ui-styles`\n- `@terminus/ui-utilities`\n- `@terminus/ui-validation-messages`\n- `@terminus/ui-validators`\n- `date-fns`\n- `text-mask-addons`\n- `text-mask-core`\n\nUse the `ng add` command to quickly install all the needed dependencies:\n\n```bash\nng add @terminus/ui-input\n```\n\n### Modules that need to be in NgModule\n\n- `BrowserAnimationsModule`\n- `TsInputModule`\n- `FormsModule`\n- `ReactiveFormsModule`\n\n### CSS imports\n\nIn your top level stylesheet, add these imports:\n\n```css\n@import '~@terminus/design-tokens/css/library-design-tokens.css';\n@import '~@terminus/ui-styles/terminus-ui.css';\n``` \n\n### CSS resources\n\nLoad the needed font families by adding this link to the `` of your application:\n\n```css\n\n```\n\n## Usage\n\nAttach an `NgModel` or `FormControl` to the input:\n\n```html\n\n\n\n```\n\nWe should _almost always_ being using a `FormControl`.\n\n> Note: If you don't need a full form group you can provide a stand-alone control: `myControl = new FormControl();`\n\n### Hint\n\nA 'hint' can be displayed below the input on the right-hand side. This should be used for helpful user information such as input\nrequirements.\n\n```html\n\n```\n\n### No validation or hint\n\nA flag to define whether this input field needs validation or hint. If it needs validation or hint, a padding bottom is added for the message, otherwise, no padding at the bottom.\n\n```html\n\n```\n\n### Prefix icon\n\nTo include an icon as a prefix to the input, pass a valid icon instance to `prefixIcon`:\n\n```typescript\nimport { faHome } from '@fortawesome/pro-solid-svg-icons/faHome';\n...\npublic home = faHome;\n```\n\n```html\n\n```\n\n> See all valid icon possibilities: \n\n### Disabled\n\nInputs can be disabled by setting the component flag OR by setting the associated `FormControl` to `disabled`.\n\nThe `isDisabled` flag works with both `ngModel` and `FormControl` inputs:\n\n```html\n\n```\n\nWhen using Reactive Forms, controls should be disabled via the control:\n\n```typescript\nmyControl: FormControl = new FormControl({value: null, disabled: true});\n```\n\n### Required\n\nWhen using a `FormControl`, set the required validator on the control:\n\n```typescript\nmyControl = new FormControl(null, Validators.required);\n```\n\nWhen using `ngModel`, validations are placed on the input as data-attributes (just like native HTML inputs):\n\n```html\n\n```\n\nIf only the required asterisk is needed rather than validation errors, the `isRequired` flag can be used:\n\n```html\n\n```\n\n#### Required asterisk `*`\n\nIf the input should be required, but the required asterisk `*` is not needed, disable it with the\n`hideRequiredMarker` input:\n\n```html\n\n```\n\n> NOTE: We should not hide this visual indicator without a very good reason!\n\n### Clearable\n\nIf the input should be easily reset, include the `isClearable` flag to enable a 'clear input'\nbutton: (button will appear as small `x` icon at the far right of the input)\n\n```html\n\n```\n\nWhen the input is cleared, the `cleared` event emitter will be fired with the value `true`.\n\n### Focused\n\nAuto-focus the input when the view loads:\n\n```html\n\n```\n\n> NOTE: If multiple inputs within the same view set `isFocused` to true, the _**last one rendered\n> will receive the final focus**_.\n\nThis can also be used to dynamically focus an existing input:\n\n```html\n\n```\n\n```typescript\nmyFocusedFlag = false;\n\ntoggleInputFocus() {\n this.myFocusedFlag = !this.myFocusedFlag;\n}\n```\n\n### Input Type\n\nThe input type can be defined with the type input:\n\n```html\n\n```\n\n> For all allowed types, see `TsInputTypes`.\n\n### Input Attributes\n\n`autocapitalize`, `autocomplete`, `spellcheck`, `readonly`\n\n```html\n\n```\n\n> For all allowed `autocomplete` types, see `TsInputAutocompleteTypes`.\n\n### Validation timing\n\nValidate on change rather than blur:\n\n```html\n\n```\n\n### Component reference\n\nTo get a reference to the component class, assign the exported name to a local variable:\n\n```html\n\n```\n\n```typescript\n@ViewChild(TsInputComponent, {static: false})\nmyVar: TsInputComponent;\n\nconsole.log('Component Class: ', this.myVar);\n```\n\n### Usage with Reactive Forms\n\nPass in the form control:\n\n```html\n\n```\n\n```typescript\nmyForm = this.formBuilder.group({\n date: [\n null, // If you need a default value, change this `null` to your value\n [\n Validators.required,\n ],\n ],\n});\n```\n\n**NOTE:** If using a form with nested form groups, _each group_ must be created with\n`formBuilder.group` for the form `get` control to work:\n\n```typescript\n// Notice the nested `dateRange` object without using `.group`\nmyForm: FormGroup = this.formBuilder.group({\n dateRange: {\n startDate: [\n new Date(2017, 4, 6),\n ],\n endDate: [\n new Date(2017, 4, 8),\n ],\n },\n});\n\n// THIS WILL FAIL!\nconst range = myForm.get('dateRange');\n\n//////////////////////////////////////////////////\n\n// Notice the nested `dateRange` object IS using `.group`\nmyForm: FormGroup = this.formBuilder.group({\n dateRange: this.formBuilder.group({\n startDate: [\n new Date(2017, 4, 6),\n [\n Validators.required,\n ],\n ],\n endDate: [\n new Date(2017, 4, 8),\n [\n Validators.required,\n ],\n ],\n }),\n});\n\n// Now there is a group for us to 'get'\nconst range = myForm.get('dateRange');\n```\n\n### Event Emitters\n\nSupported event emitters:\n\n```html\n\n```\n\n> NOTE: The `selected` input is only available when `datepicker` is true.\n\n### Masks\n\nMasks enable the input to enforce specific formatting for values; such as postal codes: `12345-1234`.\n\n#### Available Masks\n\n| Mask | Input value | Masked Value |\n|--------------|--------------|------------------|\n| `currency` | `12.34` | `$12.34` |\n| `date` | `12121982` | `12-12-1982` |\n| `number` | `1234.56` | `1,234.56` |\n| `percentage` | `12.4` | `12.4%` |\n| `phone` | `1231231234` | `(123) 123-1234` |\n| `postal` | `123456789` | `12345-6789` |\n\n#### Sanitize the model value\n\nMost often you will not want the mask characters to be saved as part of the actual value. By default this component will sanitize the value\nbefore saving it to the model. This can be disabled if needed:\n\n```html\n\n```\n\nThis setup will format the value displayed in the UI: `(123) 456-7890`)while saving the pure value to the model: `1234567890`.\n\n#### Allow decimals in number-based masks\n\nBy default, number based masks (`number`, `percentage`) allow decimals. This can be disabled:\n\n```html\n\n```\n\nThis means when the user types `12.34`, the input UI and model value will both be `1234`.\n\n### Datepicker\n\nTo add datepicker abilities to an input, set the `datepicker` input:\n\n```html\n\n```\n\n#### Filter out available dates\n\nIf, for instance, you need to prohibit weekend days (sat/sun) from being selected you can pass in a\ncustom method to filter dates:\n\n```html\n\n```\n\n```typescript\nmyFilter = (d: Date): boolean => {\n const day = d.getDay();\n // Prevent Saturday and Sunday from being selected.\n return day !== 0 && day !== 6;\n}\n```\n\n#### Set a max/min date range\n\nTo define bounds for date selection, pass in a valid `Date` to `minDate` and/or `maxDate`:\n\n```html\n\n```\n\n```typescript\ndate1 = new Date(2017, 2, 1);\ndate2 = new Date(2017, 8, 1);\n```\n\n#### Open calendar to a specific date\n\nPass in a `Date` to `openTo`:\n\n```html\n\n```\n\n```typescript\nmyDate = new Date(2017, 5, 12);\n```\n\n#### Open calendar to a specific view\n\nBy default, the calendar opens up to show the month view. This can be changed to show the year view initially:\n\n```html\n\n```\n\n`year` and `month` are the only two valid values.\n\n#### Example with dynamic validation\n\nWe can recreate a version of the {@link TsDateRangeComponent} using dynamic validation:\n\n```html\n\n```\n\n```typescript\nmyForm = this.formBuilder.group({\n startDate: [\n null,\n [\n Validators.required,\n ],\n ],\n endDate: [\n null,\n [\n Validators.required,\n ],\n ],\n});\n\n// When the startDate changes, we want to set that date as the minDate for the endDate\nrangeStartChange(event: MatDatepickerInputEvent) {\n if (event) {\n // Get the from control\n const control = this.formTwo.get('endDate');\n\n // Set all validators.\n // NOTE: setting validators will clear ALL existing validators, so we must add the required\n // validator here again\n control.setValidators([\n Validators.required,\n this.validatorsService.minDate(event.value),\n ]);\n // Tell the control to update according to the new validators\n control.updateValueAndValidity();\n }\n}\n\n// When the endDate changes, we want to set that date as the maxDate for the startDate\nrangeEndChange(event: MatDatepickerInputEvent) {\n if (event) {\n // Get the from control\n const control = this.formTwo.get('startDate');\n\n // Set all validators.\n // NOTE: setting validators will clear ALL existing validators, so we must add the required\n // validator here again\n control.setValidators([\n Validators.required,\n this.validatorsService.maxDate(event.value),\n ]);\n // Tell the control to update according to the new validators\n control.updateValueAndValidity();\n }\n}\n```\n\n### Textarea\n\nSwitch from a standard input to a textarea:\n\n```html\n\n```\n\n#### Rows\n\nThe row count can be dynamically adjusted:\n\n```html\n\n```\n\n## Test Helpers\n\nSome helpers are exposed to assist with testing. These are imported from `@terminus/ui-input/testing`;\n\n[[source]][test-helpers-src]\n\n| Function |\n|------------------------|\n| `getAllInputInstances` |\n| `getInputInstance` |\n| `getInputElement` |\n| `sendInput` |\n\n\n[test-helpers-src]: testing/src/test-helpers.ts\n[license-url]: https://github.com/GetTerminus/terminus-oss/blob/release/LICENSE\n[license-image]: http://img.shields.io/badge/license-MIT-blue.svg\n[codecov-project]: https://codecov.io/gh/GetTerminus/terminus-oss\n[codecov-badge]: https://codecov.io/gh/GetTerminus/terminus-oss/branch/release/graph/badge.svg\n[npm-version-image]: http://img.shields.io/npm/v/@terminus/ui-input.svg\n[npm-package]: https://www.npmjs.com/package/@terminus/ui-input\n[github-action-badge]: https://github.com/GetTerminus/terminus-oss/workflows/Release%20CI/badge.svg\n[github-action-link]: https://github.com/GetTerminus/terminus-oss/actions?query=workflow%3A%22CI+Release%22\n[file-size-badge]: http://img.badgesize.io/https://unpkg.com/@terminus/ui-input/bundles/terminus-ui-input.umd.min.js?compression=gzip\n[raw-distribution-js]: https://unpkg.com/@terminus/ui-input/bundles/terminus-ui-input.umd.js\n","readmeFilename":"README.md","description":"
\n\n[![CI/CD Status][github-action-badge]][github-action-link] [![Codecov][codecov-badge]][codecov-project] [![MIT License][license-image]][license-url] \n[![NPM version][npm-version-image]][npm-package] [![Library size][file-size-badge]][raw-distribution-js]\n\n\n\n## Table of Contents\n\n- [Installation](#installation)\n - [Packages that need to be installed](#packages-that-need-to-be-installed)\n - [Modules that need to be in NgModule](#modules-that-need-to-be-in-ngmodule)\n - [CSS imports](#css-imports)\n - [CSS resources](#css-resources)\n- [Usage](#usage)\n - [Hint](#hint)\n - [No validation or hint](#no-validation-or-hint)\n - [Prefix icon](#prefix-icon)\n - [Disabled](#disabled)\n - [Required](#required)\n - [Required asterisk `*`](#required-asterisk-)\n - [Clearable](#clearable)\n - [Focused](#focused)\n - [Input Type](#input-type)\n - [Input Attributes](#input-attributes)\n - [Validation timing](#validation-timing)\n - [Component reference](#component-reference)\n - [Usage with Reactive Forms](#usage-with-reactive-forms)\n - [Event Emitters](#event-emitters)\n - [Masks](#masks)\n - [Available Masks](#available-masks)\n - [Sanitize the model value](#sanitize-the-model-value)\n - [Allow decimals in number-based masks](#allow-decimals-in-number-based-masks)\n - [Datepicker](#datepicker)\n - [Filter out available dates](#filter-out-available-dates)\n - [Set a max/min date range](#set-a-maxmin-date-range)\n - [Open calendar to a specific date](#open-calendar-to-a-specific-date)\n - [Open calendar to a specific view](#open-calendar-to-a-specific-view)\n - [Example with dynamic validation](#example-with-dynamic-validation)\n - [Textarea](#textarea)\n - [Rows](#rows)\n- [Test Helpers](#test-helpers)\n\n\n\n## Installation\n\n### Packages that need to be installed\n\n- `@angular/cdk`\n- `@angular/flex-layout`\n- `@angular/material`\n- `@terminus/design-tokens`\n- `@terminus/fe-utilities`\n- `@terminus/ui-form-field`\n- `@terminus/ui-icon`\n- `@terminus/ui-input`\n- `@terminus/ui-pipes`\n- `@terminus/ui-spacing`\n- `@terminus/ui-styles`\n- `@terminus/ui-utilities`\n- `@terminus/ui-validation-messages`\n- `@terminus/ui-validators`\n- `date-fns`\n- `text-mask-addons`\n- `text-mask-core`\n\nUse the `ng add` command to quickly install all the needed dependencies:\n\n```bash\nng add @terminus/ui-input\n```\n\n### Modules that need to be in NgModule\n\n- `BrowserAnimationsModule`\n- `TsInputModule`\n- `FormsModule`\n- `ReactiveFormsModule`\n\n### CSS imports\n\nIn your top level stylesheet, add these imports:\n\n```css\n@import '~@terminus/design-tokens/css/library-design-tokens.css';\n@import '~@terminus/ui-styles/terminus-ui.css';\n``` \n\n### CSS resources\n\nLoad the needed font families by adding this link to the `` of your application:\n\n```css\n\n```\n\n## Usage\n\nAttach an `NgModel` or `FormControl` to the input:\n\n```html\n\n\n\n```\n\nWe should _almost always_ being using a `FormControl`.\n\n> Note: If you don't need a full form group you can provide a stand-alone control: `myControl = new FormControl();`\n\n### Hint\n\nA 'hint' can be displayed below the input on the right-hand side. This should be used for helpful user information such as input\nrequirements.\n\n```html\n\n```\n\n### No validation or hint\n\nA flag to define whether this input field needs validation or hint. If it needs validation or hint, a padding bottom is added for the message, otherwise, no padding at the bottom.\n\n```html\n\n```\n\n### Prefix icon\n\nTo include an icon as a prefix to the input, pass a valid icon instance to `prefixIcon`:\n\n```typescript\nimport { faHome } from '@fortawesome/pro-solid-svg-icons/faHome';\n...\npublic home = faHome;\n```\n\n```html\n\n```\n\n> See all valid icon possibilities: \n\n### Disabled\n\nInputs can be disabled by setting the component flag OR by setting the associated `FormControl` to `disabled`.\n\nThe `isDisabled` flag works with both `ngModel` and `FormControl` inputs:\n\n```html\n\n```\n\nWhen using Reactive Forms, controls should be disabled via the control:\n\n```typescript\nmyControl: FormControl = new FormControl({value: null, disabled: true});\n```\n\n### Required\n\nWhen using a `FormControl`, set the required validator on the control:\n\n```typescript\nmyControl = new FormControl(null, Validators.required);\n```\n\nWhen using `ngModel`, validations are placed on the input as data-attributes (just like native HTML inputs):\n\n```html\n\n```\n\nIf only the required asterisk is needed rather than validation errors, the `isRequired` flag can be used:\n\n```html\n\n```\n\n#### Required asterisk `*`\n\nIf the input should be required, but the required asterisk `*` is not needed, disable it with the\n`hideRequiredMarker` input:\n\n```html\n\n```\n\n> NOTE: We should not hide this visual indicator without a very good reason!\n\n### Clearable\n\nIf the input should be easily reset, include the `isClearable` flag to enable a 'clear input'\nbutton: (button will appear as small `x` icon at the far right of the input)\n\n```html\n\n```\n\nWhen the input is cleared, the `cleared` event emitter will be fired with the value `true`.\n\n### Focused\n\nAuto-focus the input when the view loads:\n\n```html\n\n```\n\n> NOTE: If multiple inputs within the same view set `isFocused` to true, the _**last one rendered\n> will receive the final focus**_.\n\nThis can also be used to dynamically focus an existing input:\n\n```html\n\n```\n\n```typescript\nmyFocusedFlag = false;\n\ntoggleInputFocus() {\n this.myFocusedFlag = !this.myFocusedFlag;\n}\n```\n\n### Input Type\n\nThe input type can be defined with the type input:\n\n```html\n\n```\n\n> For all allowed types, see `TsInputTypes`.\n\n### Input Attributes\n\n`autocapitalize`, `autocomplete`, `spellcheck`, `readonly`\n\n```html\n\n```\n\n> For all allowed `autocomplete` types, see `TsInputAutocompleteTypes`.\n\n### Validation timing\n\nValidate on change rather than blur:\n\n```html\n\n```\n\n### Component reference\n\nTo get a reference to the component class, assign the exported name to a local variable:\n\n```html\n\n```\n\n```typescript\n@ViewChild(TsInputComponent, {static: false})\nmyVar: TsInputComponent;\n\nconsole.log('Component Class: ', this.myVar);\n```\n\n### Usage with Reactive Forms\n\nPass in the form control:\n\n```html\n\n```\n\n```typescript\nmyForm = this.formBuilder.group({\n date: [\n null, // If you need a default value, change this `null` to your value\n [\n Validators.required,\n ],\n ],\n});\n```\n\n**NOTE:** If using a form with nested form groups, _each group_ must be created with\n`formBuilder.group` for the form `get` control to work:\n\n```typescript\n// Notice the nested `dateRange` object without using `.group`\nmyForm: FormGroup = this.formBuilder.group({\n dateRange: {\n startDate: [\n new Date(2017, 4, 6),\n ],\n endDate: [\n new Date(2017, 4, 8),\n ],\n },\n});\n\n// THIS WILL FAIL!\nconst range = myForm.get('dateRange');\n\n//////////////////////////////////////////////////\n\n// Notice the nested `dateRange` object IS using `.group`\nmyForm: FormGroup = this.formBuilder.group({\n dateRange: this.formBuilder.group({\n startDate: [\n new Date(2017, 4, 6),\n [\n Validators.required,\n ],\n ],\n endDate: [\n new Date(2017, 4, 8),\n [\n Validators.required,\n ],\n ],\n }),\n});\n\n// Now there is a group for us to 'get'\nconst range = myForm.get('dateRange');\n```\n\n### Event Emitters\n\nSupported event emitters:\n\n```html\n\n```\n\n> NOTE: The `selected` input is only available when `datepicker` is true.\n\n### Masks\n\nMasks enable the input to enforce specific formatting for values; such as postal codes: `12345-1234`.\n\n#### Available Masks\n\n| Mask | Input value | Masked Value |\n|--------------|--------------|------------------|\n| `currency` | `12.34` | `$12.34` |\n| `date` | `12121982` | `12-12-1982` |\n| `number` | `1234.56` | `1,234.56` |\n| `percentage` | `12.4` | `12.4%` |\n| `phone` | `1231231234` | `(123) 123-1234` |\n| `postal` | `123456789` | `12345-6789` |\n\n#### Sanitize the model value\n\nMost often you will not want the mask characters to be saved as part of the actual value. By default this component will sanitize the value\nbefore saving it to the model. This can be disabled if needed:\n\n```html\n\n```\n\nThis setup will format the value displayed in the UI: `(123) 456-7890`)while saving the pure value to the model: `1234567890`.\n\n#### Allow decimals in number-based masks\n\nBy default, number based masks (`number`, `percentage`) allow decimals. This can be disabled:\n\n```html\n\n```\n\nThis means when the user types `12.34`, the input UI and model value will both be `1234`.\n\n### Datepicker\n\nTo add datepicker abilities to an input, set the `datepicker` input:\n\n```html\n\n```\n\n#### Filter out available dates\n\nIf, for instance, you need to prohibit weekend days (sat/sun) from being selected you can pass in a\ncustom method to filter dates:\n\n```html\n\n```\n\n```typescript\nmyFilter = (d: Date): boolean => {\n const day = d.getDay();\n // Prevent Saturday and Sunday from being selected.\n return day !== 0 && day !== 6;\n}\n```\n\n#### Set a max/min date range\n\nTo define bounds for date selection, pass in a valid `Date` to `minDate` and/or `maxDate`:\n\n```html\n\n```\n\n```typescript\ndate1 = new Date(2017, 2, 1);\ndate2 = new Date(2017, 8, 1);\n```\n\n#### Open calendar to a specific date\n\nPass in a `Date` to `openTo`:\n\n```html\n\n```\n\n```typescript\nmyDate = new Date(2017, 5, 12);\n```\n\n#### Open calendar to a specific view\n\nBy default, the calendar opens up to show the month view. This can be changed to show the year view initially:\n\n```html\n\n```\n\n`year` and `month` are the only two valid values.\n\n#### Example with dynamic validation\n\nWe can recreate a version of the {@link TsDateRangeComponent} using dynamic validation:\n\n```html\n\n```\n\n```typescript\nmyForm = this.formBuilder.group({\n startDate: [\n null,\n [\n Validators.required,\n ],\n ],\n endDate: [\n null,\n [\n Validators.required,\n ],\n ],\n});\n\n// When the startDate changes, we want to set that date as the minDate for the endDate\nrangeStartChange(event: MatDatepickerInputEvent) {\n if (event) {\n // Get the from control\n const control = this.formTwo.get('endDate');\n\n // Set all validators.\n // NOTE: setting validators will clear ALL existing validators, so we must add the required\n // validator here again\n control.setValidators([\n Validators.required,\n this.validatorsService.minDate(event.value),\n ]);\n // Tell the control to update according to the new validators\n control.updateValueAndValidity();\n }\n}\n\n// When the endDate changes, we want to set that date as the maxDate for the startDate\nrangeEndChange(event: MatDatepickerInputEvent) {\n if (event) {\n // Get the from control\n const control = this.formTwo.get('startDate');\n\n // Set all validators.\n // NOTE: setting validators will clear ALL existing validators, so we must add the required\n // validator here again\n control.setValidators([\n Validators.required,\n this.validatorsService.maxDate(event.value),\n ]);\n // Tell the control to update according to the new validators\n control.updateValueAndValidity();\n }\n}\n```\n\n### Textarea\n\nSwitch from a standard input to a textarea:\n\n```html\n\n```\n\n#### Rows\n\nThe row count can be dynamically adjusted:\n\n```html\n\n```\n\n## Test Helpers\n\nSome helpers are exposed to assist with testing. These are imported from `@terminus/ui-input/testing`;\n\n[[source]][test-helpers-src]\n\n| Function |\n|------------------------|\n| `getAllInputInstances` |\n| `getInputInstance` |\n| `getInputElement` |\n| `sendInput` |\n\n\n[test-helpers-src]: testing/src/test-helpers.ts\n[license-url]: https://github.com/GetTerminus/terminus-oss/blob/release/LICENSE\n[license-image]: http://img.shields.io/badge/license-MIT-blue.svg\n[codecov-project]: https://codecov.io/gh/GetTerminus/terminus-oss\n[codecov-badge]: https://codecov.io/gh/GetTerminus/terminus-oss/branch/release/graph/badge.svg\n[npm-version-image]: http://img.shields.io/npm/v/@terminus/ui-input.svg\n[npm-package]: https://www.npmjs.com/package/@terminus/ui-input\n[github-action-badge]: https://github.com/GetTerminus/terminus-oss/workflows/Release%20CI/badge.svg\n[github-action-link]: https://github.com/GetTerminus/terminus-oss/actions?query=workflow%3A%22CI+Release%22\n[file-size-badge]: http://img.badgesize.io/https://unpkg.com/@terminus/ui-input/bundles/terminus-ui-input.umd.min.js?compression=gzip\n[raw-distribution-js]: https://unpkg.com/@terminus/ui-input/bundles/terminus-ui-input.umd.js\n","readmeFilename":"README.md","description":"
\n\n[![CI/CD Status][github-action-badge]][github-action-link] [![Codecov][codecov-badge]][codecov-project] [![MIT License][license-image]][license-url] \n[![NPM version][npm-version-image]][npm-package] [![Library size][file-size-badge]][raw-distribution-js]\n\n\n\n## Table of Contents\n\n- [Installation](#installation)\n - [Packages that need to be installed](#packages-that-need-to-be-installed)\n - [Modules that need to be in NgModule](#modules-that-need-to-be-in-ngmodule)\n - [CSS imports](#css-imports)\n - [CSS resources](#css-resources)\n- [Usage](#usage)\n - [Hint](#hint)\n - [No validation or hint](#no-validation-or-hint)\n - [Prefix icon](#prefix-icon)\n - [Disabled](#disabled)\n - [Required](#required)\n - [Required asterisk `*`](#required-asterisk-)\n - [Clearable](#clearable)\n - [Focused](#focused)\n - [Input Type](#input-type)\n - [Input Attributes](#input-attributes)\n - [Validation timing](#validation-timing)\n - [Component reference](#component-reference)\n - [Usage with Reactive Forms](#usage-with-reactive-forms)\n - [Event Emitters](#event-emitters)\n - [Masks](#masks)\n - [Available Masks](#available-masks)\n - [Sanitize the model value](#sanitize-the-model-value)\n - [Allow decimals in number-based masks](#allow-decimals-in-number-based-masks)\n - [Datepicker](#datepicker)\n - [Filter out available dates](#filter-out-available-dates)\n - [Set a max/min date range](#set-a-maxmin-date-range)\n - [Open calendar to a specific date](#open-calendar-to-a-specific-date)\n - [Open calendar to a specific view](#open-calendar-to-a-specific-view)\n - [Example with dynamic validation](#example-with-dynamic-validation)\n - [Textarea](#textarea)\n - [Rows](#rows)\n- [Test Helpers](#test-helpers)\n\n\n\n## Installation\n\n### Packages that need to be installed\n\n- `@angular/cdk`\n- `@angular/flex-layout`\n- `@angular/material`\n- `@terminus/design-tokens`\n- `@terminus/fe-utilities`\n- `@terminus/ui-form-field`\n- `@terminus/ui-icon`\n- `@terminus/ui-input`\n- `@terminus/ui-pipes`\n- `@terminus/ui-spacing`\n- `@terminus/ui-styles`\n- `@terminus/ui-utilities`\n- `@terminus/ui-validation-messages`\n- `@terminus/ui-validators`\n- `date-fns`\n- `text-mask-addons`\n- `text-mask-core`\n\nUse the `ng add` command to quickly install all the needed dependencies:\n\n```bash\nng add @terminus/ui-input\n```\n\n### Modules that need to be in NgModule\n\n- `BrowserAnimationsModule`\n- `TsInputModule`\n- `FormsModule`\n- `ReactiveFormsModule`\n\n### CSS imports\n\nIn your top level stylesheet, add these imports:\n\n```css\n@import '~@terminus/design-tokens/css/library-design-tokens.css';\n@import '~@terminus/ui-styles/terminus-ui.css';\n``` \n\n### CSS resources\n\nLoad the needed font families by adding this link to the `` of your application:\n\n```css\n\n```\n\n## Usage\n\nAttach an `NgModel` or `FormControl` to the input:\n\n```html\n\n\n\n```\n\nWe should _almost always_ being using a `FormControl`.\n\n> Note: If you don't need a full form group you can provide a stand-alone control: `myControl = new FormControl();`\n\n### Hint\n\nA 'hint' can be displayed below the input on the right-hand side. This should be used for helpful user information such as input\nrequirements.\n\n```html\n\n```\n\n### No validation or hint\n\nA flag to define whether this input field needs validation or hint. If it needs validation or hint, a padding bottom is added for the message, otherwise, no padding at the bottom.\n\n```html\n\n```\n\n### Prefix icon\n\nTo include an icon as a prefix to the input, pass a valid icon instance to `prefixIcon`:\n\n```typescript\nimport { faHome } from '@fortawesome/pro-solid-svg-icons/faHome';\n...\npublic home = faHome;\n```\n\n```html\n\n```\n\n> See all valid icon possibilities: \n\n### Disabled\n\nInputs can be disabled by setting the component flag OR by setting the associated `FormControl` to `disabled`.\n\nThe `isDisabled` flag works with both `ngModel` and `FormControl` inputs:\n\n```html\n\n```\n\nWhen using Reactive Forms, controls should be disabled via the control:\n\n```typescript\nmyControl: FormControl = new FormControl({value: null, disabled: true});\n```\n\n### Required\n\nWhen using a `FormControl`, set the required validator on the control:\n\n```typescript\nmyControl = new FormControl(null, Validators.required);\n```\n\nWhen using `ngModel`, validations are placed on the input as data-attributes (just like native HTML inputs):\n\n```html\n\n```\n\nIf only the required asterisk is needed rather than validation errors, the `isRequired` flag can be used:\n\n```html\n\n```\n\n#### Required asterisk `*`\n\nIf the input should be required, but the required asterisk `*` is not needed, disable it with the\n`hideRequiredMarker` input:\n\n```html\n\n```\n\n> NOTE: We should not hide this visual indicator without a very good reason!\n\n### Clearable\n\nIf the input should be easily reset, include the `isClearable` flag to enable a 'clear input'\nbutton: (button will appear as small `x` icon at the far right of the input)\n\n```html\n\n```\n\nWhen the input is cleared, the `cleared` event emitter will be fired with the value `true`.\n\n### Focused\n\nAuto-focus the input when the view loads:\n\n```html\n\n```\n\n> NOTE: If multiple inputs within the same view set `isFocused` to true, the _**last one rendered\n> will receive the final focus**_.\n\nThis can also be used to dynamically focus an existing input:\n\n```html\n\n```\n\n```typescript\nmyFocusedFlag = false;\n\ntoggleInputFocus() {\n this.myFocusedFlag = !this.myFocusedFlag;\n}\n```\n\n### Input Type\n\nThe input type can be defined with the type input:\n\n```html\n\n```\n\n> For all allowed types, see `TsInputTypes`.\n\n### Input Attributes\n\n`autocapitalize`, `autocomplete`, `spellcheck`, `readonly`\n\n```html\n\n```\n\n> For all allowed `autocomplete` types, see `TsInputAutocompleteTypes`.\n\n### Validation timing\n\nValidate on change rather than blur:\n\n```html\n\n```\n\n### Component reference\n\nTo get a reference to the component class, assign the exported name to a local variable:\n\n```html\n\n```\n\n```typescript\n@ViewChild(TsInputComponent, {static: false})\nmyVar: TsInputComponent;\n\nconsole.log('Component Class: ', this.myVar);\n```\n\n### Usage with Reactive Forms\n\nPass in the form control:\n\n```html\n\n```\n\n```typescript\nmyForm = this.formBuilder.group({\n date: [\n null, // If you need a default value, change this `null` to your value\n [\n Validators.required,\n ],\n ],\n});\n```\n\n**NOTE:** If using a form with nested form groups, _each group_ must be created with\n`formBuilder.group` for the form `get` control to work:\n\n```typescript\n// Notice the nested `dateRange` object without using `.group`\nmyForm: FormGroup = this.formBuilder.group({\n dateRange: {\n startDate: [\n new Date(2017, 4, 6),\n ],\n endDate: [\n new Date(2017, 4, 8),\n ],\n },\n});\n\n// THIS WILL FAIL!\nconst range = myForm.get('dateRange');\n\n//////////////////////////////////////////////////\n\n// Notice the nested `dateRange` object IS using `.group`\nmyForm: FormGroup = this.formBuilder.group({\n dateRange: this.formBuilder.group({\n startDate: [\n new Date(2017, 4, 6),\n [\n Validators.required,\n ],\n ],\n endDate: [\n new Date(2017, 4, 8),\n [\n Validators.required,\n ],\n ],\n }),\n});\n\n// Now there is a group for us to 'get'\nconst range = myForm.get('dateRange');\n```\n\n### Event Emitters\n\nSupported event emitters:\n\n```html\n\n```\n\n> NOTE: The `selected` input is only available when `datepicker` is true.\n\n### Masks\n\nMasks enable the input to enforce specific formatting for values; such as postal codes: `12345-1234`.\n\n#### Available Masks\n\n| Mask | Input value | Masked Value |\n|--------------|--------------|------------------|\n| `currency` | `12.34` | `$12.34` |\n| `date` | `12121982` | `12-12-1982` |\n| `number` | `1234.56` | `1,234.56` |\n| `percentage` | `12.4` | `12.4%` |\n| `phone` | `1231231234` | `(123) 123-1234` |\n| `postal` | `123456789` | `12345-6789` |\n\n#### Sanitize the model value\n\nMost often you will not want the mask characters to be saved as part of the actual value. By default this component will sanitize the value\nbefore saving it to the model. This can be disabled if needed:\n\n```html\n\n```\n\nThis setup will format the value displayed in the UI: `(123) 456-7890`)while saving the pure value to the model: `1234567890`.\n\n#### Allow decimals in number-based masks\n\nBy default, number based masks (`number`, `percentage`) allow decimals. This can be disabled:\n\n```html\n\n```\n\nThis means when the user types `12.34`, the input UI and model value will both be `1234`.\n\n### Datepicker\n\nTo add datepicker abilities to an input, set the `datepicker` input:\n\n```html\n\n```\n\n#### Filter out available dates\n\nIf, for instance, you need to prohibit weekend days (sat/sun) from being selected you can pass in a\ncustom method to filter dates:\n\n```html\n\n```\n\n```typescript\nmyFilter = (d: Date): boolean => {\n const day = d.getDay();\n // Prevent Saturday and Sunday from being selected.\n return day !== 0 && day !== 6;\n}\n```\n\n#### Set a max/min date range\n\nTo define bounds for date selection, pass in a valid `Date` to `minDate` and/or `maxDate`:\n\n```html\n\n```\n\n```typescript\ndate1 = new Date(2017, 2, 1);\ndate2 = new Date(2017, 8, 1);\n```\n\n#### Open calendar to a specific date\n\nPass in a `Date` to `openTo`:\n\n```html\n\n```\n\n```typescript\nmyDate = new Date(2017, 5, 12);\n```\n\n#### Open calendar to a specific view\n\nBy default, the calendar opens up to show the month view. This can be changed to show the year view initially:\n\n```html\n\n```\n\n`year` and `month` are the only two valid values.\n\n#### Example with dynamic validation\n\nWe can recreate a version of the {@link TsDateRangeComponent} using dynamic validation:\n\n```html\n\n```\n\n```typescript\nmyForm = this.formBuilder.group({\n startDate: [\n null,\n [\n Validators.required,\n ],\n ],\n endDate: [\n null,\n [\n Validators.required,\n ],\n ],\n});\n\n// When the startDate changes, we want to set that date as the minDate for the endDate\nrangeStartChange(event: MatDatepickerInputEvent) {\n if (event) {\n // Get the from control\n const control = this.formTwo.get('endDate');\n\n // Set all validators.\n // NOTE: setting validators will clear ALL existing validators, so we must add the required\n // validator here again\n control.setValidators([\n Validators.required,\n this.validatorsService.minDate(event.value),\n ]);\n // Tell the control to update according to the new validators\n control.updateValueAndValidity();\n }\n}\n\n// When the endDate changes, we want to set that date as the maxDate for the startDate\nrangeEndChange(event: MatDatepickerInputEvent) {\n if (event) {\n // Get the from control\n const control = this.formTwo.get('startDate');\n\n // Set all validators.\n // NOTE: setting validators will clear ALL existing validators, so we must add the required\n // validator here again\n control.setValidators([\n Validators.required,\n this.validatorsService.maxDate(event.value),\n ]);\n // Tell the control to update according to the new validators\n control.updateValueAndValidity();\n }\n}\n```\n\n### Textarea\n\nSwitch from a standard input to a textarea:\n\n```html\n\n```\n\n#### Rows\n\nThe row count can be dynamically adjusted:\n\n```html\n\n```\n\n## Test Helpers\n\nSome helpers are exposed to assist with testing. These are imported from `@terminus/ui-input/testing`;\n\n[[source]][test-helpers-src]\n\n| Function |\n|------------------------|\n| `getAllInputInstances` |\n| `getInputInstance` |\n| `getInputElement` |\n| `sendInput` |\n\n\n[test-helpers-src]: testing/src/test-helpers.ts\n[license-url]: https://github.com/GetTerminus/terminus-oss/blob/release/LICENSE\n[license-image]: http://img.shields.io/badge/license-MIT-blue.svg\n[codecov-project]: https://codecov.io/gh/GetTerminus/terminus-oss\n[codecov-badge]: https://codecov.io/gh/GetTerminus/terminus-oss/branch/release/graph/badge.svg\n[npm-version-image]: http://img.shields.io/npm/v/@terminus/ui-input.svg\n[npm-package]: https://www.npmjs.com/package/@terminus/ui-input\n[github-action-badge]: https://github.com/GetTerminus/terminus-oss/workflows/Release%20CI/badge.svg\n[github-action-link]: https://github.com/GetTerminus/terminus-oss/actions?query=workflow%3A%22CI+Release%22\n[file-size-badge]: http://img.badgesize.io/https://unpkg.com/@terminus/ui-input/bundles/terminus-ui-input.umd.min.js?compression=gzip\n[raw-distribution-js]: https://unpkg.com/@terminus/ui-input/bundles/terminus-ui-input.umd.js\n","readmeFilename":"README.md","description":"
\n\n[![CI/CD Status][github-action-badge]][github-action-link] [![Codecov][codecov-badge]][codecov-project] [![MIT License][license-image]][license-url] \n[![NPM version][npm-version-image]][npm-package] [![Library size][file-size-badge]][raw-distribution-js]\n\n\n\n## Table of Contents\n\n- [Installation](#installation)\n - [Packages that need to be installed](#packages-that-need-to-be-installed)\n - [Modules that need to be in NgModule](#modules-that-need-to-be-in-ngmodule)\n - [CSS imports](#css-imports)\n - [CSS resources](#css-resources)\n- [Usage](#usage)\n - [Hint](#hint)\n - [No validation or hint](#no-validation-or-hint)\n - [Prefix icon](#prefix-icon)\n - [Disabled](#disabled)\n - [Required](#required)\n - [Required asterisk `*`](#required-asterisk-)\n - [Clearable](#clearable)\n - [Focused](#focused)\n - [Input Type](#input-type)\n - [Input Attributes](#input-attributes)\n - [Validation timing](#validation-timing)\n - [Component reference](#component-reference)\n - [Usage with Reactive Forms](#usage-with-reactive-forms)\n - [Event Emitters](#event-emitters)\n - [Masks](#masks)\n - [Available Masks](#available-masks)\n - [Sanitize the model value](#sanitize-the-model-value)\n - [Allow decimals in number-based masks](#allow-decimals-in-number-based-masks)\n - [Datepicker](#datepicker)\n - [Filter out available dates](#filter-out-available-dates)\n - [Set a max/min date range](#set-a-maxmin-date-range)\n - [Open calendar to a specific date](#open-calendar-to-a-specific-date)\n - [Open calendar to a specific view](#open-calendar-to-a-specific-view)\n - [Example with dynamic validation](#example-with-dynamic-validation)\n - [Textarea](#textarea)\n - [Rows](#rows)\n- [Test Helpers](#test-helpers)\n\n\n\n## Installation\n\n### Packages that need to be installed\n\n- `@angular/cdk`\n- `@angular/flex-layout`\n- `@angular/material`\n- `@terminus/design-tokens`\n- `@terminus/fe-utilities`\n- `@terminus/ui-form-field`\n- `@terminus/ui-icon`\n- `@terminus/ui-input`\n- `@terminus/ui-pipes`\n- `@terminus/ui-spacing`\n- `@terminus/ui-styles`\n- `@terminus/ui-utilities`\n- `@terminus/ui-validation-messages`\n- `@terminus/ui-validators`\n- `date-fns`\n- `text-mask-addons`\n- `text-mask-core`\n\nUse the `ng add` command to quickly install all the needed dependencies:\n\n```bash\nng add @terminus/ui-input\n```\n\n### Modules that need to be in NgModule\n\n- `BrowserAnimationsModule`\n- `TsInputModule`\n- `FormsModule`\n- `ReactiveFormsModule`\n\n### CSS imports\n\nIn your top level stylesheet, add these imports:\n\n```css\n@import '~@terminus/design-tokens/css/library-design-tokens.css';\n@import '~@terminus/ui-styles/terminus-ui.css';\n``` \n\n### CSS resources\n\nLoad the needed font families by adding this link to the `` of your application:\n\n```css\n\n```\n\n## Usage\n\nAttach an `NgModel` or `FormControl` to the input:\n\n```html\n\n\n\n```\n\nWe should _almost always_ being using a `FormControl`.\n\n> Note: If you don't need a full form group you can provide a stand-alone control: `myControl = new FormControl();`\n\n### Hint\n\nA 'hint' can be displayed below the input on the right-hand side. This should be used for helpful user information such as input\nrequirements.\n\n```html\n\n```\n\n### No validation or hint\n\nA flag to define whether this input field needs validation or hint. If it needs validation or hint, a padding bottom is added for the message, otherwise, no padding at the bottom.\n\n```html\n\n```\n\n### Prefix icon\n\nTo include an icon as a prefix to the input, pass a valid icon instance to `prefixIcon`:\n\n```typescript\nimport { faHome } from '@fortawesome/pro-solid-svg-icons/faHome';\n...\npublic home = faHome;\n```\n\n```html\n\n```\n\n> See all valid icon possibilities: \n\n### Disabled\n\nInputs can be disabled by setting the component flag OR by setting the associated `FormControl` to `disabled`.\n\nThe `isDisabled` flag works with both `ngModel` and `FormControl` inputs:\n\n```html\n\n```\n\nWhen using Reactive Forms, controls should be disabled via the control:\n\n```typescript\nmyControl: FormControl = new FormControl({value: null, disabled: true});\n```\n\n### Required\n\nWhen using a `FormControl`, set the required validator on the control:\n\n```typescript\nmyControl = new FormControl(null, Validators.required);\n```\n\nWhen using `ngModel`, validations are placed on the input as data-attributes (just like native HTML inputs):\n\n```html\n\n```\n\nIf only the required asterisk is needed rather than validation errors, the `isRequired` flag can be used:\n\n```html\n\n```\n\n#### Required asterisk `*`\n\nIf the input should be required, but the required asterisk `*` is not needed, disable it with the\n`hideRequiredMarker` input:\n\n```html\n\n```\n\n> NOTE: We should not hide this visual indicator without a very good reason!\n\n### Clearable\n\nIf the input should be easily reset, include the `isClearable` flag to enable a 'clear input'\nbutton: (button will appear as small `x` icon at the far right of the input)\n\n```html\n\n```\n\nWhen the input is cleared, the `cleared` event emitter will be fired with the value `true`.\n\n### Focused\n\nAuto-focus the input when the view loads:\n\n```html\n\n```\n\n> NOTE: If multiple inputs within the same view set `isFocused` to true, the _**last one rendered\n> will receive the final focus**_.\n\nThis can also be used to dynamically focus an existing input:\n\n```html\n\n```\n\n```typescript\nmyFocusedFlag = false;\n\ntoggleInputFocus() {\n this.myFocusedFlag = !this.myFocusedFlag;\n}\n```\n\n### Input Type\n\nThe input type can be defined with the type input:\n\n```html\n\n```\n\n> For all allowed types, see `TsInputTypes`.\n\n### Input Attributes\n\n`autocapitalize`, `autocomplete`, `spellcheck`, `readonly`\n\n```html\n\n```\n\n> For all allowed `autocomplete` types, see `TsInputAutocompleteTypes`.\n\n### Validation timing\n\nValidate on change rather than blur:\n\n```html\n\n```\n\n### Component reference\n\nTo get a reference to the component class, assign the exported name to a local variable:\n\n```html\n\n```\n\n```typescript\n@ViewChild(TsInputComponent, {static: false})\nmyVar: TsInputComponent;\n\nconsole.log('Component Class: ', this.myVar);\n```\n\n### Usage with Reactive Forms\n\nPass in the form control:\n\n```html\n\n```\n\n```typescript\nmyForm = this.formBuilder.group({\n date: [\n null, // If you need a default value, change this `null` to your value\n [\n Validators.required,\n ],\n ],\n});\n```\n\n**NOTE:** If using a form with nested form groups, _each group_ must be created with\n`formBuilder.group` for the form `get` control to work:\n\n```typescript\n// Notice the nested `dateRange` object without using `.group`\nmyForm: FormGroup = this.formBuilder.group({\n dateRange: {\n startDate: [\n new Date(2017, 4, 6),\n ],\n endDate: [\n new Date(2017, 4, 8),\n ],\n },\n});\n\n// THIS WILL FAIL!\nconst range = myForm.get('dateRange');\n\n//////////////////////////////////////////////////\n\n// Notice the nested `dateRange` object IS using `.group`\nmyForm: FormGroup = this.formBuilder.group({\n dateRange: this.formBuilder.group({\n startDate: [\n new Date(2017, 4, 6),\n [\n Validators.required,\n ],\n ],\n endDate: [\n new Date(2017, 4, 8),\n [\n Validators.required,\n ],\n ],\n }),\n});\n\n// Now there is a group for us to 'get'\nconst range = myForm.get('dateRange');\n```\n\n### Event Emitters\n\nSupported event emitters:\n\n```html\n\n```\n\n> NOTE: The `selected` input is only available when `datepicker` is true.\n\n### Masks\n\nMasks enable the input to enforce specific formatting for values; such as postal codes: `12345-1234`.\n\n#### Available Masks\n\n| Mask | Input value | Masked Value |\n|--------------|--------------|------------------|\n| `currency` | `12.34` | `$12.34` |\n| `date` | `12121982` | `12-12-1982` |\n| `number` | `1234.56` | `1,234.56` |\n| `percentage` | `12.4` | `12.4%` |\n| `phone` | `1231231234` | `(123) 123-1234` |\n| `postal` | `123456789` | `12345-6789` |\n\n#### Sanitize the model value\n\nMost often you will not want the mask characters to be saved as part of the actual value. By default this component will sanitize the value\nbefore saving it to the model. This can be disabled if needed:\n\n```html\n\n```\n\nThis setup will format the value displayed in the UI: `(123) 456-7890`)while saving the pure value to the model: `1234567890`.\n\n#### Allow decimals in number-based masks\n\nBy default, number based masks (`number`, `percentage`) allow decimals. This can be disabled:\n\n```html\n\n```\n\nThis means when the user types `12.34`, the input UI and model value will both be `1234`.\n\n### Datepicker\n\nTo add datepicker abilities to an input, set the `datepicker` input:\n\n```html\n\n```\n\n#### Filter out available dates\n\nIf, for instance, you need to prohibit weekend days (sat/sun) from being selected you can pass in a\ncustom method to filter dates:\n\n```html\n\n```\n\n```typescript\nmyFilter = (d: Date): boolean => {\n const day = d.getDay();\n // Prevent Saturday and Sunday from being selected.\n return day !== 0 && day !== 6;\n}\n```\n\n#### Set a max/min date range\n\nTo define bounds for date selection, pass in a valid `Date` to `minDate` and/or `maxDate`:\n\n```html\n\n```\n\n```typescript\ndate1 = new Date(2017, 2, 1);\ndate2 = new Date(2017, 8, 1);\n```\n\n#### Open calendar to a specific date\n\nPass in a `Date` to `openTo`:\n\n```html\n\n```\n\n```typescript\nmyDate = new Date(2017, 5, 12);\n```\n\n#### Open calendar to a specific view\n\nBy default, the calendar opens up to show the month view. This can be changed to show the year view initially:\n\n```html\n\n```\n\n`year` and `month` are the only two valid values.\n\n#### Example with dynamic validation\n\nWe can recreate a version of the {@link TsDateRangeComponent} using dynamic validation:\n\n```html\n\n```\n\n```typescript\nmyForm = this.formBuilder.group({\n startDate: [\n null,\n [\n Validators.required,\n ],\n ],\n endDate: [\n null,\n [\n Validators.required,\n ],\n ],\n});\n\n// When the startDate changes, we want to set that date as the minDate for the endDate\nrangeStartChange(event: MatDatepickerInputEvent) {\n if (event) {\n // Get the from control\n const control = this.formTwo.get('endDate');\n\n // Set all validators.\n // NOTE: setting validators will clear ALL existing validators, so we must add the required\n // validator here again\n control.setValidators([\n Validators.required,\n this.validatorsService.minDate(event.value),\n ]);\n // Tell the control to update according to the new validators\n control.updateValueAndValidity();\n }\n}\n\n// When the endDate changes, we want to set that date as the maxDate for the startDate\nrangeEndChange(event: MatDatepickerInputEvent) {\n if (event) {\n // Get the from control\n const control = this.formTwo.get('startDate');\n\n // Set all validators.\n // NOTE: setting validators will clear ALL existing validators, so we must add the required\n // validator here again\n control.setValidators([\n Validators.required,\n this.validatorsService.maxDate(event.value),\n ]);\n // Tell the control to update according to the new validators\n control.updateValueAndValidity();\n }\n}\n```\n\n### Textarea\n\nSwitch from a standard input to a textarea:\n\n```html\n\n```\n\n#### Rows\n\nThe row count can be dynamically adjusted:\n\n```html\n\n```\n\n## Test Helpers\n\nSome helpers are exposed to assist with testing. These are imported from `@terminus/ui-input/testing`;\n\n[[source]][test-helpers-src]\n\n| Function |\n|------------------------|\n| `getAllInputInstances` |\n| `getInputInstance` |\n| `getInputElement` |\n| `sendInput` |\n\n\n[test-helpers-src]: testing/src/test-helpers.ts\n[license-url]: https://github.com/GetTerminus/terminus-oss/blob/release/LICENSE\n[license-image]: http://img.shields.io/badge/license-MIT-blue.svg\n[codecov-project]: https://codecov.io/gh/GetTerminus/terminus-oss\n[codecov-badge]: https://codecov.io/gh/GetTerminus/terminus-oss/branch/release/graph/badge.svg\n[npm-version-image]: http://img.shields.io/npm/v/@terminus/ui-input.svg\n[npm-package]: https://www.npmjs.com/package/@terminus/ui-input\n[github-action-badge]: https://github.com/GetTerminus/terminus-oss/workflows/Release%20CI/badge.svg\n[github-action-link]: https://github.com/GetTerminus/terminus-oss/actions?query=workflow%3A%22CI+Release%22\n[file-size-badge]: http://img.badgesize.io/https://unpkg.com/@terminus/ui-input/bundles/terminus-ui-input.umd.min.js?compression=gzip\n[raw-distribution-js]: https://unpkg.com/@terminus/ui-input/bundles/terminus-ui-input.umd.js\n","readmeFilename":"README.md","description":"
\n\n[![CI/CD Status][github-action-badge]][github-action-link] [![Codecov][codecov-badge]][codecov-project] [![MIT License][license-image]][license-url] \n[![NPM version][npm-version-image]][npm-package] [![Library size][file-size-badge]][raw-distribution-js]\n\n\n\n## Table of Contents\n\n- [Installation](#installation)\n - [Packages that need to be installed](#packages-that-need-to-be-installed)\n - [Modules that need to be in NgModule](#modules-that-need-to-be-in-ngmodule)\n - [CSS imports](#css-imports)\n - [CSS resources](#css-resources)\n- [Usage](#usage)\n - [Hint](#hint)\n - [No validation or hint](#no-validation-or-hint)\n - [Prefix icon](#prefix-icon)\n - [Disabled](#disabled)\n - [Required](#required)\n - [Required asterisk `*`](#required-asterisk-)\n - [Clearable](#clearable)\n - [Focused](#focused)\n - [Input Type](#input-type)\n - [Input Attributes](#input-attributes)\n - [Validation timing](#validation-timing)\n - [Component reference](#component-reference)\n - [Usage with Reactive Forms](#usage-with-reactive-forms)\n - [Event Emitters](#event-emitters)\n - [Masks](#masks)\n - [Available Masks](#available-masks)\n - [Sanitize the model value](#sanitize-the-model-value)\n - [Allow decimals in number-based masks](#allow-decimals-in-number-based-masks)\n - [Datepicker](#datepicker)\n - [Filter out available dates](#filter-out-available-dates)\n - [Set a max/min date range](#set-a-maxmin-date-range)\n - [Open calendar to a specific date](#open-calendar-to-a-specific-date)\n - [Open calendar to a specific view](#open-calendar-to-a-specific-view)\n - [Example with dynamic validation](#example-with-dynamic-validation)\n - [Textarea](#textarea)\n - [Rows](#rows)\n- [Test Helpers](#test-helpers)\n\n\n\n## Installation\n\n### Packages that need to be installed\n\n- `@angular/cdk`\n- `@angular/flex-layout`\n- `@angular/material`\n- `@terminus/design-tokens`\n- `@terminus/fe-utilities`\n- `@terminus/ui-form-field`\n- `@terminus/ui-icon`\n- `@terminus/ui-input`\n- `@terminus/ui-pipes`\n- `@terminus/ui-spacing`\n- `@terminus/ui-styles`\n- `@terminus/ui-utilities`\n- `@terminus/ui-validation-messages`\n- `@terminus/ui-validators`\n- `date-fns`\n- `text-mask-addons`\n- `text-mask-core`\n\nUse the `ng add` command to quickly install all the needed dependencies:\n\n```bash\nng add @terminus/ui-input\n```\n\n### Modules that need to be in NgModule\n\n- `BrowserAnimationsModule`\n- `TsInputModule`\n- `FormsModule`\n- `ReactiveFormsModule`\n\n### CSS imports\n\nIn your top level stylesheet, add these imports:\n\n```css\n@import '~@terminus/design-tokens/css/library-design-tokens.css';\n@import '~@terminus/ui-styles/terminus-ui.css';\n``` \n\n### CSS resources\n\nLoad the needed font families by adding this link to the `` of your application:\n\n```css\n\n```\n\n## Usage\n\nAttach an `NgModel` or `FormControl` to the input:\n\n```html\n\n\n\n```\n\nWe should _almost always_ being using a `FormControl`.\n\n> Note: If you don't need a full form group you can provide a stand-alone control: `myControl = new FormControl();`\n\n### Hint\n\nA 'hint' can be displayed below the input on the right-hand side. This should be used for helpful user information such as input\nrequirements.\n\n```html\n\n```\n\n### No validation or hint\n\nA flag to define whether this input field needs validation or hint. If it needs validation or hint, a padding bottom is added for the message, otherwise, no padding at the bottom.\n\n```html\n\n```\n\n### Prefix icon\n\nTo include an icon as a prefix to the input, pass a valid icon instance to `prefixIcon`:\n\n```typescript\nimport { faHome } from '@fortawesome/pro-solid-svg-icons/faHome';\n...\npublic home = faHome;\n```\n\n```html\n\n```\n\n> See all valid icon possibilities: \n\n### Disabled\n\nInputs can be disabled by setting the component flag OR by setting the associated `FormControl` to `disabled`.\n\nThe `isDisabled` flag works with both `ngModel` and `FormControl` inputs:\n\n```html\n\n```\n\nWhen using Reactive Forms, controls should be disabled via the control:\n\n```typescript\nmyControl: FormControl = new FormControl({value: null, disabled: true});\n```\n\n### Required\n\nWhen using a `FormControl`, set the required validator on the control:\n\n```typescript\nmyControl = new FormControl(null, Validators.required);\n```\n\nWhen using `ngModel`, validations are placed on the input as data-attributes (just like native HTML inputs):\n\n```html\n\n```\n\nIf only the required asterisk is needed rather than validation errors, the `isRequired` flag can be used:\n\n```html\n\n```\n\n#### Required asterisk `*`\n\nIf the input should be required, but the required asterisk `*` is not needed, disable it with the\n`hideRequiredMarker` input:\n\n```html\n\n```\n\n> NOTE: We should not hide this visual indicator without a very good reason!\n\n### Clearable\n\nIf the input should be easily reset, include the `isClearable` flag to enable a 'clear input'\nbutton: (button will appear as small `x` icon at the far right of the input)\n\n```html\n\n```\n\nWhen the input is cleared, the `cleared` event emitter will be fired with the value `true`.\n\n### Focused\n\nAuto-focus the input when the view loads:\n\n```html\n\n```\n\n> NOTE: If multiple inputs within the same view set `isFocused` to true, the _**last one rendered\n> will receive the final focus**_.\n\nThis can also be used to dynamically focus an existing input:\n\n```html\n