On this page
@addTagHelper *, Webority.Ui.RazorVariants
Every look of the field side by side. Each caption names the attribute that draws it.
Types and labels
Pick the input type so the keyboard and native checks fit the value, and keep a visible label on every field.
Compact semibold labels
A product sets --wui-field-label-fs and --wui-field-label-fw on any ancestor to retune every field label below it. Unset, labels keep the default 11px at weight 500.
Floating label
An animated variant: the label starts inside as the placeholder, then slides up and shrinks on focus or once the field is filled. Set floating-label to border. It stands alone: no icon, unit or affix in the same field.
Sizes and icons
Use md by default, sm in dense toolbars and lg for marketing fields, and an icon only when it adds meaning.
Units and affixes
A unit or affix shows fixed text, like a currency mark or measurement, never part of the typed value.
Input masks
A mask formats the value as it is typed, with separators and checks built in for each named format.
Password
Let people reveal what they typed before they submit, and show the password rules live while they type.
Validation and actions
Helper text guides, and an error replaces it; a verify button can sit beside the field.
Clearable
Set clearable and an ✕ appears once the field has a value. One click empties it and refocuses. Useful on any editable field: a coupon, a tag, a filter value. (For an actual search box, reach for AppSearch.) The ✕ fades in as you type.
Character count
Set show-count for a live count under the field; add max-length to cap the input and show the denominator. The count turns red at the limit.
In a centred column
Disabled and read only
Disable a field that cannot be edited yet; set read only when its value must still post with the form.
Custom class
Hook your own styling onto a field: input-class lands on the input element, class on the .field wrapper. Both append after the design-system classes, so yours win on equal specificity.
Control only
Control only draws just the input, for a dense form that draws its own labels and messages.
Every option
Every value of every prop, one cell each.
type: all seven
type="text" (default)type="email"type="number"type="tel"type="url"type="search"type="password"size: every size
size="sm"size="md" (default)size="lg"label, name and id
label="Email"name="opt-name"id="opt-id"placeholder and value
placeholder="Search projects…"value="Acme Inc." (React: defaultValue)value="Acme Inc." (React: value with onChange)action
app-input-action child (React: action)required, optional, disabled, readOnly and loading
(default)requiredoptionaloptional-label="Optional" with optionaldisabledread-onlyloadinghelperText and error
error="Required"helper-text="Helper text"required + errorhelp and helpLabel
help="Find it on the registration certificate."help-label="About the tax ID" with helpleftIcon, rightIcon, rightIconLabel and onRightIconClick
left-icon="mail"right-icon="search"onRightIconClick, runs when the icon is pressed (React only)right-icon-label="Run search"clearable and clearLabel
clearable, empty (✕ hidden)clearable, with a value (✕ visible)clear-label="Reset" with clearableunit, prefix and suffix
unit="m²"prefix="₹"suffix=".com"prefix and suffixfloatingLabel
floating-label="off" (default)floating-label="border"floating-label="above"variant
variant="bare"mask, postFormatted and onMaskChange
mask="phone-in"mask="pan"mask="gstin"mask="aadhaar"mask="ifsc"mask="pin-code"mask="date"mask="amount"mask="(999) 999-9999"post-formatted="true", posts the formatted valueonMaskChange, called with each change (React only)showCount and maxLength
show-count="true"show-count with max-length="60" (under the limit)show-count with max-length="4" (at the limit, red)passwordRequirements
password-requirements="off" (default)password-requirements="shown"passwordPolicy
password-min-length="10" (React: minLength)password-unique-chars="4" (React: uniqueChars)password-custom-rules (React: customRules)password-uppercase="false" (React: uppercase)password-lowercase="false" (React: lowercase)password-digit="false" (React: digit)password-special="false" (React: special)requirementsPlacement
requirements-placement="auto" (default)requirements-placement="top"requirements-placement="bottom"requirements-placement="start"requirements-placement="end"requirements-placement="inline"requirementsTitle, showPasswordLabel and hidePasswordLabel
requirements-title="Choose a strong password"show-password-label="Show code"hide-password-label="Hide code"className and fieldClassName
input-class="js-track" (React: className)class="demo-field" (React: fieldClassName)monospace
monospace="true"controlOnly
control-only="true" (React: controlOnly)asp-for
asp-for (Razor only, React binds with value)Guidance
What to do, and what to avoid.
Use it when
- The user enters a single line of text or a number: name, email, amount, reference.
- You want the shared field treatment: label, helper text, error, and required marking.
- A specific type (email, number, tel) should drive the keyboard and native validation.
Reach for something else when
- The value runs to multiple lines: a note or description. → AppTextarea
- The user picks from a fixed set of options. → AppSelect
- It is a search box that filters a list. → AppSearch
- The value is a calendar date. → AppDatePicker
A visible label, not a placeholder
A visible label stays put while the user types and is read by screen readers.
A placeholder used as the label vanishes on the first keystroke and fails accessibility.
Use the right input type
type="email" brings the right keyboard and native validation for free.
A plain text type misses the email keyboard and validation the browser could give.
Say exactly what is wrong
A specific error tells the user exactly what to change.
Invalid leaves them guessing what is actually wrong.
Reference
Try every prop, read the full list, and check keyboard and screen reader behaviour.
48 props. The 5 most used come first.
Used on most screens 5 props
| Prop | Type | Default | Description |
|---|---|---|---|
| labeldefault - | string | - | The field label. Always set one; never rely on the placeholder. |
| placeholderdefault - | string | - | Text shown in an empty field. |
| requireddefault false | bool | false | Marks the field as required, with a visible mark and the native required attribute. |
| helper-textdefault - | string | - | Help text under the field. An error replaces it while both are set. |
| errordefault - | string | - | A validation message under the field. It marks the control invalid for assistive technology. |
Less common 43 props
| Prop | Type | Default | Description |
|---|---|---|---|
| asp-fordefault - | ModelExpression | - | Razor-only; no React equivalent. Binds to a Razor Pages model property. It derives name, id, value, [Display] label and [Required] and emits unobtrusive validation attributes plus the validation message in place of a manual error. |
| namedefault - | string | - | The form field name. |
| typedefault text | string | text | The native input type, such as email, tel, number or password. |
| prefixdefault - | string | - | A bordered box before the input (e.g. https://). |
| suffixdefault - | string | - | A bordered box after the input (e.g. .00). |
| floating-labeldefault off | off | border | above | off | Where the label rests. Off keeps it above the field. Border sits it inside as a placeholder, then slides it onto the top border once the field is focused or filled. Above rests it above the box, clear of the border. |
| clearabledefault false | bool | false | Shows a clear button while the field has a value. |
| clear-labeldefault Clear | string | Clear | Replaces the built-in English text, for other languages. |
| maskdefault - | string | - | A named mask such as pan, phone-in, gstin, aadhaar, ifsc, pin-code, date or amount, or a pattern where 9 is a digit and A a letter. The value is formatted as it is typed. |
| post-formatteddefault false | bool | false | With a mask, a native form submit posts the formatted value instead of the raw characters. |
| show-countdefault false | bool | false | Shows a live character count under the field. |
| max-lengthdefault - | int | - | The character cap. The count turns red as the cap is approached. |
| sizedefault md | sm | md | lg | md | The control size: sm, md and lg are 32, 36 and 44px. Md is the default. |
| valuedefault - | string | - | The controlled value. Pair it with onChange. |
| 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. |
| left-icondefault - | string | - | A leading icon, given as a semantic icon name. |
| unitdefault - | string | - | A unit shown after the value, such as kg. |
| right-icondefault - | string | - | A trailing icon button, given as a semantic icon name. It calls onRightIconClick when pressed. |
| right-icon-labeldefault - | string | - | The accessible name of the right-icon button. It falls back to the icon name. |
| disableddefault false | bool | false | Disables the field. |
| read-onlydefault false | bool | false | Locks the field; the value still posts. A clearable field shows no clear button. |
| loadingdefault false | bool | false | Shows a busy state and blocks input while data loads. |
| helpdefault - | string | - | Info-tip content shown beside the label. |
| help-labeldefault More information | string | More information | The accessible name of the info-tip button. |
| iddefault - | string | - | The id of the control. The label points at it. |
| input-classdefault - | string | - | Extra classes on the input element. |
| classdefault - | string | - | Extra classes on the .field wrapper. |
| variantdefault - | bare | - | A borderless look with no border or background, for inline editing. |
| monospacedefault false | bool | false | Sets the monospace font, for codes and references. |
| password-requirementsdefault off | off | shown | off | On a password field, shows a live checklist of the password rules as the user types. It uses the default policy unless passwordPolicy is set. |
| password-min-lengthdefault 10 | int | 10 | Minimum-length rule. Set 0 to drop the length rule. |
| password-uppercasedefault true | bool | true | Require at least one uppercase letter. |
| password-lowercasedefault true | bool | true | Require at least one lowercase letter. |
| password-digitdefault true | bool | true | Require at least one digit. |
| password-specialdefault true | bool | true | Require at least one special (non-alphanumeric) character. |
| password-unique-charsdefault 0 | int | 0 | Require at least N distinct characters. 0 omits the rule. |
| password-custom-rulesdefault - | string (JSON) | - | Your own rules, as a JSON array of {"label": "...", "pattern": "..."}. A rule ticks while the JavaScript regular expression pattern matches the password. A list that is not valid JSON of that shape throws at render. |
| requirements-titledefault Password requirements | string | Password requirements | Replaces the built-in English text, for other languages. |
| requirements-placementdefault auto | auto | top | bottom | start | end | inline | auto | The side the requirements popover opens on. Auto flips to stay in view. Inline puts the checklist under the field, in place of the helper text. |
| show-password-labeldefault Show password | string | Show password | Replaces the built-in English text, for other languages. |
| hide-password-labeldefault Hide password | string | Hide password | Replaces the built-in English text, for other languages. |
| control-onlydefault false | bool | false | Draws only the control: no field wrapper, label row or message line. Name it with aria-label, aria-labelledby or a label the page draws, because the component draws none. |
Screen reader
5 notes- The control carries aria-invalid, and aria-describedby points at the error or the helper text.
- The clear button is named Clear and is hidden while the field is empty.
- The password reveal button is named Show password or Hide password, and the checklist sits in a polite live region.
- The right-icon button is named by rightIconLabel, or by the icon name when none is given.
- The info-tip button is named by helpLabel.
Do and avoid
3 pairsA visible label, not a placeholder
A visible label stays put while the user types and is read by screen readers.
A placeholder used as the label vanishes on the first keystroke and fails accessibility.
Use the right input type
type="email" brings the right keyboard and native validation for free.
A plain text type misses the email keyboard and validation the browser could give.
Say exactly what is wrong
A specific error tells the user exactly what to change.
Invalid leaves them guessing what is actually wrong.