On this page
@addTagHelper *, Webority.Ui.RazorEffects
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
Variants
The icon disc suits a toolbar; the segmented variant suits a settings page, where all three modes show at once.
Segmented strip
Own option labels
Modes
Leave out auto when a page must always show light or dark; on a light machine auto looks like no change.
Without auto
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.
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 documentclassName
class: extra classes on the discGuidance
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.
13 props. The 5 most used come first.
Used on most screens 5 props
| Prop | Type | Default | Description |
|---|---|---|---|
| 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
| Prop | Type | Default | Description |
|---|---|---|---|
| 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.