# Time range

- Entry point: `@koobiq/components/time-range`
- NgModule: `KbqTimeRangeModule`
- API: https://koobiq.io/api/time-range.md
- Page: https://koobiq.io/en/components/time-range/overview

## Overview

Time range selection menu. The user can choose one of the preset values or specify the time range manually.

[**Example: Time range overview** (`time-range-overview`)](https://koobiq.io/examples/time-range-overview.md)

### Trigger element

The component allows you to customize the trigger element. For example, it can be a button, a field, or a pseudo-link.

[**Example: Time range custom trigger** (`time-range-custom-trigger`)](https://koobiq.io/examples/time-range-custom-trigger.md)

#### Trigger inside a field

`kbq-time-range-title-as-control` puts the trigger inside a `kbq-form-field`, so the range gets a label,
a hint and the error styling of a regular field. `kbqTimeRangeTitlePlaceholder` styles the text shown
while there is no value — set `[nonNullable]="false"` for that state to be reachable at all.

[**Example: Time range as form field** (`time-range-as-form-field`)](https://koobiq.io/examples/time-range-as-form-field.md)

### Custom presets

When there are no preset values, only the start and end of the period remain in the window.

[**Example: Time range empty type list** (`time-range-empty-type-list`)](https://koobiq.io/examples/time-range-empty-type-list.md)

### Selection restriction

You can configure the minimum and maximum date through `minDate` and `maxDate`.

Both bounds take the time into account, not just the date. If you set `maxDate` to 31 December with no time, midnight is the only choice — to make the whole day available, set the time to 23:59.

The bounds are shown in the picker: next to the "Period" option, or under the "to" field when there are no presets.

[**Example: Time range min max** (`time-range-min-max`)](https://koobiq.io/examples/time-range-min-max.md)

### Custom time ranges

The component allows you to set custom time range options.

[**Example: Time range custom range types** (`time-range-custom-range-types`)](https://koobiq.io/examples/time-range-custom-range-types.md)

### Providing presets through DI

The list of options and the options themselves are data, so both can be replaced without touching the
template:

- `KBQ_DEFAULT_TIME_RANGE_TYPES` replaces the default list of options (`defaultTimeRangeTypes`) for
  every `kbq-time-range` below the provider. `[availableTimeRangeTypes]` overrides it per component.
- `KBQ_CUSTOM_TIME_RANGE_TYPES` registers options the built-in list does not have. Each entry carries
  its identifier, its duration (`units`) and the unit its label is formatted in (`translationType`),
  or a fixed `range` instead of a duration.

```ts
providers: [
    {
        provide: KBQ_CUSTOM_TIME_RANGE_TYPES,
        useValue: [{ type: 'last3Weeks', units: { weeks: -3 }, translationType: 'weeks' }]
    },
    { provide: KBQ_DEFAULT_TIME_RANGE_TYPES, useValue: ['lastHour', 'last3Weeks', 'range'] }
];
```

### Empty value and value correction

`nonNullable` (default `true`) decides what a `null` written through the form control means. While it
is `true`, `null` is replaced with the first available option and the trigger always shows a range;
set it to `false` to let the component hold no value and render the placeholder.

`valueCorrected` fires whenever the component had to change the value it was given — a type that is
not in `availableTimeRangeTypes`, a `range` missing one of its ends, or a `null` under `nonNullable`.
It emits the corrected value so that a host can write it back, and it stays silent when the value is
already the one the component would produce.

The inputs, the output and the defaults they carry are listed on the API tab.

## Examples

This example shows how to customize the display of a selection item in a dialog

[**Example: Time range custom option** (`time-range-custom-option`)](https://koobiq.io/examples/time-range-custom-option.md)
