On this page
@addTagHelper *, Webority.Ui.RazorFlag and dial code
Show or hide the flag and the dial code, but keep the country picker so the country stays selectable.
Locked country
Lock the country when only one applies, so the field shows a fixed prefix and no picker.
Sizes
Match the phone field height to its neighbours in a form, using sm and lg to step the ladder.
Country code and number
Put the dial code and the number in one control, so the country and the digits cannot drift apart.
Label and required
Always label a phone field, because the country picker alone does not say what the number is for.
Error state
Show a field-level message under the control when the number fails validation, in the theme's error style.
Every option
Every value of every prop, one cell each.
value
(default): emptyvalue="9876543210": national digits, country="IN"value="+919876543210": the same number, internationalvalue="+14155552671": international, the picker follows to USid
id="phone-main": the id of the control, one is generated when unsetonChange
onChange: React only, so Razor reads the posted value by namecountry
(default): the viewer's own countrycountry="IN"country="US"country="GB"country="AE"country="SG"country="AU"country="FR"country="DE"country="JP"country="ZA"country="BR"country="NG"lockedCountry
(default): no lock, the picker stayslocked-country="IN"locked-country="US"locked-country="GB"locked-country="AE"locked-country="SG"locked-country="AU"locked-country="FR"locked-country="DE"locked-country="JP"locked-country="ZA"locked-country="BR"locked-country="NG"size
size="sm"size="md" (default)size="lg"label
(default): "Phone number"label="Contact number"label="": no label, no accessible nameplaceholder
(default): the country's example numberplaceholder="Enter your mobile number"name
name="every-name": the form field name, posted with the valuerequired
required="false" (default)required="true"disabled
disabled="false" (default)disabled="true"disabled, with a valuereadOnly
read-only="false" (default)read-only, with a valueloading
loading="false" (default)loading="true"defaultValue
(default): no starting valuevalue="9876543210" (React: defaultValue)help
(default): no info-tiphelp="Delivery updates only": the content of the info-tip beside the labelhelpLabel
help-label="More information" (default)help-label="About this number"helperText
(default): no helper texthelper-text="We never share this number."error
(default): no errorerror="Enter a valid phone number"error, with requiredshowFlag
show-flag="true" (default)show-flag="false"showDialCode
show-dial-code="true" (default)show-dial-code="false"fieldClassName
(default): no extra classclass="mb-3" (React: fieldClassName)optional
optional="false" (default)optional="true"optionalLabel
optional-label="(optional)" (default)optional-label="(not needed)"className
(default): no extra classinput-class="fw-semibold" (React: className)Guidance
What to do, and what to avoid.
Use it when
- Collecting an international phone number where the country dial code matters.
- A signup or contact form that needs a valid, dialable number.
- You want one field the user can’t desync: the code and the number are captured together.
Reach for something else when
- The value is any non-phone text. → AppInput
- It is a generic numeric value (quantity, amount). → AppInput
- You need a date rather than a number. → AppDatePicker
- You are picking from a fixed list of labels. → AppSelect
Default the country
Default the country to the one most users will pick: fewer taps for the common case.
No label and no sensible default country: the user guesses what to enter and where.
Show the error under the field
Surface validation inline with error, right under the field the user must fix.
Required with no error feedback: the user submits and is bounced with no clue why.
Reference
Try every prop, read the full list, and check keyboard and screen reader behaviour.
20 props. The 5 most used come first.
Used on most screens 5 props
| Prop | Type | Default | Description |
|---|---|---|---|
| labeldefault Phone number | string | Phone number | Field label above the control. |
| namedefault - | string | - | The form field name. |
| valuedefault - | string | - | The phone number as entered. |
| countrydefault detected | string | detected | The ISO country code to start on. Left unset, the control starts on the viewer's own country. |
| requireddefault false | bool | false | Marks the field required and adds the required mark to the label. |
Less common 15 props
| Prop | Type | Default | Description |
|---|---|---|---|
| locked-countrydefault - | string | - | ISO alpha-2 code. The dial code is a static prefix with no picker, and the value always carries this country. |
| sizedefault md | sm | md | lg | md | The control height. |
| placeholderdefault the country's sample | string | the country's sample | Placeholder text in the empty field. Left unset, the control shows the country's example number. |
| optionaldefault false | bool | false | Ends the label with (optional) when the field is not required. Required wins when both are set. |
| optional-labeldefault (optional) | string | (optional) | Replaces the built-in English text, for other languages. |
| read-onlydefault false | bool | false | Shows the value but blocks editing. The value still posts. |
| loadingdefault false | bool | false | Shows a busy state and blocks input while data loads. |
| helpdefault - | string | - | The content of the info-tip beside the label, opened by a button. |
| help-labeldefault More information | string | More information | The accessible name of the info-tip button. |
| helper-textdefault - | string | - | Help text under the field. The error replaces it while one is shown. |
| errordefault - | string | - | An error message under the field, which also turns the border red. |
| disableddefault false | bool | false | Turns the field off. |
| show-flagdefault true | bool | true | Shows the country flag. |
| show-dial-codedefault true | bool | true | Shows the country dial code, such as +91. |
| input-classdefault - | string | - | Extra classes on the control itself. The plain class attribute merges onto the field wrapper instead. |
Screen reader
3 notes- The label is a real label tied to the field by id, and a text label is also passed to the phone control as its accessible name.
- An error or helper text is linked to the field with aria-describedby, and the helper text gives way to the error while one shows.
- An error sets aria-invalid on the control, and required adds the required mark and marks the control required.
Do and avoid
2 pairsDefault the country
Default the country to the one most users will pick: fewer taps for the common case.
No label and no sensible default country: the user guesses what to enter and where.
Show the error under the field
Surface validation inline with error, right under the field the user must fix.
Required with no error feedback: the user submits and is bounced with no clue why.