Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Selectable pill

Use a choice chip for a filter or tag the person switches on and off.

One toggleable chip
Show code
<app-choice-chip name="line" value="hv" label="High-voltage line" multiple="true" />

Several at once

Let several chips stay on together when the person may combine filters from one small set.

Filter chips (several active)
Show code
<app-choice-chip name="hazards" value="hv" label="HV power line" multiple="true" checked="true" />
<app-choice-chip name="hazards" value="lv" label="LV power line" multiple="true" />
<app-choice-chip name="hazards" value="tel" label="Telecom" multiple="true" />

One at a time

Use a group of chips where exactly one must stay selected, such as a reporting frequency.

Radio chips (one at a time)
Show code
<app-choice-chip name="frequency" value="daily" label="Daily" multiple="false" checked="true" />
<app-choice-chip name="frequency" value="weekly" label="Weekly" multiple="false" />
<app-choice-chip name="frequency" value="monthly" label="Monthly" multiple="false" />

Sizes and emphasis

Keep one size across a chip group, and use solid only for the one filter that is on.

Small, medium and large
Show code
<app-choice-chip name="sz" value="s" label="Small" size="Sm" />
<app-choice-chip name="sz" value="m" label="Medium" size="Md" />
<app-choice-chip name="sz" value="l" label="Large" size="Lg" />
Solid, checked, with a count
Show code
<app-choice-chip name="quick" value="mine" label="Assigned to me" count="4" checked="true" variant="Solid" size="Sm" />

Extra class names

Add a class to one chip for a screen's own hook. The chip keeps its base look.

className="analytics-chip": extra class alongside choice-chip
Show code
<app-choice-chip name="opt-class-ex" value="extra" label="Extra class" class="analytics-chip" />

Every option

Every value of every prop, one cell each.

checked

checked="false"
checked="true"

disabled

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

readOnly

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

loading

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

onChange

onChange (React only): fires on toggle; Razor posts name and value with the form

children

children (React only): the chip text between the tags; Razor uses label
long label: overflows the pill rather than wrapping the grid

label

label: the chip text, used in place of children

name

name="filter": chips with the same name form one group

value

value="hv": what the chip submits, no visible effect

multiple

multiple="true": checkbox (default)
multiple="false": radio

count

(no count)
count="12"
count="12" + checked (badge inverts)
count="0": falsy but defined, still renders

size

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

variant

variant="soft" (default)
variant="solid"

help

help: info-tip drawn beside the chip

help-label

help-label: aria-label of the info-tip, not visible

class

class="analytics-chip": extra class alongside choice-chip

unclaimed attrs

unclaimed attrs: data-* and aria-* land on the label, the element a consumer selects

Guidance

What to do, and what to avoid.

Use it when

  • A filter the user turns on and off, to narrow a list by tag, status or type.
  • Picking among a small set of options shown as pills, all visible at once.
  • Multi-select tags where several choices can be active together.

Reach for something else when

  • It triggers an action rather than holding a selection. → AppButton
  • It only displays or removes a chosen value (a token). → AppChip
  • You are picking one of many (6+) options. → AppSelect
  • Each option needs an icon, title, and description. → AppChoiceCard

A few short pills

Do

A few short, scannable pills; the user sees every option and toggles at a glance.

Avoid

A sentence crammed into a chip. Long labels belong in a select or a checkbox list.

Drive checked from state

Do

checked reflects real selection state that your onChange updates; a proper control.

Avoid

A chip used to fire an action. Actions are buttons; a chip should hold a choice.

Reference

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

sm md lg
soft solid
React, generated from the controls
<AppChoiceChip name="filter" value="hv" onChange={handleChange}>HV power line</AppChoiceChip>
Razor, the same props
<app-choice-chip name="filter" value="hv" label="HV power line" />

15 props. The 5 most used come first.

Used on most screens 5 props

PropTypeDefaultDescription
namedefault - string - Shared form name. Chips with the same name form one group.
valuedefault - string - The value this chip submits when selected.
labeldefault - string - The chip text. Keep it short and scannable.
checkeddefault false bool false Whether the chip is selected.
multipledefault true bool true Checkbox (multi-select) when true, radio when false.

Less common 10 props

PropTypeDefaultDescription
disableddefault false bool false The chip dims and cannot be picked.
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 content shown beside the chip.
help-labeldefault More information string More information aria-label for the info-tip button.
countdefault - string - A matching-row count, e.g. "Active 12". Inverts when the chip is selected. Rendered whenever set, so "0" still shows.
sizedefault md sm | md | lg md Pill size: padding, gap and font step together.
variantdefault soft soft | solid soft Checked look: a soft primary tint (soft) or a primary fill with a translucent count (solid).
classdefault - string - Extra classes on the chip's label element; merges with the base choice-chip class.
(unclaimed attrs)default - data-*, aria-*, … - Any other attribute lands on the <input>, not the <label>.

Screen reader

3 notes
  • The chip is a label around a native checkbox input, or a radio input when multiple is false, so keyboard and screen reader behaviour is the browser's.
  • Chips with the same name form one radio group when multiple is false.
  • The visible text comes from label, or from the children when label is not set; disabled sets the input disabled.

Do and avoid

2 pairs

A few short pills

Do

A few short, scannable pills; the user sees every option and toggles at a glance.

Avoid

A sentence crammed into a chip. Long labels belong in a select or a checkbox list.

Drive checked from state

Do

checked reflects real selection state that your onChange updates; a proper control.

Avoid

A chip used to fire an action. Actions are buttons; a chip should hold a choice.