# igx-date-picker Component

The **igx-date-picker** component allows you to choose date from calendar
which is presented into input field.
A walk through of how to get started can be found [here](https://www.infragistics.com/products/ignite-ui-angular/angular/components/date_picker.html)

## Dependencies

In order to be able to use **igx-date-picker** you should keep in mind that it is dependent on **BrowserAnimationsModule**,
which must be imported **only once** in your application's AppModule, for example:

```typescript
import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
@NgModule({
    imports: [
        ...
        BrowserAnimationsModule
        ...
    ]
})
export class AppModule {
}
```

# Usage

Import the `IgxDatePickerModule` in the module that you want to use it in:

```typescript
import { IgxDatePickerModule } from "igniteui-angular-sovn";

@NgModule({
    imports: [IgxDatePickerModule],
})
export class AppModule {}
```

Basic initialization

```html
<igx-date-picker></igx-date-picker>
```

This will produce an `igx-date-picker` without a default label. If you want to add a label you can import the `IgxLabelModule` and then in your `HTML` you can project it like so:

```html
<igx-date-picker>
    <label igxLabel>Date: </label>
</igx-date-picker>
```

Custom formats for the input field.

```html
<igx-date-picker [inputFormat]="dd/MM/yyyy" [displayFormat]="'longDate'" [value]="date"> </igx-date-picker>
```

If the `inputFormat` is not set, it will default to the format used by the browser. The `displayFormat` accepts all supported formats by Angular's `DatePipe`.

DatePicker with cancel and today buttons

```html
<igx-date-picker [cancelButtonLabel]="'Close'" [todayButtonLabel]="'Today'"> </igx-date-picker>
```

If the these two properties are not set, the `igx-date-picker` will have any buttons.

Additionally, custom buttons can be templated in the `igx-date-picker` using the `igxPickerActions` directive:

```html
<igx-date-picker #datePicker>
    <ng-template igxPickerActions>
        <div class="action-buttons">
            <button igxButton="flat" (click)="datePicker.selectToday()">Today</button>
        </div>
    </ng-template>
</igx-date-picker>
```

The date picker also supports binding through `ngModel` if two-way date-bind is needed. It is also a custom validator which triggers

```html
<igx-date-picker #model="ngModel" required [displayMonthsCount]="3" [(ngModel)]="date" [minValue]="minDate" [maxValue]="maxDate">
    <label igxLabel>Select a Date</label>
    <igx-hint *ngIf="model.errors?.value"> This field is required. </igx-hint>
    <igx-hint *ngIf="model.errors?.minValue || model.errors?.maxValue"> Value is not in range. </igx-hint>
</igx-date-picker>
```

# API

###### Inputs

| Name                 | Description                                                                                                                                        | Type                                    |
| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------- |
| `id`                 | `attr.id` of the picker.                                                                                                                           | string                                  |
| `mode`               | Sets whether `IgxDatePickerComponent` is in dialog or dropdown mode.                                                                               | InteractionMode                         |
| `value`              | The value of the editor.                                                                                                                           | Date                                    |
| `minValue`           | The minimum value required for the picker to remain valid.                                                                                         | Date \| string                          |
| `maxValue`           | The maximum value required for the editor to remain valid.                                                                                         | Date \| string                          |
| `displayFormat`      | The display value of the editor.                                                                                                                   | string                                  |
| `inputFormat`        | The format that the editor will use to display the date/time.                                                                                      | string                                  |
| `calendarFormat`     | The calendar's format options for the day view.                                                                                                    | PickersFormatOptions                    |
| `specialDates`       | Dates that will be marked as special in the calendar.                                                                                              | DateRangeDescriptor[]                   |
| `disabledDates`      | Dates that will be disabled in the calendar.                                                                                                       | DateRangeDescriptor[]                   |
| `formatViews`        | Determines if `day`, `month` and `year` will be rendered in the calendar. `locale` and `formatOptions` are taken into account as well, if present. | PickersFormatViews                      |
| `displayMonthsCount` | Sets the number of displayed month views. Default is `2`.                                                                                          | number                                  |
| `hideOutsideDays`    | Sets whether dates that are not part of the current month will be displayed. Default is `false`.                                                   | boolean                                 |
| `showWeekNumbers`    | Shows or hides week numbers.                                                                                                                       | number                                  |
| `tabindex`           | The editor's tabindex.                                                                                                                             | number                                  |
| `weekStart`          | Sets the start day of the week.                                                                                                                    | number                                  |
| `locale`             | Locale settings used in `displayFormat` and for localizing the calendar.                                                                           | string                                  |
| `overlaySettings`    | Changes the default overlay settings used by the `IgxDatePickerComponent`.                                                                         | OverlaySettings                         |
| `placeholder`        | Sets the placeholder text for empty input.                                                                                                         | string                                  |
| `disabled`           | Disables or enables the picker.                                                                                                                    | boolean                                 |
| `outlet`             | The container used for the pop up element.                                                                                                         | IgxOverlayOutletDirective \| ElementRef |
| `type`               | Determines how the picker will be styled.                                                                                                          | IgxInputGroupType                       |
| `spinLoop`           | Determines if the currently spun date segment should loop over.                                                                                    | boolean                                 |
| `spinDelta`          | Delta values used to increment or decrement each editor date part on spin actions. All values default to `1`.                                      | DatePartDeltas                          |
| `cancelButtonLabel`  | The label of the `cancel` button. No button is rendered if there is no label provided.                                                             | string                                  |
| `todayButtonLabel`   | The label of the `select today` button. No button is rendered if there is no label provided.                                                       | string                                  |
| `headerOrientation`  | Determines whether the calendar's header renders in `vertical` or `horizontal` state. Applies only in `dialog` mode.                               | 'horizontal' \| 'vertical'              |

### Outputs

| Name               | Description                                                                                        | Cancelable | Emitted with                         |
| ------------------ | -------------------------------------------------------------------------------------------------- | ---------- | ------------------------------------ |
| `opening`          | Fired when the calendar has started opening.                                                       | true       | IBaseCancelableBrowserEventArgs      |
| `opened`           | Fired after the calendar has opened.                                                               | false      | IBaseEventArgs                       |
| `closing`          | Fired when the calendar has started closing                                                        | true       | IBaseCancelableBrowserEventArgs      |
| `closed`           | Fired after the calendar has closed.                                                               | false      | IBaseEventArgs                       |
| `valueChange`      | Emitted when the picker's value changes. Allows two-way binding of `value`.                        | false      | Date                                 |
| `validationFailed` | Emitted when a user enters an invalid date string or when the value is not within a min/max range. | false      | IDatePickerValidationFailedEventArgs |

### Methods

| Name        | Description                                                                                                                    | Return type |
| :---------- | :----------------------------------------------------------------------------------------------------------------------------- | :---------- |
| `select`    | Accepts a Date object and selects the corresponding date from the calendar.                                                    | void        |
| `clear`     | Clears the editor's date.                                                                                                      | void        |
| `open`      | Opens the calendar.                                                                                                            | void        |
| `close`     | Closes the calendar.                                                                                                           | void        |
| `toggle`    | Toggles the calendar between opened and closed states.                                                                         | void        |
| `increment` | Accepts a `DatePart` and increments it by one. If no value is provided, it defaults to the part at the position of the cursor. | void        |
| `decrement` | Accepts a `DatePart` and decrements it by one. If no value is provided, it defaults to the part at the position of the cursor. | void        |