PhoneInput

The field is made of two halves that share one frame: the country selector on the leading side and the number input on the trailing one. DefaultCountry picks the country the field starts on without taking control of the selection, so the user is free to change it afterwards, and Placeholder is the hint of the number input. Whatever is typed is combined with the dialing code of the selected country into the E.164 Value ("+14155550123"), which is the single string a form usually stores.

Typing a number that already carries an international prefix - either + or its 00 equivalent - selects the matching country by itself and keeps only the local digits in the input, so a pasted number lands correctly whatever the field was showing. Separators are welcome while typing: spaces, hyphens, dots and parentheses are dropped from the value, never from the field.

AutoFocus puts the caret in the number input on the first render, which is what a page whose only purpose is that one field (a sign-in step, a one-field dialog) should do. The country selector is left alone: it is a choice the user rarely has to make, so the focus goes where the typing happens.

Label renders a label above the field and wires it to the number input, so clicking it moves the focus there and screen readers announce it with the field. LabelTemplate replaces the text with markup of your own while keeping the same wiring. Adding Required marks the label with an asterisk and sets aria-required on the input.

Description writes a line under the field for the hint a label is too short to carry, and DescriptionTemplate renders markup there instead. Either way it is tied to the input through aria-describedby, so it is read with the field rather than as a stray line of text.

Countries replaces the built-in list of every country (BitCountries.All) with one of your own, which is how a form that only ships to a handful of markets is kept short. The list is also what the dialing-code lookup searches, so a number pasted with a code outside it is left whole instead of being attached to the wrong country. Each entry is a BitCountry, so its Name can be translated and its Code, Iso2 and Iso3 reused as they are.

ExcludeCountries works the other way round and takes a few countries out of the list the other parameters produced, which is the shorter way to say it when the exceptions are what is known - a sanctioned market, a territory a carrier does not reach. What is excluded is gone from the lookup too, so its dialing code no longer selects it.

PreferredCountries pins a few countries to the top of the list without removing the rest, which puts the ones most of your users pick within reach while an alphabetical list of 240 stays available underneath. They also break the tie when a typed dialing code belongs to several countries: +1 is both Canada and the United States, +7 both Kazakhstan and Russia. Without a preference the tie is settled by BitCountry.Priority, which the built-in list already sets on the country that owns each shared code, and the country currently selected always wins over both - changing the country is the user's decision, not the parser's. A country can also answer to more than one code: BitCountry.ExtraCodes holds the rest of them, which is how +1-829 finds the Dominican Republic instead of stopping at the +1 it starts with.

The country list opens with a search box focused and ready, and the term is matched against the name of the country, its two- and three-letter ISO codes and its dialing code all at once. The closest match comes first: an exact ISO code, then a name that starts with the term, then a dialing code that does. Accents are folded away, so "reunion" finds Réunion, a dialing code is found however it is written ("+44", "0044" and "44" are the same code), and a term of several words matches the initials of the name ("united sta"). How many countries a term left is announced to a screen reader, since the list it filtered is only ever seen. SearchBoxPlaceholder and SearchBoxAriaLabel label the box, NoResultsMessage is what an empty result says, and NoSearchBox takes the box away - the list then answers to type-ahead instead, jumping to the country whose name the typed letters start.

What the selector shows is up to you: NoFlags drops the flag images (from the button and from the list), NoDialCode hides the "+code" text next to the flag, and DropdownPlaceholder is what stands in the button while no country is selected yet. NoDropdown goes further and removes the selector as an interactive element altogether: the country still shows, but it can only be set through Country or DefaultCountry - the shape to use when the market is fixed and the choice would only be a way to get it wrong.

ShowClearButton adds a button at the end of the field while it holds a number. It empties the number, hands the focus back to the input and raises OnClear; the selected country is deliberately left alone, since clearing a number is not a reason to make the user find their country again. The icon comes from ClearButtonIconName (or ClearButtonIcon for an external icon set), and ClearButtonTemplate replaces the button's content entirely.

Last cleared at:

A phone number is digits, and everything else typed into the field is only ever a separator. The composed Value reflects that already - separators never reach it - but Strict makes it visible too, discarding on the spot every character that cannot be part of a number and keeping only the digits and an optional leading plus, whether they were typed one at a time or pasted in at once. MaxLength caps how many characters the field holds, which is the simplest guard against a mistyped number that is far too long; the cap covers the separators a pattern inserts as well, so it is the text on screen that is measured rather than only what was typed.

The field is only as wide as it needs to be by default, which suits a row of controls. FullWidth stretches it to 100% of its container instead, so it lines up with the rest of the fields of a form.

NoBorder takes the frame away and leaves the field to sit on whatever surface it is placed on - inside a toolbar or a table cell, where a second border would only add noise. Underlined keeps a single bottom rule instead of the full frame, and thickens it on focus rather than drawing a ring.

By default the value updates on the change event (when the input loses focus). Enable the Immediate parameter to update the value on every keystroke (the 'oninput' event). To rate-limit how often the value updates while typing, combine it with DebounceTime (waits until typing pauses) or ThrottleTime (updates at most once per interval) - useful when every change triggers a lookup or a validation round-trip.

Immediate:

Value: []

Immediate + DebounceTime (500ms):

Value: []

Immediate + ThrottleTime (500ms):

Value: []

The same field is bindable three ways at once, and the three stay in step whichever one changes: Value is the full E.164 number, Number the local digits the user types, and Country the selection. Assigning a full number from the outside splits it back into its parts (the country is resolved from the dialing code), and changing the country recomposes the value under the same local number. The BitTextField below is bound to the same Value, so editing either field updates the other; both are Immediate with a 500ms debounce.

Mask lays the digits out over a pattern as they are typed: every # is a digit slot and every other character is a separator inserted for the user, so (###) ###-#### turns 4155550123 into (415) 555-0123. Nothing is lost to it - digits beyond the last slot are appended as they are, and the separators are display only: the Value stays the plain E.164 number whatever the field shows. The caret stays on the digit it was on while the pattern rearranges the text around it, so the middle of a number is as editable as its end.

National conventions differ from one country to the next, so MaskSelector gives each one a pattern of its own; it takes precedence over Mask whenever it returns something, and returning null leaves that country unformatted. Picking a new country lays the digits already typed out over its pattern instead of keeping the separators of the country left behind.

AutoPlaceholder turns that pattern into the placeholder of the field, so the shape the country expects is offered before anything is typed. It only fills in for a missing Placeholder, and a country whose MaskSelector returns nothing keeps an empty field.

Inside an EditForm the field joins the cascading EditContext automatically and the data annotations on the model drive it: a failing field gets the bit-inv class and the aria-invalid="true" attribute. What is validated is the full E.164 Value, which is why a regular expression on the model can check the dialing code and the length together. NoValidate opts the field out of the EditContext altogether.

Outside a form the state is forced from the outside: Invalid alone marks the field, and ErrorMessage both marks it and writes the reason under it - for a rejection that comes from a server or from a rule no annotation can express. ErrorMessageTemplate renders markup there instead, and the message is pointed at by aria-describedby along with any description.

IsEnabled="false" dims the whole field and takes it out of the tab order - both halves of it, the selector as much as the input. ReadOnly keeps the field focusable and its text selectable, so the number can still be read and copied, while the typing and the country selection are refused.

Responsive turns the country list into a full-height side panel on small screens, the way a native picker takes over the screen instead of squeezing 240 rows into a callout that barely fits. The panel carries the Label of the field and a close button, whose icon and label are set through ResponsiveCloseIconName and ResponsiveCloseButtonAriaLabel. Narrow the window to see it.

Every visible part of the selector can be replaced. DropdownTemplate receives the selected country and renders the content of the button - the place to show a name instead of a code, or nothing at all. ItemTemplate renders each row of the list, NoResultsTemplate stands in for the empty result, and LabelTemplate replaces the label while keeping it tied to the input.

OnCountryChange fires whenever the selection changes, whether it was picked from the list or resolved from a typed dialing code. OnOpen and OnClose follow the callout, OnSearch reports every search term as it is typed, and OnChange carries the full E.164 value. The number input also raises the usual field events - OnFocus, OnBlur, OnFocusIn, OnFocusOut, OnClick, OnKeyDown, OnEnter and OnEscape.

Selected country:

Value:

Search text:

Callout: closed

Enter pressed: 0

IsOpen is two-way bound, so the callout can be opened and closed from anywhere else on the page and its state read back when the user does it. The component also exposes OpenAsync, CloseAsync, SelectCountryAsync, SetNumberAsync, ClearAsync and FocusAsync for the same work through a reference, plus FullNumber as a shorthand for the composed value. SetNumberAsync fills the field the way typing into it would, international prefix included, so handing it "+81 3 1234 5678" moves the selection to Japan on its own.

Picking a country normally hands the focus to the number input, since that is what the user came to type. NoFocusOnSelect leaves it where it was, for a form that decides itself where the focus goes next.

IsOpen: False

The flags that ship with the library are 16px images served from the Extras package. FlagUrlSelector points the flag of each country somewhere else instead - a sprite of your own, a CDN, an SVG set - and returning nothing for a country leaves it with the built-in image, so only the ones you care about have to be answered for. It reaches every flag at once: the one in the selector button and the one on every row of the list.

The visible input holds the local number, so a plain HTML form posting the field would otherwise send the digits without their dialing code. Name renders a hidden field carrying the full E.164 Value instead, which is the one string a server needs, and CountryName adds a second hidden field with the ISO 3166-1 alpha-2 code of the selection - for a schema that stores the country beside the number, or a server that has to know that "+16135550123" was entered as Canadian rather than as American.

Posted as phone:

Posted as phoneCountry: CA

The number input is a tel input, so a phone keypad is what a touch device offers and autocomplete="tel" is what a browser fills it from; spell checking, autocorrection and autocapitalisation are all turned off, since none of them has anything to say about a phone number. AutoComplete names another autofill token when the field is not the owner's own number (tel-national, or off), InputMode asks for a different on-screen keyboard, and EnterKeyHint labels its return key - "next" in the middle of a form, "send" at the end of one.

The country list is a callout placed against the field and kept on screen: by default (BitDropDirection.TopAndBottom) it drops below the field when there is room and flips above it when there is not. DropDirection set to All lets it take a side as well, which is what a field near the bottom of a narrow window needs, and MaxHeight caps how tall it may grow - a short list is easier to scan than one that fills the window, and a taller one saves a scroll on a page that has the room for it.

Inside the list the arrow keys wrap around at both ends, so the last country is one press up from the first. NoWrapNavigation stops them at the ends instead, for the users who read the stop as "there is nothing more this way". Home, End, Page Up and Page Down move through it either way.

Color repaints the frame and the focus ring of the field in one of the general colors of the library, which is how a field is tied to the meaning of the section it belongs to.

Besides the built-in Fluent icon set exposed through ClearButtonIconName and ResponsiveCloseIconName, the ClearButtonIcon and ResponsiveCloseIcon parameters render icons from any CSS-class based library such as FontAwesome or Bootstrap Icons. Pass the raw classes directly, or use the BitIconInfo helpers (Css, Fa and Bi) for a shorter syntax. When both parameters are set, the icon one wins. Remember to reference the icon library's stylesheet in your app.

Size scales the field as a whole - its height, its padding, its text, its flags and the rows of the country list - so a phone input sits at the same height as the other controls of a compact toolbar or of a roomy form.

Style and Class land on the root element, while Styles and Classes reach every part of the component by name - the field group, the dropdown, the input, the callout, each item and the rest - which is how a field is themed without a single ::deep selector.

Dir="BitDir.Rtl" mirrors the field: the country selector moves to the right of the number input, the callout is aligned to the right edge and the responsive panel slides in from the left. The number itself is left to right wherever it is read, so the digits and the separators around them keep their order inside a right-to-left field instead of being reordered around each other.