On this page
@addTagHelper *, Webority.Ui.RazorSelectable pill
Use a choice chip for a filter or tag the person switches on and off.
Several at once
Let several chips stay on together when the person may combine filters from one small set.
One at a time
Use a group of chips where exactly one must stay selected, such as a reporting frequency.
Sizes and emphasis
Keep one size across a chip group, and use solid only for the one filter that is on.
Extra class names
Add a class to one chip for a screen's own hook. The chip keeps its base look.
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 formchildren
children (React only): the chip text between the tags; Razor uses labellong label: overflows the pill rather than wrapping the gridlabel
label: the chip text, used in place of childrenname
name="filter": chips with the same name form one groupvalue
value="hv": what the chip submits, no visible effectmultiple
multiple="true": checkbox (default)multiple="false": radiocount
(no count)count="12"count="12" + checked (badge inverts)count="0": falsy but defined, still renderssize
size="sm"size="md" (default)size="lg"variant
variant="soft" (default)variant="solid"help
help: info-tip drawn beside the chiphelp-label
help-label: aria-label of the info-tip, not visibleclass
class="analytics-chip": extra class alongside choice-chipunclaimed attrs
unclaimed attrs: data-* and aria-* land on the label, the element a consumer selectsGuidance
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
A few short, scannable pills; the user sees every option and toggles at a glance.
A sentence crammed into a chip. Long labels belong in a select or a checkbox list.
Drive checked from state
checked reflects real selection state that your onChange updates; a proper control.
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.
15 props. The 5 most used come first.
Used on most screens 5 props
| Prop | Type | Default | Description |
|---|---|---|---|
| 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
| Prop | Type | Default | Description |
|---|---|---|---|
| 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 pairsA few short pills
A few short, scannable pills; the user sees every option and toggles at a glance.
A sentence crammed into a chip. Long labels belong in a select or a checkbox list.
Drive checked from state
checked reflects real selection state that your onChange updates; a proper control.
A chip used to fire an action. Actions are buttons; a chip should hold a choice.