Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

AppIcon cards

Use icon cards to let a person compare a few options side by side and pick one.

A structure picker
Each card is a radio; selecting one clears the rest. Keep the group to a handful of options.
Show code
<app-choice-card name="struct" value="flat" checked="true" icon="building-2" title="Flat roof" description="Single-level rooftop" />
<app-choice-card name="struct" value="pitched" icon="house" title="Pitched roof" description="Sloped / gabled roof" />
<app-choice-card name="struct" value="tower" icon="factory" title="Tower" description="Tall vertical structure" />

Image cards

Use an image in place of the icon when the choice is visual, such as a colour or a plan.

Image-forward cards
image renders a media band above the title and description.
Show code
<app-choice-card name="swatch" value="blue" checked="true" image="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='320' height='180'%3E%3Crect width='100%25' height='100%25' fill='%232F50E4'/%3E%3C/svg%3E" title="Royal blue" description="Primary brand" />
<app-choice-card name="swatch" value="green" image="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='320' height='180'%3E%3Crect width='100%25' height='100%25' fill='%2304B440'/%3E%3C/svg%3E" title="Green" description="Success tone" />
<app-choice-card name="swatch" value="amber" image="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='320' height='180'%3E%3Crect width='100%25' height='100%25' fill='%23DFA000'/%3E%3C/svg%3E" title="Amber" description="Warning tone" />

Selected state

A checked card carries a tick and the selected treatment, so the chosen option reads at a glance.

One card selected
checked marks the active card; the shared name moves the selection.
Show code
<app-choice-card name="struct" value="pitched" checked="true" icon="house" title="Pitched roof" description="Sloped / gabled roof" />
single vs multi grouping
multiple makes each card a checkbox, so several can be on at once.
Show code
<app-choice-card name="struct-multi" multiple="true" value="flat" checked="true" icon="building-2" title="Flat roof" description="Single-level rooftop" />
<app-choice-card name="struct-multi" multiple="true" value="pitched" icon="house" title="Pitched roof" description="Sloped / gabled roof" />
<app-choice-card name="struct-multi" multiple="true" value="tower" checked="true" icon="factory" title="Tower" description="Tall vertical structure" />

Read-only answers

Show a submitted answer the person can see but not change, with the chosen card marked.

Read-only answers
Show code
<app-choice-card name="billing" value="monthly" checked="true" disabled="true" title="Monthly billing" />
<app-choice-card name="billing" value="yearly" disabled="true" title="Yearly billing" />

Custom body

Children replace the title and description with any markup, for a card that needs its own layout.

content mode: custom children
Children take the place of title and description, so the card shows the markup it is given.
Show code
<app-choice-card name="opt-content" value="children">
  <strong>Custom body</strong>
  <span>Any markup, not just title and description.</span>
</app-choice-card>

Every option

Every value of every prop, one cell each.

name

name="pg-group" (shared form name, no visible effect)

value

value="a" (posted on submit, no visible effect)

checked

checked="false" (default)
checked="true"

onChange

onChange (React callback, Razor posts the value on submit)

icon

icon="house"

iconNode

icon="stars" (Razor has no iconNode, icon takes the name)

iconSize

icon-size unset (default, follows the size)
icon-size="28"

image

image unset (default)
image: swatch image (blue)
image="green"
image="amber"

imageAlt

image-alt="Green swatch" (alt text for screen readers, not drawn)

title

title="Flat roof" (required, the card title)

description

description="Single-level rooftop" (secondary text under the title)

children

children: inner markup replaces title and description

checkIcon

check-icon="check" (default)
check-icon="check-circle"
check-icon="star"

checkSize

check-size="18" (default)
check-size="24"

hideCheck

hide-check="false" (default)
hide-check="true"

disabled

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

readOnly

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

loading

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

size

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

layout

layout="inline" (default)
layout="stacked"

selectedStyle

selected-style unset (default, soft selected look)
selected-style="filled"

help

help="Why this size?" (info tip after the text)

helpLabel

help-label="Explain the size" (aria-label of the info tip, not drawn)

className

class="pg-extra" (extra class on the element, no visible effect alone)

multiple

multiple="false" (default, radio group)
multiple="true" (checkbox group)

Guidance

What to do, and what to avoid.

Use it when

  • Picking one of a small set (2 to 5) of exclusive options, each worth an icon and a line of description.
  • A structure, plan, or type picker where seeing all options side by side helps the decision.
  • An onboarding or setup choice that benefits from richer visuals than a plain radio list.

Reach for something else when

  • There are many options (6+). → AppSelect
  • The options are plain and need no icon or description. → AppRadio
  • It is a compact filter or tag toggle. → AppChoiceChip
  • It just displays a chosen value. → AppChip

A short title and one line

Do

A short title and a one-line description. The card reads instantly.

Avoid

A paragraph stuffed into a card. If it needs this much text, it needs a different control.

One visual style per group

Do

One visual style across the group: all icon cards, or all image cards.

Avoid

Mixing an icon card with an image card in one group makes the set feel broken.

Reference

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

(none) blue green amber
md sm lg
inline stacked
unset filled
check check-check check-circle badge-check shield-check circle star heart
React, generated from the controls
<AppChoiceCard
  name="struct"
  value="flat"
  onChange={onChange}
  icon="building-2"
  title="Flat roof"
  description="Single-level rooftop"
/>
Razor, the same props
<app-choice-card name="struct" value="flat" icon="building-2" title="Flat roof" description="Single-level rooftop" />

22 props. The 5 most used come first.

Used on most screens 5 props

PropTypeDefaultDescription
namedefault - string - Shared form name. Cards with the same name form one group.
valuedefault - string - The value this card submits when selected.
checkeddefault false bool false Whether the card is selected.
multipledefault false bool false Render as a checkbox (multi-select) rather than a radio.
icondefault - string - Icon name. Renders linear, and switches to the solid (bold) style while the card is checked so the selected card reads at a glance.

Less common 17 props

PropTypeDefaultDescription
icon-sizedefault by size int by size Icon glyph size in px. Defaults to the card size: 16 (sm), 18 (md), 22 (lg).
imagedefault - string - Image URL. Renders an image-forward card (overrides icon).
image-altdefault '' string '' Alternative text for the image.
titledefault - string - The card title.
descriptiondefault - string - A one-line description under the title.
(content)default - markup - Inner markup for a fully custom body template. It overrides title/description.
check-icondefault check string check Icon name for the selected tick.
check-sizedefault 18 int 18 Tick icon size in px.
hide-checkdefault false bool false Render no selected tick. Selection then reads from the card's border and fill alone, and the card sheds the top and bottom room the tick needed.
disableddefault false bool false The card cannot change: no pointer, no hover, announced as disabled. A disabled parent fieldset does the same.
sizedefault md sm | md | lg md Card size: padding, gap, icon disc, type and the tick offset step together.
layoutdefault inline inline | stacked inline inline puts the icon beside the text; stacked puts the icon on its own line with the title and description below it.
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.
helpdefault - string - Info tip shown on the card.
help-labeldefault More information string More information aria-label for the info-tip button.
selected-styledefault unset filled unset filled fills the checked card's icon disc with the primary colour and draws the glyph in the on-primary colour. Unset keeps the soft selected look.

Screen reader

3 notes
  • The card is a label around a native radio input, or a checkbox input when multiple is set, so keyboard and screen reader behaviour is the browser's.
  • Cards with the same name form one radio group; disabled sets the input disabled and marks the card aria-disabled.
  • The image uses imageAlt as its alternative text, empty when it is not set.

Do and avoid

2 pairs

A short title and one line

Do

A short title and a one-line description. The card reads instantly.

Avoid

A paragraph stuffed into a card. If it needs this much text, it needs a different control.

One visual style per group

Do

One visual style across the group: all icon cards, or all image cards.

Avoid

Mixing an icon card with an image card in one group makes the set feel broken.