Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Flag and dial code

Show or hide the flag and the dial code, but keep the country picker so the country stays selectable.

Show or hide each part
default: flag and dial code
show-flag="false"
show-dial-code="false"
both off
Show code
<app-phone-number-input label="Mobile" />
<app-phone-number-input label="Mobile" show-flag="false" />
<app-phone-number-input label="Mobile" show-dial-code="false" />
<app-phone-number-input label="Mobile" show-flag="false" show-dial-code="false" />

Locked country

Lock the country when only one applies, so the field shows a fixed prefix and no picker.

Fixed country prefix
Show code
<app-phone-number-input label="Mobile number" locked-country="IN" show-flag="false" />

Sizes

Match the phone field height to its neighbours in a form, using sm and lg to step the ladder.

Three sizes
Show code
<app-phone-number-input label="Mobile" size="Sm" />
<app-phone-number-input label="Mobile" />
<app-phone-number-input label="Mobile" size="Lg" />

Country code and number

Put the dial code and the number in one control, so the country and the digits cannot drift apart.

A phone field
Show code
<app-phone-number-input label="Mobile" name="mobile" country="IN" />

Label and required

Always label a phone field, because the country picker alone does not say what the number is for.

Labelled and required
Show code
<app-phone-number-input label="Contact number" name="contactNumber" country="IN" required="true" />

Error state

Show a field-level message under the control when the number fails validation, in the theme's error style.

With a validation error
Enter a valid phone number
Show code
<app-phone-number-input label="Phone" name="phone" country="IN" required="true" error="Enter a valid phone number" />

Every option

Every value of every prop, one cell each.

value

(default): empty
value="9876543210": national digits, country="IN"
value="+919876543210": the same number, international
value="+14155552671": international, the picker follows to US

id

id="phone-main": the id of the control, one is generated when unset

onChange

onChange: React only, so Razor reads the posted value by name

country

(default): the viewer's own country
country="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 stays
locked-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 name

placeholder

(default): the country's example number
placeholder="Enter your mobile number"

name

name="every-name": the form field name, posted with the value

required

required="false" (default)
required="true"

disabled

disabled="false" (default)
disabled="true"
disabled, with a value

readOnly

read-only="false" (default)
read-only, with a value

loading

loading="false" (default)
loading="true"

defaultValue

(default): no starting value
value="9876543210" (React: defaultValue)

help

(default): no info-tip
help="Delivery updates only": the content of the info-tip beside the label

helpLabel

help-label="More information" (default)
help-label="About this number"

helperText

(default): no helper text
helper-text="We never share this number."
We never share this number.

error

(default): no error
error="Enter a valid phone number"
Enter a valid phone number
error, with required
Enter a valid phone number

showFlag

show-flag="true" (default)
show-flag="false"

showDialCode

show-dial-code="true" (default)
show-dial-code="false"

fieldClassName

(default): no extra class
class="mb-3" (React: fieldClassName)

optional

optional="false" (default)
optional="true"

optionalLabel

optional-label="(optional)" (default)
optional-label="(not needed)"

className

(default): no extra class
input-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

Do

Default the country to the one most users will pick: fewer taps for the common case.

Avoid

No label and no sensible default country: the user guesses what to enter and where.

Show the error under the field

Do
Enter a valid phone number

Surface validation inline with error, right under the field the user must fix.

Avoid

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.

(none) IN US GB AE SG AU FR DE JP ZA BR NG
(none) IN US GB AE SG AU FR DE JP ZA BR NG
sm md lg
React, generated from the controls
<AppPhoneNumberInput name="phone" helpLabel="More information" />
Razor, the same props
<app-phone-number-input name="phone" />

20 props. The 5 most used come first.

Used on most screens 5 props

PropTypeDefaultDescription
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

PropTypeDefaultDescription
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 pairs

Default the country

Do

Default the country to the one most users will pick: fewer taps for the common case.

Avoid

No label and no sensible default country: the user guesses what to enter and where.

Show the error under the field

Do
Enter a valid phone number

Surface validation inline with error, right under the field the user must fix.

Avoid

Required with no error feedback: the user submits and is bounced with no clue why.