Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Effects

Pick a wipe that suits the page's motion; the switch changes instantly when motion is reduced.

Six effects, one toggle each
effect=wave
effect=circle
effect=slide
effect=blinds
effect=fade
effect=none
Show code
<app-theme-toggle effect="Wave" storage-key="sc-theme" label="Theme (wave)" />
<app-theme-toggle effect="Circle" storage-key="sc-theme" label="Theme (circle)" />
<app-theme-toggle effect="Slide" storage-key="sc-theme" label="Theme (slide)" />
<app-theme-toggle effect="Blinds" storage-key="sc-theme" label="Theme (blinds)" />
<app-theme-toggle effect="Fade" storage-key="sc-theme" label="Theme (fade)" />
<app-theme-toggle effect="None" storage-key="sc-theme" label="Theme (none)" />

Variants

The icon disc suits a toolbar; the segmented variant suits a settings page, where all three modes show at once.

Segmented strip
Show code
<app-theme-toggle variant="Segmented" storage-key="sc-theme" />
Own option labels
Show code
<app-theme-toggle variant="Segmented" effect="Circle" light-label="Day" dark-label="Night" storage-key="sc-theme" />

Modes

Leave out auto when a page must always show light or dark; on a light machine auto looks like no change.

Without auto
Show code
<app-theme-toggle include-auto="false" storage-key="sc-theme" />

Setup

Paste the boot script into the head of every page, the sign-in page included, so the stored theme paints first.

Pre-paint script

Both sandboxes carry this script; the page you are reading loaded straight into its stored theme.

Show code
<head>
  <app-theme-script storage-key="theme" />
  <link rel="stylesheet" href="~/_content/Webority.Ui.Razor/css/webority-theme.css" />
</head>

Every option

Every value of every prop, one cell each.

variant

variant="icon" (default)
variant="segmented"

effect

effect="wave" (default)
effect="circle"
effect="slide"
effect="blinds"
effect="fade"
effect="none"

includeAuto

include-auto="true" (default)
include-auto="false"

storageKey

storage-key="sc-theme"

duration

duration="1500"

label

label="Pick a look"

lightLabel

light-label="Day"

darkLabel

dark-label="Night"

autoLabel

auto-label="Device"

name

name="theme-mode"

size

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

tooltipPlacement

tooltip-placement="auto" (default)
tooltip-placement="top"
tooltip-placement="bottom"
tooltip-placement="start"
tooltip-placement="end"

onChange

onChange: the React callback; Razor listens for the wui:theme:change event on document

className

class: extra classes on the disc

Guidance

What to do, and what to avoid.

Use it when

  • One disc in the app chrome (the topbar, the sidebar foot) that switches the whole product
  • A settings row that offers System, Light and Dark (variant="segmented")

Reach for something else when

  • A per-section or per-card theme: the switch is page-wide by design
  • Branding colour choices: that is a theme variable, not a mode

Reference

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

icon segmented
wave circle slide blinds fade none
true false
sm md lg xl
auto top bottom start end
React, generated from the controls
<AppThemeToggle storageKey="sc-theme" onChange={fn} />
Razor, the same props
<app-theme-toggle storage-key="sc-theme" />

13 props. The 5 most used come first.

Used on most screens 5 props

PropTypeDefaultDescription
variantdefault icon icon | segmented icon One cycling disc, or one option per mode.
effectdefault wave wave | circle | slide | blinds | fade | none wave The page-wide effect that plays when the theme changes.
include-autodefault true bool true Offers the system-following mode beside light and dark. Off, the toggle offers only light and dark.
labeldefault Theme string Theme The accessible name: the disc's tooltip, or the segmented group's name.
sizedefault md sm | md | lg | xl md The disc's glyph size (16, 20, 24 or 28 px) or the segmented strip's size; xl draws the lg strip.

Less common 8 props

PropTypeDefaultDescription
storage-keydefault theme string theme The localStorage key the choice is kept under.
durationdefault - int - The effect length in milliseconds. Each effect has its own default.
light-labeldefault Light string Light The segmented variant's option text for light.
dark-labeldefault Dark string Dark The segmented variant's option text for dark.
auto-labeldefault System string System The segmented variant's option text for the system-following mode.
namedefault - string - The segmented variant's field name, which groups its radios. A generated name is used when this is unset.
tooltip-placementdefault auto auto | top | bottom | start | end auto The disc's preferred tooltip side.
classdefault - string - Extra classes on the disc.

Screen reader

3 notes
  • The disc is an icon button named by the label and the current mode, such as "Theme: dark".
  • The segmented variant is one radio option per mode inside a group named by the label.
  • Without the View Transitions API, under reduced motion, or when the page already shows the requested theme, the switch is instant.