Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Basic

Use the six-digit default for a sign-in or verification code, typed, pasted or filled from an SMS.

A verification code
Show code
<app-otp-input label="Verification code" name="Code" />

States

Set a length and mode that match the code, and show errors and disabled states beside it.

Length, mode, error and disabled
That code has expired.
Show code
<app-otp-input label="Backup code" name="B1" length="8" mode="Alphanumeric" />
<app-otp-input label="Verification code" name="B2" error="That code has expired." />
<app-otp-input label="Verification code" name="B3" disabled="true" />

Every option

Every value of every prop, one cell each.

value

value="482913"

onChange (React only)

onChange: React only, called with the code on each change; a form posts the code instead

onComplete (React only)

onComplete: React only, called once when the last character lands; a form posts the code on submit

defaultValue (React only)

value="482913" (React: defaultValue)

readOnly / read-only

read-only="false" (default)
read-only="true"

loading

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

size

size="sm"
size="md" (default)
size="lg"

help

help="Codes arrive by SMS within a minute."

helpLabel / help-label

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

length

length="4"
length="6" (default)
length="8"

mode

mode="numeric" (default)
mode="alphanumeric"

label

label="Sign-in code"

required

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

helperText / helper-text

helper-text="Sent via SMS to •••• 42"
Sent via SMS to •••• 42

error

error="That code has expired."
That code has expired.

disabled

disabled="false" (default)
disabled="true"

name

name="Code" (posted with the form)

id

id="sign-in-code" (no visible change)

className / input-class

input-class="extra-class" (no visible change)

optional

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

optionalLabel / optional-label

optional-label="(optional)" (default)
optional-label="(facultatif)"

fieldClassName / class

class="extra-field" (no visible change)

asp-for (Razor only)

asp-for (Razor only): binds name, id, value, label and required from a model

Guidance

What to do, and what to avoid.

Use it when

  • A one-time code: MFA, email or phone verification, backup codes.
  • Anywhere the code has a known, fixed length.

Reach for something else when

  • A password or passphrase. → AppInput with type="password"
  • A code of unknown or variable length. → AppInput
  • A licence key with separators. The segments here are characters, not groups. → AppInput

One field for the whole code

Do

One labelled field, six boxes drawn underneath. Autofill, paste and a screen reader all work.

Avoid

Six inputs: the OS drops the whole SMS code into box one, and a screen reader announces six unlabelled boxes.

Reference

Try every prop, read the full list, and check keyboard and screen reader behaviour.

4 6 8
numeric alphanumeric
sm md lg
React, generated from the controls
<AppOtpInput label="Verification code" helpLabel="More information" name="Code" value={code} onChange={setCode} />
Razor, the same props
<app-otp-input label="Verification code" name="Code" />

20 props. The 5 most used come first.

Used on most screens 5 props

PropTypeDefaultDescription
labeldefault - string - The visible label. It also becomes the field's accessible name.
valuedefault - string - The code the field starts with.
lengthdefault 6 int 6 Characters in the code. TOTP is 6; backup codes are often 8.
requireddefault false bool false Marks the field required for assistive technology and shows the required mark beside the label.
helper-textdefault - string - Help text under the code. It is hidden while an error is shown.

Less common 15 props

PropTypeDefaultDescription
asp-fordefault - ModelExpression - Model property to bind to. Supplies name, id, value, label and required.
namedefault - string - The form field name, so a plain form post includes the code.
iddefault - string - The element id. A generated id is used when this is omitted.
modedefault numeric numeric | alphanumeric numeric Drives the on-screen keyboard and what the field will accept.
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.
errordefault - string - The error message under the code. It replaces the helper text and marks the field invalid.
disableddefault false bool false Disables the field so the code cannot be entered.
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.
sizedefault md sm | md | lg md The control size: sm, md or lg.
helpdefault - string - Info-tip content shown beside the label.
help-labeldefault More information string More information The accessible name of the info-tip button.
classdefault - string - Extra classes on the field wrapper. Use input-class for the control.
input-classdefault - string - Extra classes on the control itself. The plain class attribute merges onto the field wrapper instead.

Screen reader

5 notes
  • One input, with the segment boxes drawn underneath, so a screen reader announces one labelled field instead of six unlabelled boxes.
  • OS autofill delivers the whole code to the one field, so an SMS code is never split across boxes.
  • A string label is the accessible name of the control, because a label element cannot point at the custom element.
  • An error marks the field invalid and is linked to it as the description, which takes precedence over the helper text.
  • Helper text is linked to the field as its description when no error is shown.

Do and avoid

1 pairs

One field for the whole code

Do

One labelled field, six boxes drawn underneath. Autofill, paste and a screen reader all work.

Avoid

Six inputs: the OS drops the whole SMS code into box one, and a screen reader announces six unlabelled boxes.