Angular Date Time Editor Directive

The Ignite UI for Angular Date Time Editor Directive allows the user to set and edit the date and time in a chosen input element. The user can edit the date or time portion, using an editable masked input. Additionally, one can specify a desired display and input format, as well as min and max values to utilize validation.

Angular Date Time Editor Directive Example

Getting Started with Angular Date Time Editor Directive

To get started with the Ignite UI for Angular Date Time Editor directive, first you need to install Ignite UI for Angular. In an existing Angular application, type the following command:

ng add igniteui-angular

For a complete introduction to the Ignite UI for Angular, read the getting started topic.

The next step is to import the IgxDateTimeEditorModule in your app.module.ts file.

// app.module.ts

...
import { IgxDateTimeEditorModule } from 'igniteui-angular';
// import { IgxDateTimeEditorModule } from '@infragistics/igniteui-angular'; for licensed package

@NgModule({
    ...
    imports: [..., IgxDateTimeEditorModule],
    ...
})
export class AppModule {}

Alternatively, as of 16.0.0 you can import the IgxDateTimeEditorDirective as a standalone dependency.

// home.component.ts

import { IgxDateTimeEditorDirective, IGX_INPUT_GROUP_DIRECTIVES } from 'igniteui-angular';
// import { IgxDateTimeEditorDirective, IGX_INPUT_GROUP_DIRECTIVES } from '@infragistics/igniteui-angular'; for licensed package

@Component({
    selector: 'app-home',
    template: `
    <igx-input-group>
        <input type="text" igxInput igxDateTimeEditor [value]="date" />
    </igx-input-group>
    `,
    styleUrls: ['home.component.scss'],
    standalone: true,
    imports: [IgxDateTimeEditorDirective, IGX_INPUT_GROUP_DIRECTIVES]
})
export class HomeComponent {
    public date = new Date();
}

Now that you have the Ignite UI for Angular Date Time Editor module or directive imported, you can start using the igxDateTimeEditor directive.

Using the Angular Date Time Editor Directive

To use an input as a date time editor, set an igxDateTimeEditor directive and a valid date object as value. In order to have complete editor look and feel, wrap the input in an igx-input-group. This will allow you to not only take advantage of the following directives igxInput, igxLabel, igx-prefix, igx-suffix, igx-hint, but will cover common scenarios when dealing with form inputs as well.

Binding

A basic configuration scenario setting a Date object as a value:

public date = new Date();

<igx-input-group>
    <input type="text" igxInput igxDateTimeEditor [value]="date" />
</igx-input-group>

To create a two-way data-binding, set an ngModel:

<igx-input-group>
    <input type="text" igxInput igxDateTimeEditor [(ngModel)]="date"/>
</igx-input-group>

Binding to ISO strings

The IgxDateTimeEditorDirective accepts an ISO 8601 strings.

The string can be a full ISO string, in the format YYYY-MM-DDTHH:mm:ss.sssZ or it could be separated into date-only and time-only portions.

Date-only

If a date-only string is bound to the directive, it needs to follow the format - YYYY-MM-DD. This applies only when binding a string value to the directive, the inputFormat is still used when typing values in the editor and it does not have to be in the same format. Additionally, when binding a date-only string, the directive will prevent time shifts by coercing the time to be T00:00:00.

Time-only

Time-only strings are normally not defined in the ECMA specification, however to allow the directive to be integrated in scenarios which require time-only solutions, it supports the 24 hour format - HH:mm:ss. The 12 hour format is not supported. Please also note that this applies for bound values only.

Full ISO string

If a full ISO string is bound, the directive will parse it only if all elements required by Date.parse are provided.

All falsy values, including InvalidDate will be parsed as null. Incomplete date-only, time-only, or full ISO strings will be parsed as InvalidDate.

Date Time Editor Directive has intuitive keyboard navigation that makes it easy to increment, decrement, or jump through different DateParts among others without having to touch the mouse.

Ctrl / Cmd + Arrow Left / Right - navigates between date sections. On Ctrl / Cmd + Right it goes to the end of the section. If already there it goes to the end of next section if any. It works in a similar fashion in the opposite direction.
Arrow Up / Down - increment/decrement date portions. See related spinLoop
Ctrl / Cmd + ; - set the current day and time in the editor.

Examples

Display and input format

The IgxDateTimeEditor supports different display and input formats.

It uses Angular's DatePipe, which allows it to support predefined format options, such as shortDate and longDate. It can also accept a constructed format string using characters supported by the DatePipe, e.g. EE/MM/yyyy. Notice that formats like shortDate, longDate, etc., can be used as displayFormat only. Also, if no displayFormat is provided, the editor will use the inputFormat as its displayFormat.

To set a specific input format, pass it as a string to the IgxDateTimeEditor directive. This will set both the expected user input format and the mask for the editor. Additionally, the inputFormat is locale based, so if none is provided, the editor will default to the one used by the browser.

<igx-input-group>
    <input type="text" igxInput [displayFormat]="'shortDate'" [igxDateTimeEditor]="'dd/MM/yyyy'" [(ngModel)]="date"/>
</igx-input-group>

The table bellow shows formats that are supported by the directive's inputFormat:

Format	Description
`d`	Date, will be coerced with a leading zero while editing.
`dd`	Date with an explicitly set leading zero.
`M`	Month, will be coerced with a leading zero while editing.
`MM`	Month with an explicitly set leading zero.
`yy`	Short year format.
`yyyy`	Full year format.
`h`	Hours in 12-hour format, will be coerced with a leading zero while editing.
`hh`	Hours in 12-hour format with an explicitly set leading zero.
`H`	Hours in 24-hour format, will be coerced with a leading zero while editing.
`HH`	Hours in 24-hour format, with an explicitly set leading zero.
`m`	Minutes, will be coerced with a leading zero while editing.
`mm`	Minutes with an explicitly set leading zero.
`tt`	AM/PM section for 12-hour format.

Note

The IgxDateTimeEditorDirective directive supports IME input. When typing in an Asian language input, the control will display input method compositions and candidate lists directly in the control’s editing area, and immediately re-flow surrounding text as the composition ends.

Min max value

You can specify minValue and maxValue properties to restrict input and control the validity of the ngModel.

public minDate = new Date(2020, 1, 15);
public maxDate = new Date(2020, 11, 1);

<igx-input-group>
    <input type="text" igxInput igxDateTimeEditor [minValue]="minDate" [maxValue]="maxDate" [(ngModel)]="date"/>
</igx-input-group>

The minValue and minValue inputs can also be of type string, see Binding to ISO strings.

Increment and decrement

igxDateTimeEditor directive exposes public increment and decrement methods. They increment or decrement a specific DatePart of the currently set date and time and can be used in a couple of ways.

In the first scenario, if no specific DatePart is passed to the method, a default DatePart will increment or decrement, based on the specified inputFormat and the internal directive implementation. In the second scenario, you can explicitly specify what DatePart to manipulate as it may suite different requirements. Also, both methods accept an optional delta parameter of type number which can be used to set the increment/decrement step.

You may compare both in the following sample:

Additionally, spinDelta is an input property of type DatePartDeltas and it can be used to apply a different delta to each date time segment. It will be applied when spinning with the keyboard, as well as when spinning with the increment and decrement methods, as long as they don't have the delta parameter provided since it will take precedence over spinDelta.

In Angular Forms

The Date Time Editor Directive supports all of the form directives from the core FormsModule NgModel and ReactiveFormsModule (FormControl, FormGroup, etc.). This also includes the Forms Validators functions. The following example illustrates the use of the required validator in a Template-driven Form.

Note

If needed, you can revert back to a valid state by handling the validationFailed event and changing the newValue property of the available arguments.

Template-driven form example:

<form>
    <igx-input-group>
        <input igxInput type="text" [(ngModel)]="date" name="form" required
            (valueChanged)="onValueChanged($event)" (validationFailed)="onValidationFailed($event)"
            [igxDateTimeEditor]="'dd/MM/yyyy'" [minValue]="minDate" [maxValue]="maxDate" [isSpinLoop]="false" />
    </igx-input-group>
</form>
<div class="divider--half"></div>

Text Selection

You can force the component to select all of the input text on focus using igxTextSelection. Find more info on igxTextSelection at Label & Input.

<igx-input-group>
    <input igxInput [igxDateTimeEditor]="'dd/MM/yyyy'" [igxTextSelection]="true"/>
</igx-input-group>

Note

In order for the component to work properly, it is crucial to set igxTextSelection after the igxDateTimeEditor directive. The reason for this is both directives operate on the input focus event so text selection should happen after the mask is set.

Styling

For details check out the Input Group styling guide.

Angular Date Time Editor Directive