# TimePicker
## Description
A BitTimePicker offers a drop-down control that's optimized for picking a single time value using hour and minute spin buttons. The time it holds is a TimeSpan of the day, written and read in the format of the current culture, and every part of it can be set with the pointer or the keyboard alike. You can customize the picker to fit your scenario, for example by changing the time format, showing the seconds, stepping in intervals, limiting the selectable range or the exact values that can be picked, rendering it inline instead of in a callout, or letting users type the time directly.
## Parameters
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| AllowTextInput | `bool` | false | Whether the TimePicker allows input a time string directly or not. |
| AllowedHours | `Func<int, bool>?` | null | The hours that can be selected, on top of what MinTime and MaxTime already allow. The predicate receives an hour of the day (0-23); the spin buttons skip over the hours it rejects, a typed one snaps to the nearest it accepts, and a time entered as text that lands on one fails validation. |
| AllowedMinutes | `Func<int, bool>?` | null | The minutes that can be selected, on top of what MinTime and MaxTime already allow. The predicate receives a minute of the hour (0-59); the spin buttons skip over the minutes it rejects, a typed one snaps to the nearest it accepts, and a time entered as text that lands on one fails validation. |
| AllowedSeconds | `Func<int, bool>?` | null | The seconds that can be selected, on top of what MinTime and MaxTime already allow. The predicate receives a second of the minute (0-59); the spin buttons skip over the seconds it rejects, a typed one snaps to the nearest it accepts, and a time entered as text that lands on one fails validation. |
| AutoFocus | `bool` | false | Whether the input of the TimePicker gets the focus as soon as it renders for the first time. |
| CalloutAriaLabel | `string` | Clock | Aria label for time picker popup for screen reader users. |
| CalloutFooterTemplate | `RenderFragment?` | null | Custom template to render at the bottom of the TimePicker's callout, below the time inputs and the action buttons. |
| CalloutHeaderTemplate | `RenderFragment?` | null | Custom template to render at the top of the TimePicker's callout, above the time inputs. |
| CalloutHtmlAttributes | `Dictionary<string, object>` | new Dictionary<String, Object>() | Capture and render additional attributes in addition to the main callout's parameters. |
| Classes | `BitTimePickerClassStyles` | null | Custom CSS classes for different parts of the TimePicker. |
| ClearButtonText | `string` | Clear | The text of the clear button, shown when ShowClearButton is set. |
| CloseButtonIcon | `BitIconInfo?` | null | Gets or sets the close button icon using custom CSS classes for external icon libraries. Takes precedence over CloseButtonIconName when both are set. |
| CloseButtonIconName | `string?` | Cancel | Gets or sets the name of the close button icon from the built-in Fluent UI icons. |
| CloseButtonTitle | `string` | Close time picker | The title of the close button (tooltip). |
| Color | `BitColor?` | null | The general color of the TimePicker, which applies to the selected AM/PM button, the now and clear action buttons, and the focus indicator of the input. |
| ContinuousSpinDelay | `int` | 400 | The delay in milliseconds before the time part starts changing continuously while an increase/decrease button is held down. |
| ContinuousSpinInterval | `int` | 75 | The interval in milliseconds between two consecutive changes while an increase/decrease button is held down. |
| Culture | `CultureInfo` | CultureInfo.CurrentUICulture | CultureInfo for the TimePicker. It provides the AM/PM designators and the pattern the value is written in, and a culture that reads right to left lays the picker out that way without an explicit Dir. |
| DecreaseHourIcon | `BitIconInfo?` | null | Gets or sets the decrease hour button icon using custom CSS classes for external icon libraries. Takes precedence over DecreaseHourIconName when both are set. |
| DecreaseHourIconName | `string?` | ChevronDownSmall | Gets or sets the name of the decrease hour button icon from the built-in Fluent UI icons. |
| DecreaseHourTitle | `string` | Decrease hour | The title of the decrease hour button (tooltip and aria-label). |
| DecreaseMinuteIcon | `BitIconInfo?` | null | Gets or sets the decrease minute button icon using custom CSS classes for external icon libraries. Takes precedence over DecreaseMinuteIconName when both are set. |
| DecreaseMinuteIconName | `string?` | ChevronDownSmall | Gets or sets the name of the decrease minute button icon from the built-in Fluent UI icons. |
| DecreaseMinuteTitle | `string` | Decrease minute | The title of the decrease minute button (tooltip and aria-label). |
| DecreaseSecondIcon | `BitIconInfo?` | null | Gets or sets the decrease second button icon using custom CSS classes for external icon libraries. Takes precedence over DecreaseSecondIconName when both are set. |
| DecreaseSecondIconName | `string?` | ChevronDownSmall | Gets or sets the name of the decrease second button icon from the built-in Fluent UI icons. |
| DecreaseSecondTitle | `string` | Decrease second | The title of the decrease second button (tooltip and aria-label). |
| DisallowedTimeErrorMessage | `string?` | null | The custom validation error message for a time entered as text that AllowedHours, AllowedMinutes or AllowedSeconds rejects. |
| DisableFuture | `bool` | false | Disables every time of day after the current time, exactly as a MaxTime of now would. When both are set, the earlier of the two bounds wins. |
| DisablePast | `bool` | false | Disables every time of day before the current time, exactly as a MinTime of now would. When both are set, the later of the two bounds wins. |
| DropDirection | `BitDropDirection` | BitDropDirection.TopAndBottom | Determines the allowed drop directions of the callout. |
| HasBorder | `bool` | true | Determines if the TimePicker has a border. |
| HourInputAriaLabel | `string` | Hour | The aria-label of the hour input. |
| HourStep | `int` | 1 | The step, in hours, the spin buttons move the hour by. A step greater than 1 lays a grid over the day, starting at the hour of MinTime, and at midnight where there is none, that every hour the buttons produce sits on. A time entered as text is not held to it. |
| Icon | `BitIconInfo?` | null | Gets or sets the icon to display using custom CSS classes for external icon libraries. Takes precedence over IconName when both are set. |
| IconName | `string?` | Clock | Gets or sets the name of the icon to display from the built-in Fluent UI icons. |
| IconLocation | `BitIconLocation` | BitIconLocation.Right | TimePicker icon location. |
| IconTemplate | `RenderFragment?` | null | Custom TimePicker icon template. |
| IncreaseHourIcon | `BitIconInfo?` | null | Gets or sets the increase hour button icon using custom CSS classes for external icon libraries. Takes precedence over IncreaseHourIconName when both are set. |
| IncreaseHourIconName | `string?` | ChevronDownSmall | Gets or sets the name of the increase hour button icon from the built-in Fluent UI icons. |
| IncreaseHourTitle | `string` | Increase hour | The title of the increase hour button (tooltip and aria-label). |
| IncreaseMinuteIcon | `BitIconInfo?` | null | Gets or sets the increase minute button icon using custom CSS classes for external icon libraries. Takes precedence over IncreaseMinuteIconName when both are set. |
| IncreaseMinuteIconName | `string?` | ChevronDownSmall | Gets or sets the name of the increase minute button icon from the built-in Fluent UI icons. |
| IncreaseMinuteTitle | `string` | Increase minute | The title of the increase minute button (tooltip and aria-label). |
| IncreaseSecondIcon | `BitIconInfo?` | null | Gets or sets the increase second button icon using custom CSS classes for external icon libraries. Takes precedence over IncreaseSecondIconName when both are set. |
| IncreaseSecondIconName | `string?` | ChevronDownSmall | Gets or sets the name of the increase second button icon from the built-in Fluent UI icons. |
| IncreaseSecondTitle | `string` | Increase second | The title of the increase second button (tooltip and aria-label). |
| InvalidErrorMessage | `string?` | null | The custom validation error message for the invalid value. |
| IsOpen | `bool` | false | Whether or not this TimePicker is open. Supports two-way binding to open and close the callout from code. |
| Label | `string?` | null | Label for the TimePicker. |
| LabelTemplate | `RenderFragment?` | null | Used to customize the label for the TimePicker. |
| MaxTime | `TimeSpan?` | null | The maximum time of day that can be selected. Stepping clamps the value into the bound, a typed time beyond it fails validation, and a bound outside of a day is clamped into one before it is applied. |
| MinTime | `TimeSpan?` | null | The minimum time of day that can be selected. Stepping clamps the value into the bound, a typed time beyond it fails validation, and a bound outside of a day is clamped into one before it is applied. |
| MinuteInputAriaLabel | `string` | Minute | The aria-label of the minute input. |
| MinuteStep | `int` | 1 | The step, in minutes, the spin buttons move the minute by. A step greater than 1 lays a grid over the hour, starting at the minute of MinTime, and at the top of the hour where there is none, that every minute the buttons produce sits on - which is what turns it into a five-minute or quarter-hour picker. A time entered as text is not held to it. |
| NowButtonText | `string` | Now | The text of the now button, shown when ShowNowButton is set. |
| OnClear | `EventCallback` | | Callback for when the value is cleared using the clear button. |
| OnClick | `EventCallback` | | Callback for when clicking on TimePicker input. |
| OnClose | `EventCallback` | | Callback for when the callout of the TimePicker is closed. |
| OnFocus | `EventCallback` | | Callback for when focus moves into the TimePicker input. |
| OnFocusIn | `EventCallback` | | Callback for when focus moves into the TimePicker input. |
| OnFocusOut | `EventCallback` | | Callback for when focus moves out of the TimePicker input. |
| OnOpen | `EventCallback` | | Callback for when the callout of the TimePicker is opened. |
| OnSelectTime | `EventCallback<TimeSpan?>` | | Callback for when the selected time changes. |
| OutOfRangeErrorMessage | `string?` | null | The custom validation error message for a time entered as text that falls outside of MinTime and MaxTime. |
| Placeholder | `string?` | null | Placeholder text for the TimePicker. |
| Responsive | `bool` | false | Enables the responsive mode in small screens. |
| SecondInputAriaLabel | `string` | Second | The aria-label of the second input. |
| SecondStep | `int` | 1 | The step, in seconds, the spin buttons move the second by. A step greater than 1 lays a grid over the minute, starting at the second of MinTime, and at the top of the minute where there is none, that every second the buttons produce sits on. A time entered as text is not held to it. |
| ShowClearButton | `bool` | false | Whether the BitTimePicker's clear button should be shown or not. |
| ShowCloseButton | `bool` | false | Whether the BitTimePicker's close button should be shown or not. |
| ShowNowButton | `bool` | false | Whether the BitTimePicker's now button should be shown or not. The button selects the current time of day, snapped to the steps and to the allowed values. |
| ShowSeconds | `bool` | false | Whether the BitTimePicker shows the seconds input or not. |
| Size | `BitSize?` | null | The size of the TimePicker, which scales the input, the label, the time inputs and the spin buttons. |
| Styles | `BitTimePickerClassStyles` | null | Custom CSS styles for different parts of the TimePicker. |
| Standalone | `bool` | false | Whether the BitTimePicker is rendered standalone or with the input component and callout. |
| StartingValue | `TimeSpan?` | null | The time an empty TimePicker starts from, instead of midnight. It is not a value: the picker stays empty until something is picked, but the first change made to it lands around the given time. |
| TimeFormat | `BitTimeFormat` | BitTimeFormat.TwentyFourHours | The time format of the time-picker, 24H or 12H. |
| Underlined | `bool` | false | Whether or not the Text field of the TimePicker is underlined. |
| ValueFormat | `string?` | null | The format of the time in the TimePicker like "HH:mm". Left unset it follows the time pattern of the culture, rewritten into the TimeFormat, extended with the seconds where ShowSeconds is set and padded with the leading zeros. |
| DefaultValue | `TValue?` | null | The default value of the input to be used in uncontrolled mode (i.e. when the Value is not bound), typically used alongside the OnChange callback. |
| DisplayName | `string?` | null | Gets or sets the display name for this field. |
| InputHtmlAttributes | `IReadOnlyDictionary<string, object>?` | null | Gets or sets a collection of additional attributes that will be applied to the created element. |
| Name | `string?` | null | Gets or sets the name of the element. Allows access by name from the associated form. |
| NoValidate | `bool` | false | Disables the validation of the input. |
| OnChange | `EventCallback<TValue?>` | | Callback for when the input value changes. |
| ReadOnly | `bool` | false | Makes the input read-only. |
| Required | `bool` | false | Makes the input required. |
| Value | `TValue?` | null | Gets or sets the value of the input. This should be used with two-way binding. |
| AriaLabel | `string?` | null | Gets or sets the accessible label for the component, used by assistive technologies. |
| Class | `string?` | null | Gets or sets the CSS class name(s) to apply to the rendered element. |
| Dir | `BitDir?` | null | Gets or sets the text directionality for the component's content. |
| ForceAnimation | `bool` | false | Gets or sets a value indicating whether the component's animations play at their full duration even when reduced motion is requested. |
| HtmlAttributes | `Dictionary<string, object>` | new Dictionary<string, object>() | Captures additional HTML attributes to be applied to the rendered element, in addition to the component's parameters. |
| Id | `string?` | null | Gets or sets the unique identifier for the component's root element. |
| IsEnabled | `bool` | true | Gets or sets a value indicating whether the component is enabled and can respond to user interaction. |
| Style | `string?` | null | Gets or sets the CSS style string to apply to the rendered element. |
| TabIndex | `string?` | null | Gets or sets the tab order index for the component when navigating with the keyboard. |
| Visibility | `BitVisibility` | BitVisibility.Visible | Gets or sets the visibility state (visible, hidden, or collapsed) of the component. |
## Public Members
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| InputId | `string?` | | The id of the input element of the TimePicker. |
| OpenCallout | `Task OpenCallout()` | | Opens the callout of the TimePicker, doing nothing when it is already open or when the picker is standalone and has no callout to open. |
| DismissCallout | `Task DismissCallout()` | | Closes the callout of the TimePicker, leaving the focus wherever it is. |
| InputElement | `ElementReference` | | The ElementReference of the input element. |
| FocusAsync() | `() => ValueTask` | | Gives focus to the input element. |
| FocusAsync(bool preventScroll) | `(bool preventScroll) => ValueTask` | | Gives focus to the input element. |
| UniqueId | `Guid` | Guid.NewGuid() | Gets the readonly unique identifier for the component's root element, assigned when the component instance is constructed. |
| RootElement | `ElementReference` | | Gets the reference to the root HTML element associated with this component. |
## Enums
### BitVisibility Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Visible | 0 | Show content of the component. |
| Hidden | 1 | Hide content of the component,though the space it takes on the page remains. |
| Collapsed | 2 | Hide content of the component,though the space it takes on the page gone. |
### BitIconLocation Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Left | 0 | Show the icon at the left side. |
| Right | 1 | Show the icon at the right side. |
### BitTimeFormat Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| TwentyFourHours | 0 | Show time pickers in 24 hours format. |
| TwelveHours | 1 | Show time pickers in 12 hours format. |
### BitColor Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Primary | 0 | Primary general color. |
| Secondary | 1 | Secondary general color. |
| Tertiary | 2 | Tertiary general color. |
| Info | 3 | Info general color. |
| Success | 4 | Success general color. |
| Warning | 5 | Warning general color. |
| SevereWarning | 6 | SevereWarning general color. |
| Error | 7 | Error general color. |
| PrimaryBackground | 8 | Primary background color. |
| SecondaryBackground | 9 | Secondary background color. |
| TertiaryBackground | 10 | Tertiary background color. |
| PrimaryForeground | 11 | Primary foreground color. |
| SecondaryForeground | 12 | Secondary foreground color. |
| TertiaryForeground | 13 | Tertiary foreground color. |
| PrimaryBorder | 14 | Primary border color. |
| SecondaryBorder | 15 | Secondary border color. |
| TertiaryBorder | 16 | Tertiary border color. |
### BitSize Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Small | 0 | The small size TimePicker. |
| Medium | 1 | The medium size TimePicker. |
| Large | 2 | The large size TimePicker. |
### BitDropDirection Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| All | 0 | The direction determined automatically based on the available spaces in all directions. |
| TopAndBottom | 1 | Show the callout at the top or bottom side. |
### BitVisibility Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Visible | 0 | The content of the component is visible. |
| Hidden | 1 | The content of the component is hidden, but the space it takes on the page remains (visibility:hidden). |
| Collapsed | 2 | The component is hidden (display:none). |
### BitDir Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Ltr | 0 | Ltr (left to right) is to be used for languages that are written from the left to the right (like English). |
| Rtl | 1 | Rtl (right to left) is to be used for languages that are written from the right to the left (like Arabic). |
| Auto | 2 | Auto lets the user agent decide. It uses a basic algorithm as it parses the characters inside the element until it finds a character with a strong directionality, then applies that directionality to the whole element. |
## Sub Classes
### BitTimePickerClassStyles Properties
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| Root | `string?` | null | Custom CSS classes/styles for the root element of the BitTimePicker. |
| Focused | `string?` | null | Custom CSS classes/styles for the focused state of the BitTimePicker. |
| Label | `string?` | null | Custom CSS classes/styles for the Label of the BitTimePicker. |
| InputWrapper | `string?` | null | Custom CSS classes/styles for the input wrapper of the BitTimePicker. |
| InputContainer | `string?` | null | Custom CSS classes/styles for the input container of the BitTimePicker. |
| Input | `string?` | null | Custom CSS classes/styles for the input of the BitTimePicker. |
| Icon | `string?` | null | Custom CSS classes/styles for the icon of the BitTimePicker. |
| Overlay | `string?` | null | Custom CSS classes/styles for the overlay of the BitTimePicker. |
| Callout | `string?` | null | Custom CSS classes/styles for the callout of the BitTimePicker. |
| CalloutContainer | `string?` | null | Custom CSS classes/styles for the callout container of the BitTimePicker. |
| CalloutHeader | `string?` | null | Custom CSS classes/styles for the callout header of the BitTimePicker. |
| CalloutFooter | `string?` | null | Custom CSS classes/styles for the callout footer of the BitTimePicker. |
| TimeInputContainer | `string?` | null | Custom CSS classes/styles for the time input container of the BitTimePicker. |
| HourInputContainer | `string?` | null | Custom CSS classes/styles for the hour input container of the BitTimePicker. |
| IncreaseHourButton | `string?` | null | Custom CSS classes/styles for the increase hour button of the BitTimePicker. |
| IncreaseHourIcon | `string?` | null | Custom CSS classes/styles for the increase hour icon of the BitTimePicker. |
| HourInput | `string?` | null | Custom CSS classes/styles for the hour input of the BitTimePicker. |
| DecreaseHourButton | `string?` | null | Custom CSS classes/styles for the decrease hour button of the BitTimePicker. |
| DecreaseHourIcon | `string?` | null | Custom CSS classes/styles for the decrease hour icon of the BitTimePicker. |
| HourMinuteSeparator | `string?` | null | Custom CSS classes/styles for the hour minute separator of the BitTimePicker. |
| MinuteInputContainer | `string?` | null | Custom CSS classes/styles for the minute input container of the BitTimePicker. |
| IncreaseMinuteButton | `string?` | null | Custom CSS classes/styles for the increase minute button of the BitTimePicker. |
| IncreaseMinuteIcon | `string?` | null | Custom CSS classes/styles for the increase minute icon of the BitTimePicker. |
| MinuteInput | `string?` | null | Custom CSS classes/styles for the minute input of the BitTimePicker. |
| DecreaseMinuteButton | `string?` | null | Custom CSS classes/styles for the decrease minute button of the BitTimePicker. |
| DecreaseMinuteIcon | `string?` | null | Custom CSS classes/styles for the decrease minute icon of the BitTimePicker. |
| MinuteSecondSeparator | `string?` | null | Custom CSS classes/styles for the minute second separator of the BitTimePicker. |
| SecondInputContainer | `string?` | null | Custom CSS classes/styles for the second input container of the BitTimePicker. |
| IncreaseSecondButton | `string?` | null | Custom CSS classes/styles for the increase second button of the BitTimePicker. |
| IncreaseSecondIcon | `string?` | null | Custom CSS classes/styles for the increase second icon of the BitTimePicker. |
| SecondInput | `string?` | null | Custom CSS classes/styles for the second input of the BitTimePicker. |
| DecreaseSecondButton | `string?` | null | Custom CSS classes/styles for the decrease second button of the BitTimePicker. |
| DecreaseSecondIcon | `string?` | null | Custom CSS classes/styles for the decrease second icon of the BitTimePicker. |
| AmPmContainer | `string?` | null | Custom CSS classes/styles for the AM/PM container of the BitTimePicker. |
| AmButton | `string?` | null | Custom CSS classes/styles for the AM button of the BitTimePicker. |
| PmButton | `string?` | null | Custom CSS classes/styles for the PM button of the BitTimePicker. |
| Actions | `string?` | null | Custom CSS classes/styles for the actions container of the BitTimePicker. |
| NowButton | `string?` | null | Custom CSS classes/styles for the now button of the BitTimePicker. |
| ClearButton | `string?` | null | Custom CSS classes/styles for the clear button of the BitTimePicker. |
| CloseButton | `string?` | null | Custom CSS classes/styles for the close button of the BitTimePicker. |
| CloseButtonIcon | `string?` | null | Custom CSS classes/styles for the close button icon of the BitTimePicker. |
### BitIconInfo Properties
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| Name | `string?` | null | Gets or sets the name of the icon. |
| BaseClass | `string?` | null | Gets or sets the base CSS class for the icon. For built-in Fluent UI icons, this defaults to "bit-icon". For external icon libraries like FontAwesome, you might set this to "fa" or leave empty. |
| Prefix | `string?` | null | Gets or sets the CSS class prefix used before the icon name. For built-in Fluent UI icons, this defaults to "bit-icon--". For external icon libraries, you might set this to "fa-" or leave empty. |
## Examples
\n**Basic**:
```razor
Submit
```
```csharp
public class FormValidationTimePickerModel
{
[Required]
public TimeSpan? Time { get; set; }
}
private string successMessage = string.Empty;
private FormValidationTimePickerModel formValidationTimePickerModel = new();
private async Task HandleValidSubmit()
{
successMessage = "Form Submitted Successfully!";
await Task.Delay(3000);
successMessage = string.Empty;
StateHasChanged();
}
private void HandleInvalidSubmit()
{
successMessage = string.Empty;
}
```
\n**Responsive**:
```razor
eventLogs = [];
private void LogOpen() => Log("OnOpen");
private void LogClose() => Log("OnClose");
private void LogClick() => Log("OnClick");
private void LogClear() => Log("OnClear");
private void LogFocusIn() => Log("OnFocusIn");
private void LogFocusOut() => Log("OnFocusOut");
private void LogSelectTime(TimeSpan? time) => Log($"OnSelectTime: {time}");
private void LogChange(TimeSpan? time) => Log($"OnChange: {time}");
private void Log(string message)
{
eventLogs.Insert(0, message);
if (eventLogs.Count > 8)
{
eventLogs.RemoveRange(8, eventLogs.Count - 8);
}
}
```
\n**Programmatic control**:
```razor
OpenCallout()
DismissCallout()
```
```csharp
private bool isCalloutOpen;
private BitTimePicker? programmaticPicker;
```
\n**Templates**:
```razor
Custom label
```
```csharp
private TimeSpan? templateTime;
private BitTimePicker timePicker;
private async Task OpenCallout()
{
await timePicker.OpenCallout();
}
```
\n**Color**:
```razor
Selected time: @selectedTime.ToString()
Selected time: @actionsTime.ToString()
@foreach (var log in eventLogs)
{
```
```csharp
private readonly List@log
}
IsOpen: @isCalloutOpen
Pick a meeting time