Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Basic

Use a labelled rich text editor for formatted copy such as articles and product descriptions.

A labelled editor
Show code
<app-rich-text label="Notes" name="notes" placeholder="Write something…"></app-rich-text>

HTML or Markdown

Choose the value format: HTML by default, or Markdown for products that store Markdown text.

Markdown editor
The same toolbar; the value is Markdown text.
Show code
<app-rich-text label="Release notes" name="release-notes" format="AppRichTextFormat.Markdown" value="@Model.ReleaseNotes"></app-rich-text>

Always clean

Only a fixed set of allowed content reaches the form, so seeded or pasted markup stays out.

Seeded markup, cleaned
The script, the inline style, the class and the fourth-level heading cannot survive; their text does. Still sanitise on the server: the browser is not a trust boundary, so your server decides what it accepts.
Show code
<app-rich-text label="Description" name="description" value="@Model.Description"></app-rich-text>

Validation

Give helper text for guidance and an error when validation fails; an empty editor posts an empty string.

Helper text and error
Error always wins over helper text: they share the same slot below the field, so setting both shows only the error.
Shown on the quote.
Description is required.
Show code
<app-rich-text label="Terms" name="terms" helper-text="Shown on the quote."></app-rich-text>
<app-rich-text label="Description" name="description" required="true" error="Description is required."></app-rich-text>

Every option

Every value of every prop, one cell each.

asp-for (Razor only)

asp-for: binds a model property (name, id, value, label and validation)

value

value, empty
value, a short note with markup

onChange

onChange (React): every edit is posted with the form

format

html (default)
markdown

name

name: posted under this name with a form

id

id: the editor id; the helper text and error ids derive from it

label

label: the visible label; it also names the editor for screen readers

placeholder

placeholder

defaultValue

value: the starting value, Razor's form of defaultValue

state

(default)
required
disabled
read-only
loading
error
Notes are required.
helper-text
Shown on the invoice.
error + helper-text (error wins)
Shown on the invoice.
Notes are required.

help, helpLabel and ariaLabel

help="…" with the default help-label
help with a custom help-label
(no label) with aria-label

className

input-class: a class on the editor element (React className)

fieldClassName

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

Guidance

What to do, and what to avoid.

Use it when

  • People need bold, links, lists or headings in a note, description or message, and the product stores or shows that formatting.
  • The value is rendered somewhere later as HTML or Markdown, and you want it clean on the way in.

Reach for something else when

  • The value is plain text that may run past a line. → AppTextarea
  • The value is a single short line. → AppInput
  • The user picks tags or keywords. → AppSelect mode="tag"

Keep a visible label

Do
Shown on the quote.

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.

Reference

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

html markdown
React, generated from the controls
<AppRichText label="Notes" name="pg-richtext" placeholder="Write something…" value={value} onChange={setValue} />
Razor, the same props
<app-rich-text label="Notes" name="pg-richtext" placeholder="Write something…"></app-rich-text>

17 props. The 5 most used come first.

Used on most screens 5 props

PropTypeDefaultDescription
valuedefault - string - The content, in format.
formatdefault html html | markdown html What the value is. HTML is used when it is left out. It is read when the editor mounts, so changing it remounts the editor.
placeholderdefault - string - Shown while the editor is empty.
namedefault - string - Posted under this name with a form.
labeldefault - string - The field label. Always set one, or pass aria-label.

Less common 12 props

PropTypeDefaultDescription
asp-fordefault - string - The model property to bind to: supplies name, id, value, label, required and validation.
requireddefault false bool false Marks the field required; an empty editor is invalid.
disableddefault false bool false Locks the editor and keeps it out of the form post.
read-onlydefault false bool false Locks the editor; the value still posts.
loadingdefault false bool false Shows a busy state and blocks input while data loads.
errordefault - string - Message below the editor. It replaces the helper text.
helper-textdefault - string - Helper text below the editor.
helpdefault - string - Info-tip content shown beside the label.
help-labeldefault More information string More information Accessible name for that info tip.
iddefault - string - The id of the editor; the helper text and error ids derive from it. Generated when omitted.
classdefault - string - Extra classes on the .field wrapper.
input-classdefault - string - Extra classes on the editor element itself.

Screen reader

3 notes
  • The editor is a group named by ariaLabel, or by the label when it is a string.
  • The label is tied to the editor by id. Helper text or an error is linked through aria-describedby, and an error also sets aria-invalid.
  • Required, disabled and read-only are passed to the editor as attributes, and a failed editor load shows a status message.

Do and avoid

1 pairs

Keep a visible label

Do
Shown on the quote.

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.