On this page
@addTagHelper *, Webority.Ui.RazorAppIcon cards
Use icon cards to let a person compare a few options side by side and pick one.
Image cards
Use an image in place of the icon when the choice is visual, such as a colour or a plan.
Selected state
A checked card carries a tick and the selected treatment, so the chosen option reads at a glance.
Read-only answers
Show a submitted answer the person can see but not change, with the chosen card marked.
Custom body
Children replace the title and description with any markup, for a card that needs its own layout.
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 descriptioncheckIcon
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
A short title and a one-line description. The card reads instantly.
A paragraph stuffed into a card. If it needs this much text, it needs a different control.
One visual style per group
One visual style across the group: all icon cards, or all image cards.
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.
22 props. The 5 most used come first.
Used on most screens 5 props
| Prop | Type | Default | Description |
|---|---|---|---|
| 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
| Prop | Type | Default | Description |
|---|---|---|---|
| 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 pairsA short title and one line
A short title and a one-line description. The card reads instantly.
A paragraph stuffed into a card. If it needs this much text, it needs a different control.
One visual style per group
One visual style across the group: all icon cards, or all image cards.
Mixing an icon card with an image card in one group makes the set feel broken.