Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Tones

Pick the tone by what the message means: info for notices, success for confirmations, danger for errors.

The five tones
Show code
<app-alert tone="Info">Reports use the latest IEC 62305-2 methodology.</app-alert>
<app-alert tone="Success">Invite sent. The user will appear once they accept.</app-alert>
<app-alert tone="Warning">Your trial ends in 3 days. Upgrade to keep full access.</app-alert>
<app-alert tone="Danger">Something went wrong while saving. Please try again.</app-alert>
<app-alert tone="Neutral">Reports are generated on the first working day of each month.</app-alert>

In context

Place a danger alert above the fields when a form fails, saying what failed and what to do next.

A form-level error
Enter a work email address.
Show code
<app-alert tone="Danger">We couldn't save your changes. Check the highlighted fields and try again.</app-alert>
<app-input label="Work email" error="Enter a work email address."></app-input>

Heading and icon

Give the alert a title line for a headline, and an icon to reinforce the tone at a glance.

A titled, iconed alert
Show code
<app-alert tone="Danger" icon="alert-circle" title="Payment failed">Your card was declined. Update your billing details and try again.</app-alert>
<app-alert tone="Success" icon="check-circle" title="All set">Your workspace is ready. Invite your team to get started.</app-alert>

Custom image

Show a product logo or brand mark in the badge instead of the tone's glyph.

A logo in the badge
Show code
<app-alert tone="Info" title="Acme" image="/brand/acme.png" image-alt="Acme">Your Acme advisor has the full terms if you need them.</app-alert>
<app-alert tone="Success" image="/brand/acme.png" image-alt="Acme">Invite sent. The user will appear once they accept.</app-alert>

Dismissible

Use a close button only for a notice the reader can acknowledge once, never for an error that must stay.

A dismissible notice
Show code
<app-alert tone="Info" dismissible="true">Reports use the latest IEC 62305-2 methodology.</app-alert>

Borderless

Drop the soft ring when the alert sits inside a bordered card or a dense layout.

Without the border
Show code
<app-alert tone="Info">Bordered (default): soft ring.</app-alert>
<app-alert tone="Info" bordered="false">Borderless: tint fill only.</app-alert>
<app-alert tone="Danger" bordered="false" title="Payment failed">Update your billing details and try again.</app-alert>

Explanatory asides

Explain how a figure is worked out with a quiet aside that screen readers do not interrupt.

An aside with a trailing action
How this is worked out
Reports use the latest IEC 62305-2 methodology.
Your plan renews on 1 Sep.
Two documents are still missing.
Show code
<app-alert tone="Info" accent="true" role="None" title="How this is worked out">Reports use the latest <strong>IEC 62305-2</strong> methodology.</app-alert>
<app-alert tone="Info" accent="true" role="None"><app-alert-action><app-button size="WideSize.Sm" variant="Soft">Renew</app-button></app-alert-action>Your plan renews on 1 Sep.</app-alert>
<app-alert tone="Warning" size="Sm" role="Status">Two documents are still missing.</app-alert>

Long text

A long message wraps onto as many lines as it needs, inside the alert.

Long body wraps within the alert, no overflow
Show code
<app-alert tone="Info" title="Heads up">This is a considerably longer alert body meant to show how the component wraps multi-line content without breaking layout, overflowing its container, or truncating the message the user needs to read in full.</app-alert>

Every option

Every value of every prop, one cell each.

tone: all five

tone="info" (default)
tone="success"
tone="warning"
tone="danger"
tone="neutral"

title & icon

(default): no title, the tone's glyph
title only
icon only
title + icon
icon="none": no badge
icon: a node icon is React-only; Razor takes a library icon name

icon-variant: the six iconsax styles

icon-variant="linear" (default)
icon-variant="outline"
icon-variant="bold"
icon-variant="bulk"
icon-variant="broken"
icon-variant="twotone"

icon-size: the badge glyph in px

(default) follows size
icon-size="16"
icon-size="28"

image, image-alt and image-size

(default): no picture, the tone's glyph
image="url": a picture fills the badge
image-alt="Acme": alt text, read aloud, not shown
image-size="48": the picture badge in px

dismissible and onClose

(default): not dismissible
dismissible="true": the × shows and closes the alert on click
onClose: React only, a callback run on the × click
dismissible="false": suppresses the button
dismissible + icon + title

bordered

bordered (default): the soft ring of the tone
bordered="false": tint fill only

accent

(default): no left edge
accent="true": a thick left edge in the tone colour

size

size="sm": a compact single line
size="md" (default)
size="lg": roomier heading, body and badge

action

<app-alert-action>: a trailing action pinned right

role

(default) role="alert"
role="status"
A non-assertive notice.
role="none": explanatory content, not announced
Ordinary page content.

className

className: React only; Razor takes a plain class attribute

content: long text, no width cap

long body: wraps within the alert, no overflow

Guidance

What to do, and what to avoid.

Use it when

  • A message needs to persist on the page while its cause is true: a form error, a trial warning.
  • You are stating status inline, in context, next to the thing it concerns.
  • The user should be able to re-read it. It is not a fleeting confirmation.
  • You are explaining how something works, as page content (accent with role "none").

Reach for something else when

  • The feedback is brief and self-dismissing, such as "Saved" or "Copied". → toast
  • It is a small count or a one-word label. → AppBadge
  • It maps a status enum to a coloured pill. → AppStatusBadge
  • It is a help hint tied to a single field label. → AppInfoTip

Match the tone to the message

Do

Match the tone to intent and say what to do next. A danger alert names the problem and the recovery.

Avoid

A success (green) tone on an error message contradicts the words. The colour lies about what happened.

Use info for a neutral notice

Do

A neutral, informational notice uses the info tone: calm, not alarming.

Avoid

A warning (amber) tone on a purely informational message implies a problem that is not there.

Reference

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

info success warning danger neutral
(none) alert-triangle alert-circle check-circle info-circle
linear outline bold bulk broken twotone
alert status none
true false
md sm lg
React, generated from the controls
<AppAlert onClose={onClose}>Something happened.</AppAlert>
Razor, the same props
<app-alert>Something happened.</app-alert>

15 props. The 5 most used come first.

Used on most screens 5 props

PropTypeDefaultDescription
tonedefault info info | success | warning | danger | neutral info The status tone. Neutral is a plain notice in ink on a grey surface, with no semantic colour.
titledefault - string - A bold heading line above the body.
icondefault - string - A leading glyph, given as a semantic icon name. It defaults to the glyph of the tone; pass null for no badge.
dismissibledefault false bool false Shows the close button. It is on by default when a close handler is set.
sizedefault md sm | md | lg md Sm is a compact single line. Lg is roomier, with a larger heading, body and badge.

Less common 10 props

PropTypeDefaultDescription
(content)default - string - The alert message (inner content).
icon-variantdefault linear linear | outline | bold | bulk | broken | twotone linear The iconsax style of a named icon. It does not change an image.
icon-sizedefault - int - The badge glyph's width and height in px. Unset, it follows size.
imagedefault - string - A custom image URL shown in the badge instead of the icon glyph.
image-altdefault '' string '' Alt text for the custom image.
image-sizedefault - int - Width and height of the image badge in px. Unset, it follows size.
roledefault alert alert | status | none alert Status is for notices that must not interrupt a screen reader. None is for explanatory page content.
bordereddefault true bool true Draws the soft border of the tone. False keeps only the tint fill.
accentdefault false bool false A thick left edge in the tone colour, marking the alert as an aside.
<app-alert-action>default - child - A trailing action pinned to the right, usually an <app-button>. It drops below the text on phones.

Screen reader

3 notes
  • The alert role is set by default, so assistive technology announces the alert as it appears; pass status for a notice that must not interrupt.
  • Role none removes the role, so an explanatory note reads as ordinary page content.
  • A custom image takes its alt text from imageAlt, which is empty by default.

Do and avoid

2 pairs

Match the tone to the message

Do

Match the tone to intent and say what to do next. A danger alert names the problem and the recovery.

Avoid

A success (green) tone on an error message contradicts the words. The colour lies about what happened.

Use info for a neutral notice

Do

A neutral, informational notice uses the info tone: calm, not alarming.

Avoid

A warning (amber) tone on a purely informational message implies a problem that is not there.