Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Basic

Use a labelled multi-line field for notes, descriptions and other text that runs past one line.

A labelled textarea
One field with a label and a placeholder.
Show code
<app-textarea label="Notes" name="notes" rows="4" placeholder="Add any additional details…"></app-textarea>

Sizing

Set rows to the typical answer: two lines for a short note, six for a full description.

Short and tall
A two-row summary above a six-row description.
Show code
<app-textarea label="Summary" name="summary" rows="2" placeholder="One or two lines…"></app-textarea>
<app-textarea label="Description" name="description" rows="6" placeholder="A fuller description…"></app-textarea>

Auto-grow

Let the field grow with the text, so a long answer never scrolls inside a fixed box.

Grows as you type
A field that starts at two rows and grows with the text.
Show code
<app-textarea label="Notes" name="notes" auto-grow="true" rows="2" placeholder="Type a few lines…"></app-textarea>

Character count

Show a live count, and add a cap when the answer has a fixed limit, such as a short bio.

Live count with a cap
A bio field counting towards 280 characters.
41 / 280
Show code
<app-textarea label="Bio" name="bio" show-count="true" max-length="280" rows="3" placeholder="Up to 280 characters"></app-textarea>

Validation

Give short helper text for guidance, and an error that says how to fix a problem.

Helper text and error
One field with helper text, one showing a required error.
Markdown supported.
Description is required.
Show code
<app-textarea label="Scope of work" name="scope" helper-text="Markdown supported."></app-textarea>
<app-textarea label="Description" name="description" required error="Description is required."></app-textarea>

Optional field

Mark a field optional when the form asks for it but does not need it.

Optional field
A field whose label ends with (optional).
Show code
<app-textarea label="Additional notes" name="notes" optional></app-textarea>

Monospace

Set monospace for codes, logs and pasted data, where the characters must line up.

Monospace payload
A three-row field in the monospace font.
Show code
<app-textarea label="Payload" name="payload" rows="3" monospace="true"></app-textarea>

Control only

Control only draws just the textarea, for a dense form that draws its own labels and messages.

Control only
The label is drawn on the page.
Show code
<label id="co-message-label">Message</label>
<app-textarea control-only="true" aria-labelledby="co-message-label" name="co-message"></app-textarea>

Every option

Every value of every prop, one cell each.

label: present or omitted

(no label): placeholder only
label="Notes"

name: the posted field name

name="notes": no visible effect, the key the text posts under

rows: the visible line count

rows="2"
rows="4" (default)
rows="6"
rows="10"

autoGrow: off vs on, with overflow content

(default): fixed rows, scrolls
auto-grow: height fits the content

showCount: live count

(default): no count
show-count="true": live count under the field
13

maxLength: the cap

(default): no cap
max-length="40": typing stops at 40 characters

placeholder: the empty-field text

placeholder="Type here…": shown in the empty field

value: the text the field opens with

value="Starting text": the text the field opens with (React: defaultValue)

optional: the label suffix

(default): no suffix
optional="true": ends the label with (optional)

optionalLabel: the suffix text

optional-label="(optional)" (default)
optional-label="Optional, by choice": replaces the built-in text

state: required, disabled, readOnly, loading, error, helperText

(default)
required
disabled
read-only
loading: busy state, blocks input
error
Notes are required.
helper-text
Markdown supported.
error + helper-text (error wins)
Markdown supported.
Notes are required.
required + error
Notes are required.

size: sm, md, lg

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

help: the info-tip beside the label

(no help)
help="…", help-label="More information" (default)
help + help-label="Notes help"

id: the control's id

id="notes-id": no visible effect, names the control

field wrapper class (fieldClassName, class)

class: a class on the field wrapper (React: fieldClassName)

control class (className, input-class)

input-class: a class on the control (React: className)

monospace: the font

(default): proportional font
monospace="true": monospace font on the control

controlOnly: the bare control

(default): label, field and message drawn
control-only="true": the textarea only, named by aria-labelledby (React: aria-label)

…rest: pass-through props (React only)

…rest: onChange and the ref pass through to the textarea (React only)

Guidance

What to do, and what to avoid.

Use it when

  • The value is free-form text that can run past a single line: a note, description, comment, or address block.
  • You want the same labelled treatment (helper text, error, required) as the rest of the form, for a longer answer.
  • The user might write a few words or a few paragraphs and you can't predict which.

Reach for something else when

  • The value is a single short line: a name, email, or reference. → AppInput
  • The user picks from a fixed set of options. → AppSelect
  • It is a search box that filters a list. → AppSearch

Keep a visible label

Do
What the assessment covers.

A visible label stays put while the user types and is read by screen readers.

Avoid

A placeholder used as the label vanishes on the first keystroke and fails accessibility.

Match the height to the answer

Do

A height that matches the expected answer keeps the form compact and scannable.

Avoid

An oversized box wastes space and signals 'write an essay' when you wanted a sentence.

Say exactly what to change

Do
Add at least one sentence describing the work.

A specific error tells the user exactly what to change.

Avoid
Invalid

'Invalid' leaves them guessing what is actually wrong.

Reference

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

sm md lg
React, generated from the controls
<AppTextarea label="Notes" name="pg-textarea" placeholder="Add any additional details…" />
Razor, the same props
<app-textarea label="Notes" name="pg-textarea" placeholder="Add any additional details…"></app-textarea>

24 props. The 5 most used come first.

Used on most screens 5 props

PropTypeDefaultDescription
labeldefault - string - The field label. Always set one. Never rely on the placeholder.
placeholderdefault - string - Text shown in the empty field.
requireddefault false bool false Marks the field required and shows the required mark beside the label.
helper-textdefault - string - Help text under the field.
errordefault - string - An error message. It replaces the helper text and marks the field invalid.

Less common 19 props

PropTypeDefaultDescription
namedefault - string - The field name the text posts under.
auto-growdefault false bool false Grows the height to fit the content as the user types.
show-countdefault false bool false Shows a live character count under the field, as count / maxLength when maxLength is set.
max-lengthdefault - int - The character cap. The count turns red as it is approached.
rowsdefault 4 int 4 The visible number of text lines.
valuedefault - string - The controlled value, paired with onChange.
optionaldefault false bool false Ends the label with (optional) when the field is not required. Required wins when both are set.
disableddefault false bool false Locks the field and keeps it out of the form post.
read-onlydefault false bool false Locks the field; 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.
optional-labeldefault (optional) string (optional) Replaces the built-in English text, for other languages.
help-labeldefault More information string More information The accessible name of the info-tip button.
iddefault - string - The control's id. A generated id is used when this is unset.
classdefault - string - Extra classes on the .field wrapper.
input-classdefault - string - Extra classes on the control itself (the textarea), the React className counterpart. The plain class attribute merges onto the .field wrapper instead.
monospacedefault false bool false Sets the monospace font on the control, for codes, logs and pasted data.
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

4 notes
  • The label is tied to the field with a for and id pair, and a generated id is used when none is given.
  • The field carries the native required attribute as well as the visible required mark.
  • aria-invalid is set from error, and aria-describedby points at the error text, or at the helper text when there is no error.
  • The info tip beside the label is named by helpLabel.

Do and avoid

3 pairs

Keep a visible label

Do
What the assessment covers.

A visible label stays put while the user types and is read by screen readers.

Avoid

A placeholder used as the label vanishes on the first keystroke and fails accessibility.

Match the height to the answer

Do

A height that matches the expected answer keeps the form compact and scannable.

Avoid

An oversized box wastes space and signals 'write an essay' when you wanted a sentence.

Say exactly what to change

Do
Add at least one sentence describing the work.

A specific error tells the user exactly what to change.

Avoid
Invalid

'Invalid' leaves them guessing what is actually wrong.