igniteui-angular-sovn
Version:
Ignite UI for Angular is a dependency-free Angular toolkit for building modern web apps
146 lines (116 loc) • 11.9 kB
Markdown
# 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 |