Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Options

Use a segmented control for two to four exclusive choices that all need to stay visible.

A range toggle
Three options is the comfortable case; four is the practical ceiling.
Show code
<app-segmented label="Date range" name="range" value="30d">
    <app-segmented-option value="7d" label="7 days" />
    <app-segmented-option value="30d" label="30 days" />
    <app-segmented-option value="90d" label="90 days" />
</app-segmented>
The theme switch
The canonical use. Keep the text label: an icon-only segmented control forces the reader to guess.
Show code
<app-segmented label="Theme" name="theme" value="dark">
    <app-segmented-option value="light" label="Light" icon="sun" />
    <app-segmented-option value="dark" label="Dark" icon="moon" />
    <app-segmented-option value="system" label="System" icon="gauge" />
</app-segmented>

Labels and counts

Add a note, a visible label or a count when the reader needs more than the option name.

A sub-label per option
note renders under label, not instead of it. Keep the label itself short.
Show code
<app-segmented label="Date range" name="range-notes" value="30d">
    <app-segmented-option value="7d" label="7 days" note="Last week" />
    <app-segmented-option value="30d" label="30 days" note="Last month" />
    <app-segmented-option value="90d" label="90 days" note="Last quarter" />
</app-segmented>
A labelled range toggle
Use it in a form, where the control needs the same label as the fields beside it.
Show code
<app-segmented label="Date range" label-visible="true">
  <app-segmented-option value="7d" label="7 days" />
  <app-segmented-option value="30d" label="30 days" />
  <app-segmented-option value="90d" label="90 days" />
</app-segmented>
A count on each option
Keep counts to plain numbers. The label stays the option's name; the count is a supporting figure beside it.
Show code
<app-segmented label="Status" name="status-counts" value="open">
    <app-segmented-option value="open" label="Open" count="12" />
    <app-segmented-option value="review" label="In review" count="3" />
    <app-segmented-option value="done" label="Done" count="0" />
</app-segmented>

Sizes and width

Match the control's height to the fields beside it, and let segments fill a card when it should span.

Small, medium and large
Show code
<app-segmented size="Sm" label="Date range" name="range" value="30d">…</app-segmented>
<app-segmented label="Date range" name="range" value="30d">…</app-segmented>
<app-segmented size="Lg" label="Date range" name="range" value="30d">…</app-segmented>
Segments fill the row
Show code
<app-segmented full-width="true" label="View" name="view" value="list">…</app-segmented>
Flat thumb
Show code
<app-segmented bordered="false" label="Range" name="range" value="30d">…</app-segmented>

Disabled

Disable the whole group while a value is locked, or one option that is not yet available.

Whole control and a single option
Show code
<app-segmented disabled="true" label="View" name="view" value="7d">…</app-segmented>
<app-segmented-option value="map" label="Map" disabled="true" />

Every option

Every value of every prop, one cell each.

options: icon, note, count, disabled and edge cases

app-segmented-option icon: a glyph beside the label
app-segmented-option note: a line under the label
app-segmented-option count: a count beside the label
app-segmented-option disabled="true": one option kept visible, not pickable
options: minimum (2)
no app-segmented-option children: empty group

value: each option, and one that matches none

value="7d"
value="30d"
value="90d"
value="unknown": matches no option, so nothing is checked

onChange: called with the picked value

onChange: React only, a Razor form posts the picked value on submit

label: the accessible name

label="Date range": the accessible name, not shown

name: the field name

name="range": groups the radios and posts with a form

size: sm, md, lg

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

fullWidth: segments share the row

full-width="false" (default)
full-width="true"

bordered: the edge and shadow of the thumb

bordered="true" (default)
bordered="false"

disabled: the whole group

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

labelVisible: the label above the control

label-visible="false" (default)
label-visible="true"

readOnly: shows the value, blocks editing

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

loading: busy state

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

defaultValue: the starting value

defaultValue: React only, Razor leaves value out so nothing is checked

help: info-tip beside the visible label

help="Shows the last 7, 30 or 90 days.": info-tip beside the visible label

helpLabel: aria-label of the info-tip

help-label="Explain the range": aria-label of the info-tip

className: extra class names

class: extra class names on the group, none set here

Guidance

What to do, and what to avoid.

Use it when

  • Two to four exclusive options, and seeing all of them helps the reader choose.
  • The choice changes a view immediately, such as a range, a mode or a theme.
  • The options are short words that fit on one row.

Reach for something else when

  • There are five or more options. → AppSelect
  • It is a single on/off setting. → AppSwitch
  • Options are not exclusive: several can be on. AppChoiceChip also fits a filter that can be off. → AppCheckbox
  • The options need descriptions to choose between. AppChoiceCard also fits. → AppRadio

Short, parallel labels

Do

Short, parallel labels of similar length, so the pills are balanced and the row reads as one control.

Avoid

Wildly uneven labels make one pill swamp the other and push the control past its container. If a label needs a sentence, the choice needs radios.

Reference

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

range theme notes withdisabled counts
sm md lg
true false
7d 30d 90d
React, generated from the controls
<AppSegmented
  label="Preview"
  name="demo"
  options={[
    { value: '7d', label: '7 days' },
    { value: '30d', label: '30 days' },
    { value: '90d', label: '90 days' },
  ]}
  value={value}
  onChange={setValue}
/>
Razor, the same props
<app-segmented label="Preview" name="demo" value="7d">
    <app-segmented-option value="7d" label="7 days" />
    <app-segmented-option value="30d" label="30 days" />
    <app-segmented-option value="90d" label="90 days" />
</app-segmented>

12 props. The 4 most used come first.

Used on most screens 4 props

PropTypeDefaultDescription
labeldefault - string - The accessible name of the group.
valuedefault - string - The selected option's value. Leave it out, with defaultValue, for an uncontrolled field.
namedefault generated string generated The field name, which groups the radios and is what a form posts. Defaults to a generated one.
sizedefault md sm | md | lg md Heights 32, 36 and 44px.

Less common 8 props

PropTypeDefaultDescription
full-widthdefault false bool false Segments share the row equally, filling the container.
bordereddefault true bool true Draws the edge and soft shadow of the selected thumb. false keeps a flat thumb.
disableddefault false bool false Disables the whole control.
label-visibledefault false bool false Shows the label above the control. The accessible name stays either way.
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 text beside the visible label. Shows only with label-visible.
help-labeldefault More information string More information aria-label for the info-tip button.

Screen reader

3 notes
  • The group is a radiogroup named by label, built from native radio inputs inside labels, so arrow keys, the single tab stop and the position announcement come from the browser.
  • disabled on the group sets aria-disabled and disables every radio; an option's own disabled disables that radio.
  • The sliding thumb is aria-hidden, and with labelVisible the visible label is aria-hidden because the group's aria-label already names it.

Do and avoid

1 pairs

Short, parallel labels

Do

Short, parallel labels of similar length, so the pills are balanced and the row reads as one control.

Avoid

Wildly uneven labels make one pill swamp the other and push the control past its container. If a label needs a sentence, the choice needs radios.