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

Switch Since v2.0.0

OverviewStyleGuidelinesCodeAccessibilityDemos
ImportingUsagerh-switchImportingUsagerh-switch

Importing

Add rh-switch to your page with this import statement:

<script type="module">
  import '@rhds/elements/rh-switch/rh-switch.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-switch id="switch-a" accessible-label="Switch A" message-on="Message when on" message-off="Message when off" checked=""></rh-switch>

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

<style>
  rh-switch {
    margin: var(--rh-space-lg);
  }
</style>
Copy to Clipboard Wrap lines

rh-switch

A switch provides a visible toggle for a setting. Authors must supply an accessible label via accessible-label or a <label for>. The element uses ARIA role="switch" with aria-checked for screen readers. Users should toggle with Space or Enter keys. Avoid using a switch when multiple selections are needed; use checkboxes instead.

Theming

Themable

This element uses Red Hat design system theming and can be used in themable contexts.

Slots 2

Slot Name Summary Description
message-on

Message content when checked. Overrides the message-on attribute.

Accepts inline content such as <span> elements. Content is exposed to screen readers via aria-describedby, so it should be concise and meaningful.
message-off

Message content when unchecked. Overrides the message-off attribute.

Accepts inline content such as <span> elements. Content is exposed to screen readers via aria-describedby, so it should be concise and meaningful.

Attributes 7

Attribute DOM Property Description Type Default
accessible-label accessibleLabel

invisible, accessible label for screen readers

 
string
 
unknown
message-on messageOn

Message to display when the switch is on (i.e. checked)

 
string
 
unknown
message-off messageOff

Message to display when the switch is off (i.e. unchecked)

 
string
 
unknown
show-check-icon showCheckIcon

If the checkmark icon should be displayed when the switch is on

 
boolean
 
false
checked checked

Whether the switch is on (checked)

 
boolean
 
false
disabled disabled

If the switch is disabled

 
boolean
 
false
reversed reversed

If the switch is reversed: message first, then control

 
boolean
 
false

Methods 0

None

Events 1

Event Name Description
change

Fires when the user toggles the switch on or off via click, Space, or Enter. Does not fire when disabled. The event bubbles and carries no detail; read the checked property on the target element to determine the new state.

CSS Shadow Parts 2

Part Name Summary Description
container

The outer flex container for the switch and message slots
switch

The toggle track and handle

CSS Custom Properties 3

CSS Property Description Default
--rh-switch-unchecked

Unchecked track color in light mode

Unchecked track color in dark mode

 var(--rh-color-gray-40, #a3a3a3)
--rh-switch-checked light-dark( /** Checked track color in light mode */ var(--rh-color-accent-base-on-light, #0066cc), /** Checked track color in dark mode */ var(--rh-color-accent-base-on-dark, #92c5f9) )
--rh-switch-disabled

Disabled track color in light mode

Disabled track color in dark mode

 var(--rh-color-gray-60, #4d4d4d)

Design Tokens 16

Token Description Copy
--rh-space-lg

Gap between track and message

16px spacer
--rh-color-surface-lightest

Handle color in light mode

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

Tertiary surface (dark theme)
--rh-box-shadow-sm

Handle shadow in dark mode

Small box shadow
--rh-border-radius-pill

Track border radius

Handle border radius

Applies a 64px border radius to at least 1 corner of a container. It should be used for elements needing a circle or pill-shaped background like Avatar, Badge, or Switch. It may also be used for Hybrid style branding. Applying to all 4 corners at once is optional. It may replace the default 3px radius when not all corners need the same value.
--rh-color-text-secondary

Unchecked message text color
--rh-color-accent-base-on-light

Checked track color in light mode

Inline link (light theme)
--rh-color-accent-base-on-dark

Checked track color in dark mode

Inline link (dark theme)
--rh-color-text-primary

Checked message text color
--rh-border-width-md

Focus ring outline width

Applies a 2px border width to at least 1 side of a container. It should be used to add emphasis or visual separation beyond a 1px border. Recommended for elements needing extra thickness like Alert or Progress stepper. It must be used to ensure hover, focus, and active states are discernible by more than color alone per WCAG. Applying to all 4 sides at once is optional.
--rh-color-border-interactive

Focus ring outline color
--rh-space-sm

6px spacer
--rh-color-gray-50

Disabled message text color

Subtle icon
--rh-color-gray-40

Disabled text color in dark mode

Subtle icon (hover state)
--rh-color-gray-30

Subtle borders (light scheme)
--rh-color-gray-60

Disabled text color in light mode

Secondary text (light scheme)
Edit this page on GitHub
© 2026 Red Hat Deploys by Netlify