CircularTimePicker

The picker is a read-only text field that opens a clock callout when it is clicked. Label names it, Placeholder fills the empty field, Required marks it with an asterisk and hands the requirement to the browser, IsEnabled turns it off, and IconName replaces the clock glyph that trails the field.

Standalone drops the field and the callout and renders the clock inline, as a permanent part of the page. The value still travels through a hidden input, so a standalone picker takes part in a form exactly like a callout one does - but that input is kept out of the tab order, so the dial is the one thing the keyboard lands on, and the one FocusAsync puts the focus on.

TimeFormat chooses the face. TwentyFourHours (the default) draws a double ring - 13 to 00 on the outside, 01 to 12 on the inside - and the pointer picks the ring it is closest to. TwelveHours draws a single 1 to 12 ring and adds the AM/PM pair to the toolbar, whose labels come from the culture of the picker. AmPmInClock moves that pair under the clock as a segmented control instead, which is what keeps the toolbar legible when the seconds are shown too. On an empty 12-hour picker the dial opens on the half that has something to offer, so a range that starts in the afternoon does not greet you with twelve dimmed numbers.

ShowSeconds adds a third part: a second ring the dial moves on to after the minute, a third read-out in the toolbar, and the seconds kept in the value instead of zeroed. SecondStep and AllowedSeconds narrow it exactly as their minute counterparts do, and the default ValueFormat grows a seconds part with it. A picker left without the seconds still carries the ones a bound value came with - it simply never offers a way to change them.

Selected time: 14:05:30

EditMode decides which parts of the time the dial offers. Normal edits all of them and settles onto the next one as soon as the current one is picked, while OnlyHours, OnlyMinutes and OnlySeconds pin the dial to a single part and leave the rest as it is. StartView chooses which part an opening picker lands on in Normal mode, View reports the one it is on, SwitchView moves it from code, and OnViewChange reports every switch - including the automatic one after a pick.

Last view change: -

MinuteStep and HourStep set the granularity the dial and the arrow keys move in. A step lays a grid over its range that the pick snaps to, which is what turns the face into a five-minute or quarter-hour picker, and dims the numbers in between so a value the picker does not accept is never offered. A press on a dimmed number changes nothing and leaves the dial where it is. The grid starts at the matching part of MinTime, and at the top of the range where there is none, so a picker whose range begins at 09:07 can still be set to 09:07.

MinTime and MaxTime bound what can be picked: the hours outside the range are dimmed, and inside the boundary hours only the minutes still within it stay selectable. AllowedHours, AllowedMinutes and AllowedSeconds add an arbitrary rule on top of that. The pointer refuses a dimmed number, the arrow keys step over it, and a time typed outside the range fails validation with its own OutOfRangeErrorMessage rather than the message an unreadable one gets. DisablePast and DisableFuture bound the range by the current time exactly as a MinTime or a MaxTime of now would; where both apply, the narrower of the two wins.

ShowNowButton jumps to the current time - snapped to the steps and clamped into the range, so it can never land on a time the dial itself refuses - and ShowClearButton empties the picker. ShowCloseButton adds a dismiss button in the corner of the callout, and AutoClose closes it the moment the selection is complete, without waiting for either. Their captions are set with NowButtonText, ClearButtonText and CloseButtonTitle.

@bind-IsOpen puts the callout under the control of the page, so it can be opened and closed from anywhere - the OpenCallout and DismissCallout methods do the same from code. DropDirection chooses the sides the callout may open towards: TopAndBottom (the default) keeps it above or below the field, while All lets it take whichever side has the room. OnOpen and OnClose report every change either way, and closing the picker hands the focus back to the field so the keyboard carries on where it left off. Tabbing out of the callout closes it too, and leaves the focus where it was going: the callout is moved to the end of the document while it is open, so a picker left behind would be one nothing on the page could reach any more.

AllowTextInput makes the field editable, so a time can be typed instead of dialled. The text is parsed with the exact ValueFormat of the picker, so what is typed has to match what the picker itself writes - which is why the format is worth putting in the placeholder.

ValueFormat is the .NET format string the field is rendered with, and - when the text input is allowed - parsed back with. Left unset, the picker writes the time the way its culture writes one: the pattern of the culture, rewritten into the clock format the dial is in (TimeFormat), extended with the seconds where ShowSeconds is set and written with the leading zeros - though a time typed without them is still read.

@bind-Value keeps a TimeSpan? in step with the dial in both directions. Where the value does not need to be held anywhere, DefaultValue seeds the picker once and OnChange reports every change from then on, so the picker keeps its own state (uncontrolled mode).

Selected time: 05:12:00

Changed time:

Culture is what the value is formatted and parsed with, and what the AM/PM designators of the 12-hour toolbar are taken from; left unset it follows CultureInfo.CurrentUICulture. Our CultureInfoHelper class shows how to build a custom one. The face itself is a deliberate choice rather than a consequence of the culture - TimeFormat stays where it is put - but the short time pattern of a culture says which of the two its readers expect, so a picker that should follow them can be wired to it in a line.

ReadOnly shows the value and lets the callout open, but nothing on the dial can be moved: the pointer, the arrow keys, the AM/PM pair and the action buttons all stop short of a change. Unlike a disabled picker it stays in the tab order and keeps being announced, so the value can still be read out.

Underlined trades the box of the field for a single rule under it, HasBorder is on by default and set to false takes the box away altogether - for a picker that sits inside a container of its own - and IconLocation moves the clock glyph to the leading edge.

LabelTemplate and IconTemplate replace the label and the trailing glyph with arbitrary markup. The first picker below drives its callout from a button inside its own label, through the public OpenCallout and DismissCallout methods of the component. CalloutHeaderTemplate and CalloutFooterTemplate add arbitrary markup above and below the dial inside the callout itself.

Responsive turns the callout into a sheet anchored to the top of the screen once the viewport is narrow enough, and lets it be swiped away upwards. Resize the window below the small breakpoint to see it.

The dial is a listbox whose options are the numbers of the current view, so a screen reader reads out what the pointer rests on, and the whole time can be set without ever touching the clock:

CalloutAriaLabel names the dialog, HourButtonTitle, MinuteButtonTitle and SecondButtonTitle name the toolbar buttons and the dial in each view, AutoFocus puts the focus on the field as the page renders, and TabIndex reaches the dial as well as the field. Values the constraints rule out are marked aria-disabled rather than merely dimmed, and a live region announces every move of the dial - the part it switches to, and the value it lands on where no number of the face stands for it, so a step of a single minute is never made in silence.

Inside an EditForm the picker is an ordinary form input: it registers with the EditContext, turns red and gets aria-invalid when its field has messages, and reports a value that cannot be parsed - or that falls outside MinTime / MaxTime - through InvalidErrorMessage.

OnSelectTime fires for every change the dial makes, OnChange for every change of the value itself, OnOpen and OnClose follow the callout, OnViewChange follows the dial between the parts of the time, and OnClick, OnFocusIn and OnFocusOut follow the field.

Landscape puts the toolbar down the leading edge of the picker instead of above the clock, stacking the parts of the time in a column - which is roughly half the height for a picker that has width to spare. It takes effect from the small breakpoint up: below it there is no width to give the toolbar, so the picker keeps its portrait layout. The Body slot of Styles and Classes reaches the column the toolbar is set beside - the clock, the AM/PM pair when AmPmInClock puts it there, and the row of actions.

Color picks the theme color of the accent the dial is painted with - the toolbar, the hand, the pin and the selected number - with Primary as the default. The semantic colors tie the picker to what the time it sets means, while the Background, Foreground and Border families keep it legible on non-default surfaces.

The glyphs are not limited to the built-in icon font: Icon and CloseButtonIcon take a BitIconInfo - or a raw CSS class string - that can point at any icon library whose stylesheet is loaded. Use BitIconInfo.Fa(), BitIconInfo.Bi() or BitIconInfo.Css() to build one.

FontAwesome:

Bootstrap:

Size scales the dial, its numbers and the toolbar together: Small where the clock has to share a dense layout, Medium (the default) for forms, and Large where the picker is the point of the screen or aimed at touch. The two rings and the hand keep their proportions at every size.

Style and Class land on the root element, while Styles and Classes reach every named part of the picker on their own - the toolbar, the face, the numbers, the hand and its thumb - so the callout can be restyled without a single descendant selector.

Component's Style & Class:

Styles & Classes:

Dir flips the field, the label and the toolbar into a right-to-left layout, and reaches the callout as well even though it is rendered outside the root element. The dial itself keeps running clockwise, and the parts of the time in the toolbar stay in reading order, because a clock reads the same way in every script.