Skip to main content Home About the Design SystemRoadmap OverviewDesignersDevelopers OverviewColorGridIconographyInteractionsSpacingTypography Overview Global colorBox shadowTypographyBorderOpacitySpaceLengthIconBreakpointsMedia queries All elements Accordion Alert Announcement Audio player Avatar Back to top Badge Blockquote Breadcrumb Button group Button Card Chip Code block Call to action Dialog Disclosure Footer Health index Icon Jump links Menu dropdown Navigation link Navigation (primary) Navigation (secondary) Navigation (vertical) Pagination PopoverPlanned Progress stepper Readtime Scheme toggle Select Site status Skeleton Skip link Spinner Statistic Subnavigation Surface Switch Table Tabs Tag Tile Timestamp Tooltip Video embed OverviewColor PalettesCustomizingDevelopers All PatternsAccordionAlertCall to ActionCardFilterFormLink with iconLogo wallSearch barSticky bannerSticky cardTabsTagTile All Personalization PatternsAnnouncement FundamentalsAccessibility toolsAssistive technologiesCI/CDContentContributorsDesignDevelopmentManual testingResourcesScreen readers Design/code status Release notes Get support

Scheme toggle Since v3.1.0

OverviewStyleGuidelinesCodeAccessibilityDemos
ImportingUsagerh-scheme-toggleImportingUsagerh-scheme-toggle

Importing

Add rh-scheme-toggle to your page with this import statement:

<script type="module">
  import '@rhds/elements/rh-scheme-toggle/rh-scheme-toggle.js';
</script>
Copy to Clipboard Wrap lines

To learn more about installing RHDS elements on your site using an import map read our getting started docs.

Usage 

<rh-scheme-toggle></rh-scheme-toggle>

<script type="module">
  import '@rhds/elements/rh-scheme-toggle/rh-scheme-toggle.js';
</script>

<style>
  body {
    color-scheme: light dark;
    background-color: light-dark(var(--rh-color-surface-lightest, #ffffff),
        var(--rh-color-surface-darkest, #151515));
    color: light-dark(var(--rh-color-text-primary-default-on-light, #151515),
        var(--rh-color-text-primary-default-on-dark, #ffffff));
  }

  rh-scheme-toggle {
    margin-block-start: var(--rh-space-md, 8px);
  }
</style>
Copy to Clipboard Wrap lines

rh-scheme-toggle

A scheme toggle provides users with the ability to switch between light, dark, and system default color schemes. It should be placed in a visible location for easy access. For WCAG compliance, screen reader users must be able to identify each option; the component uses a native fieldset with ARIA-compatible radio buttons. Tab focuses the group; arrow keys allow selection between schemes.

Slots 0

None

Attributes 5

Attribute DOM Property Description Type Default
scheme scheme

Current color scheme setting. Reflects to the scheme attribute and initializes from localStorage.rhdsColorScheme when available. When set, applies the value to document.body.style.colorScheme and persists it to localStorage.

 
'light' | 'dark' | 'light dark'
 
globalThis.localStorage\n ?.rhdsColorScheme as Scheme
legend-text legendText

Legend text displayed next to the toggle button group. Authors should keep this text short (under 20 characters).

 
string
 
'Color scheme'
light-text lightText

Accessible label for the light mode radio button. Rendered as a visually-hidden span and a title tooltip.

 
string
 
'Light'
dark-text darkText

Accessible label for the dark mode radio button. Rendered as a visually-hidden span and a title tooltip.

 
string
 
'Dark'
system-text systemText

Accessible label for the system default radio button. Rendered as a visually-hidden span and a title tooltip.

 
string
 
'System'

Methods 0

None

Events 0

None

CSS Shadow Parts 0

None

CSS Custom Properties 0

None

Design Tokens 14

Token Description Copy
--rh-space-lg

Fieldset legend-to-group gap

16px spacer
--rh-size-icon-01

16px icon box
--rh-border-width-sm

Toggle button border width

Applies a 1px border width to at least 1 side of a container. This shall be the default width for all borders and lines. It should be used to establish baseline thickness or visual separation with a container or thin line. It must not be used for strong directional emphasis like indicating a selected state. Recommended for elements like Button, Card, or Field. Applying to all 4 sides at once is optional.
--rh-color-border-subtle

Toggle button border color
--rh-space-2xl

Toggle button height

32px spacer
--rh-space-3xl

Toggle button width

48px spacer
--rh-border-radius-default

Button group start-start corner radius

Button group end-start corner radius

Button group start-end corner radius

Button group end-end corner radius

Applies a 3px border radius to at least 1 corner of a container. This shall be the default for all containers needing rounded corners. It should be used to soften a container's visual footprint. Recommended for elements with subtle rounded corners like Button, Card, or Dialog. It must be applied to all 4 corners of a container at once.
--rh-color-surface-light

Secondary surface (light theme)
--rh-color-surface-dark

Tertiary surface (dark theme)
--rh-color-interactive-primary-default

Selected toggle button background
--rh-color-text-primary-on-dark

Selected toggle button icon color in light mode

Primary text color for dark theme
--rh-color-text-primary-on-light

Selected toggle button icon color in dark mode

Primary text color for light theme
--rh-border-width-lg

Focus outline width

Applies a 3px border width to 1 side of a container. It should be used for strong directional emphasis like indicating a current page, expanded, or selected state. Recommended for elements needing heavy visual weight like Accordion, Navigation, or Tabs. It must also be used for the focus indicator border per WCAG. Except for the focus indicator, it should not be applied to all 4 sides at once.
--rh-color-border-interactive

Selected toggle button border color

Focus outline color
Edit this page on GitHub
© 2026 Red Hat Deploys by Netlify