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 reports the field as required to assistive technology, Disabled turns it off, and IconName replaces the clock glyph that trails the field. Enforcing the requirement is the job of the validator the picker is bound through - see the Validation sample.

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 and out of the accessibility tree, so the dial is the one thing the keyboard lands on, and the one FocusAsync puts the focus on. The dial takes the name of the field with it - AriaLabel, or the Label where there is none - ahead of the part of the time it is on, and clicking the label moves the focus to it.

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 - including the AM/PM pair, which is shown so the read-out can be placed in the day but is not offered where the hour is not a part being edited. 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. The pair is a range inside one day and does not wrap past midnight - a window that does, such as a night shift, is a job for AllowedHours.

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 as soon as the selection is complete, without waiting for either - AutoCloseDelay holds the clock open for a moment first, so the pick that completed it can be seen being made. 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.

ValueFormat is the .NET format string the field is written with. Left unset, the picker writes the time the way its culture does: the pattern of the culture, rewritten into the clock format the dial is in (TimeFormat), extended with the seconds where ShowSeconds is set and padded with leading zeros.

AllowTextInput makes the field editable, so a time can be typed instead of dialled. It is read back with the same format - which is why the format is worth putting in the placeholder - except that the default one also accepts a time written without its leading zeros.

@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:

StartingValue is not a value: the picker below stays empty and submits nothing until it is touched. It is only where the first change lands, so moving the hour keeps the 30 minutes instead of resetting them to midnight - which is what a picker that mostly gets times around the working day wants. Open both and dial an hour to see the difference.

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 (opens in a new tab) 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 IconPlacement 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.

Two parameters answer the space the picker has, and the small breakpoint is where one hands over to the other. Landscape puts the toolbar down the leading edge instead of above the clock, stacking the parts of the time in a column - roughly half the height for a picker with width to spare - and takes effect from that breakpoint up. Responsive takes over below it, turning the callout into a sheet anchored to the top of the screen that can be swiped away upwards. 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.

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. In the toolbar the part the dial is on carries a rule under it rather than the other two being dimmed, so which one is being edited never rests on a difference of contrast.

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. Text is the only way a time the dial itself refuses can reach it, and the three ways it can be wrong get three messages of their own - InvalidErrorMessage for one that cannot be read, OutOfRangeErrorMessage for one outside MinTime / MaxTime, and DisallowedTimeErrorMessage for one the Allowed* predicates rule out. The steps are the one constraint typed text is not held to. A Standalone picker has no field to redden, so the rule is drawn around the dial instead, and the dial is what carries aria-required and aria-invalid.

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

A form full of time pickers usually repeats the same handful of parameters on every one of them. BitParams takes them out of the markup: it cascades a BitCircularTimePickerParams down to every BitCircularTimePicker underneath it, however deeply nested. Every property of that class is nullable, so only the ones actually set travel; the rest are left alone.

Here the clock format, the minute step, the actions and the accent are set once for the whole group. A value written on a picker itself always wins - the cascade only fills in what the markup left alone - which is why the last one below keeps its own step and color:

The value and the open state are deliberately left out of BitCircularTimePickerParams: both are per-field state the picker assigns to itself, so a cascaded value would be written straight back over what the person just picked. StartingValue is the cascadable way to say where an empty picker begins.

Parameters is a list, so a single BitParams can carry the parameters of several component types at once - a BitCircularTimePickerParams next to a BitButtonParams, each one reaching only the components it belongs to.

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 field, the label, the dial, its numbers and the toolbar together, so the picker lines up with the other controls of a form at whichever size they are: 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:

CSS variables (listed in the table at the bottom of this page) restyle the picker without a selector. On :root they re-skin every picker of the app. The callout moves to the body when it opens, so a wrapper around the picker reaches the field, the label and the icon but never the dial - its variables go on Styles.Callout instead:

Per instance, Styles.Root covers the field and Styles.Callout the dial:

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.