diff --git a/.changeset/stupid-carrots-jam.md b/.changeset/stupid-carrots-jam.md
new file mode 100644
index 00000000000..0df7f9b5237
--- /dev/null
+++ b/.changeset/stupid-carrots-jam.md
@@ -0,0 +1,5 @@
+---
+'@primer/react': minor
+---
+
+Adds a toggle switch component
diff --git a/docs/content/ToggleSwitch.mdx b/docs/content/ToggleSwitch.mdx
new file mode 100644
index 00000000000..ae2764af93e
--- /dev/null
+++ b/docs/content/ToggleSwitch.mdx
@@ -0,0 +1,220 @@
+---
+componentId: toggle_switch
+title: ToggleSwitch
+description: Toggles a setting on or off, and immediately saves the change
+status: Alpha
+source: https://github.com/primer/react/blob/main/src/ToggleSwitch.tsx
+storybook: '/react/storybook?path=/story/toggleswitch-examples--default'
+---
+
+## Examples
+
+### Basic
+
+```jsx live
+
+
+ Notifications
+
+
+```
+
+### Uncontrolled with default value
+
+```jsx live
+
+
+ Notifications
+
+
+```
+
+### Controlled
+
+```javascript noinline live
+const Controlled = () => {
+ const [isOn, setIsOn] = React.useState(false)
+
+ const onClick = () => {
+ setIsOn(!isOn)
+ }
+
+ const handleSwitchChange = on => {
+ console.log(`new switch "on" state: ${on}`)
+ }
+
+ return (
+ <>
+
+
+ Notifications
+
+
+ The switch is {isOn ? 'on' : 'off'}
+
+ )
+}
+
+render(Controlled)
+```
+
+### Small
+
+```jsx live
+
+
+ Notifications
+
+
+```
+
+### Delayed toggle with loading state
+
+```javascript noinline live
+const LoadingToggle = () => {
+ const [loading, setLoading] = React.useState(false)
+ const [isOn, setIsOn] = React.useState(false)
+
+ async function switchSlowly(currentOn) {
+ await new Promise(resolve => setTimeout(resolve, 1500))
+ return await !currentOn
+ }
+
+ async function onClick() {
+ setLoading(!loading)
+ const newSwitchState = await switchSlowly(isOn)
+ setIsOn(newSwitchState)
+ }
+
+ const handleSwitchChange = React.useCallback(
+ on => {
+ setLoading(false)
+ },
+ [setLoading]
+ )
+
+ return (
+ <>
+
+
+ Notifications
+
+
+ The switch is {isOn ? 'on' : 'off'}
+
+ )
+}
+
+render(LoadingToggle)
+```
+
+### Disabled
+
+```jsx live
+
+
+ Notifications
+
+
+```
+
+### With associated caption text
+
+```jsx live
+
+
+
+ Notifications
+
+
+ Notifications will be delivered via email and the GitHub notification center
+
+
+
+```
+
+### Left-aligned with label
+
+```jsx live
+<>
+
+ Notifications
+
+
+
+ Whether the "on" and "off" labels should appear before or after the switch.
+
+ This should only be changed when the switch's alignment needs to be adjusted. {' '}
+ For example: It needs to be left-aligned because the label appears above it and the caption appears below it.
+
+
+ }
+ />
+
+
+## Status
+
+(filterValue: strin
}
}
-function getDefaultOnSelectionChange(
+function getdefaultCheckedSelectionChange(
setInputValueFn: (value: string) => void
): OnSelectedChange {
return function (itemOrItems) {
@@ -160,7 +160,9 @@ function AutocompleteMenu(props: AutocompleteMe
const newSelectedItemIds = selectedItemIds.includes(item.id)
? otherSelectedItemIds
: [...otherSelectedItemIds, item.id]
- const onSelectedChangeFn = onSelectedChange ? onSelectedChange : getDefaultOnSelectionChange(setInputValue)
+ const onSelectedChangeFn = onSelectedChange
+ ? onSelectedChange
+ : getdefaultCheckedSelectionChange(setInputValue)
onSelectedChangeFn(
newSelectedItemIds.map(newSelectedItemId => getItemById(newSelectedItemId, items)) as T[]
diff --git a/src/ToggleSwitch.tsx b/src/ToggleSwitch.tsx
new file mode 100644
index 00000000000..14e07f1e006
--- /dev/null
+++ b/src/ToggleSwitch.tsx
@@ -0,0 +1,329 @@
+import React, {MouseEventHandler, useCallback, useEffect} from 'react'
+import styled, {css} from 'styled-components'
+import {variant} from 'styled-system'
+import {Box, Spinner, Text} from '.'
+import {get} from './constants'
+import {useProvidedStateOrCreate} from './hooks'
+import sx, {BetterSystemStyleObject, SxProp} from './sx'
+import VisuallyHidden from './_VisuallyHidden'
+
+const TRANSITION_DURATION = '80ms'
+const EASE_OUT_QUAD_CURVE = 'cubic-bezier(0.5, 1, 0.89, 1)'
+
+type SwitchProps = {
+ /** The id of the DOM node that describes the switch */
+ ['aria-describedby']?: string
+ /** The id of the DOM node that labels the switch */
+ ['aria-labelledby']: string
+ /** Uncontrolled - whether the switch is turned on */
+ defaultChecked?: boolean
+ /** Whether the switch is ready for user input */
+ disabled?: boolean
+ /** Whether the switch's value is being calculated */
+ loading?: boolean
+ /** Whether the switch is turned on */
+ checked?: boolean
+ /** The callback that is called when the switch is toggled on or off */
+ onChange?: (on: boolean) => void
+ /** The callback that is called when the switch is clicked */
+ onClick?: MouseEventHandler
+ /** Size of the switch */
+ size?: 'small' | 'medium'
+ /** Whether the "on" and "off" labels should appear before or after the switch.
+ * **This should only be changed when the switch's alignment needs to be adjusted.** For example: It needs to be left-aligned because the label appears above it and the caption appears below it.
+ */
+ statusLabelPosition?: 'start' | 'end'
+} & SxProp
+
+const sizeVariants = variant({
+ prop: 'size',
+ variants: {
+ small: {
+ height: '24px',
+ width: '48px'
+ }
+ }
+})
+
+type SwitchButtonProps = {
+ disabled?: boolean
+ checked?: boolean
+ size?: SwitchProps['size']
+} & SxProp
+
+type InnerIconProps = {size?: SwitchProps['size']}
+
+const CircleIcon: React.FC = ({size}) => (
+
+
+)
+const LineIcon: React.FC = ({size}) => (
+
+
+)
+
+const SwitchButton = styled.button`
+ vertical-align: middle;
+ cursor: pointer;
+ user-select: none;
+ appearance: none;
+ text-decoration: none;
+ padding: 0;
+ transition-property: background-color, border-color;
+ transition-duration: ${TRANSITION_DURATION};
+ transition-timing-function: ${EASE_OUT_QUAD_CURVE};
+ border-radius: ${get('radii.2')};
+ border-style: solid;
+ border-width: 1px;
+ display: block;
+ height: 32px;
+ width: 64px;
+ outline-offset: 2px;
+ position: relative;
+
+ @media (pointer: coarse) {
+ &:before {
+ content: '';
+ position: absolute;
+ left: 0;
+ right: 0;
+ transform: translateY(-50%);
+ top: 50%;
+ min-height: 44px;
+ }
+ }
+
+ @media (prefers-reduced-motion) {
+ transition: none;
+
+ * {
+ transition: none;
+ }
+ }
+
+ &:after {
+ content: '';
+ box-sizing: border-box;
+ position: absolute;
+ top: 0;
+ left: 0;
+ width: 100%;
+ height: 100%;
+ border-radius: calc(${get('radii.2')} - 1px); /* -1px to account for 1px border around the control */
+ }
+
+ ${props => {
+ if (props.disabled) {
+ return css`
+ background-color: ${get('colors.canvas.subtle')};
+ border-color: ${get('colors.border.subtle')};
+ cursor: not-allowed;
+ transition-property: none;
+ `
+ }
+
+ if (props.checked) {
+ return css`
+ background-color: ${get('colors.switchTrack.checked.bg')};
+ border-color: ${get('colors.switchTrack.checked.border')};
+
+ &:hover,
+ &:focus:focus-visible {
+ background-color: ${get('colors.switchTrack.checked.hoverBg')};
+ }
+
+ &:active,
+ &:active:focus-visible {
+ background-color: ${get('colors.switchTrack.checked.activeBg')};
+ }
+ `
+ } else {
+ return css`
+ background-color: ${get('colors.switchTrack.bg')};
+ border-color: ${get('colors.switchTrack.border')};
+
+ &:hover,
+ &:focus:focus-visible {
+ .Toggle-knob {
+ background-color: ${get('colors.btn.hoverBg')};
+ }
+ }
+
+ &:active,
+ &:active:focus-visible {
+ .Toggle-knob {
+ background-color: ${get('colors.btn.activeBg')};
+ }
+ }
+ `
+ }
+ }}
+
+ ${sx}
+ ${sizeVariants}
+`
+
+const ToggleKnob = styled.div<{checked?: boolean; disabled?: boolean}>`
+ background-color: ${get('colors.btn.bg')};
+ border-width: 1px;
+ border-style: solid;
+ border-color: ${props => (props.disabled ? get('colors.border.default') : get('colors.switchTrack.border'))};
+ border-radius: calc(${get('radii.2')} - 1px); /* -1px to account for 1px border around the control */
+ box-shadow: ${props =>
+ props.disabled ? 'none' : `${props.theme?.shadows?.shadow.medium}, ${props.theme?.shadows?.btn.insetShadow}`};
+ width: 50%;
+ position: absolute;
+ top: -1px;
+ bottom: -1px;
+ transition-property: transform;
+ transition-duration: ${TRANSITION_DURATION};
+ transition-timing-function: ${EASE_OUT_QUAD_CURVE};
+ transform: ${props => `translateX(${props.checked ? 'calc(100% + 1px)' : '-1px'})`};
+ z-index: 1;
+
+ @media (prefers-reduced-motion) {
+ transition: none;
+ }
+
+ ${props => {
+ if (props.checked) {
+ return css`
+ background-color: ${props.disabled
+ ? get('colors.switchKnob.checked.disabledBg')
+ : get('colors.switchKnob.checked.bg')};
+ border-color: ${props.disabled
+ ? get('colors.switchKnob.checked.disabledBg')
+ : get('colors.switchKnob.checked.bg')};
+ box-shadow: ${get('shadows.shadow.small')};
+ `
+ }
+ }}
+`
+
+const hiddenTextStyles: BetterSystemStyleObject = {
+ visibility: 'hidden',
+ height: 0
+}
+
+const Switch: React.FC = ({
+ 'aria-labelledby': ariaLabelledby,
+ 'aria-describedby': ariaDescribedby,
+ defaultChecked,
+ disabled,
+ loading,
+ checked,
+ onChange,
+ onClick,
+ size,
+ statusLabelPosition,
+ sx: sxProp
+}) => {
+ const isControlled = typeof checked !== 'undefined'
+ const [isOn, setIsOn] = useProvidedStateOrCreate(checked, onChange, Boolean(defaultChecked))
+ const acceptsInteraction = !disabled && !loading
+ const handleToggleClick: MouseEventHandler = useCallback(
+ e => {
+ if (!isControlled) {
+ setIsOn(!isOn)
+ }
+ onClick && onClick(e)
+ },
+ [onClick, isControlled, isOn, setIsOn]
+ )
+
+ useEffect(() => {
+ if (onChange && isControlled) {
+ onChange(Boolean(checked))
+ }
+ }, [onChange, checked, isControlled])
+
+ return (
+
+ {loading ?
+
+ On
+
+
+ Off
+
+
+
+ {isOn ? 'On' : 'Off'}
+
+
+
+
+
+
+
+
+ )
+}
+
+Switch.defaultProps = {
+ statusLabelPosition: 'start',
+ size: 'medium'
+}
+
+export default Switch
diff --git a/src/__tests__/ToggleSwitch.test.tsx b/src/__tests__/ToggleSwitch.test.tsx
new file mode 100644
index 00000000000..65816bae599
--- /dev/null
+++ b/src/__tests__/ToggleSwitch.test.tsx
@@ -0,0 +1,128 @@
+import React from 'react'
+import '@testing-library/jest-dom/extend-expect'
+import {render} from '@testing-library/react'
+import {ToggleSwitch} from '..'
+import {behavesAsComponent, checkExports, checkStoriesForAxeViolations} from '../utils/testing'
+import userEvent from '@testing-library/user-event'
+
+const SWITCH_LABEL_TEXT = 'Switch label'
+
+behavesAsComponent({
+ Component: ToggleSwitch,
+ options: {skipAs: true}
+})
+checkExports('ToggleSwitch', {
+ default: ToggleSwitch
+})
+it('renders a switch that is turned off', () => {
+ const {getByLabelText} = render(
+ <>
+ {SWITCH_LABEL_TEXT}
+ {SWITCH_LABEL_TEXT}
+ {SWITCH_LABEL_TEXT}
+ {SWITCH_LABEL_TEXT}
+ {SWITCH_LABEL_TEXT}
+ {SWITCH_LABEL_TEXT}
+ {SWITCH_LABEL_TEXT}
+
+
+
+ On
+
+
+ Off
+
+
+
+
+ Off
+
+
+
+
+
+
+const excludedControlKeys = [
+ 'aria-describedby',
+ 'aria-labelledby',
+ 'defaultChecked',
+ 'onChange',
+ 'onClick',
+ 'statusLabelPosition',
+ 'sx'
+]
+
+export default {
+ title: 'ToggleSwitch/examples',
+ component: ToggleSwitch,
+ argTypes: {
+ on: {
+ defaultValue: undefined,
+ control: {
+ type: 'boolean'
+ }
+ },
+ disabled: {
+ defaultValue: false,
+ control: {
+ type: 'boolean'
+ }
+ },
+ loading: {
+ defaultValue: false,
+ control: {
+ type: 'boolean'
+ }
+ },
+ size: {
+ defaultValue: 'medium',
+ control: {
+ type: 'radio',
+ options: ['small', 'medium']
+ }
+ }
+ },
+ parameters: {controls: {exclude: excludedControlKeys}},
+ decorators: [
+ Story => {
+ return (
+
+
+
+
+ )
+ }
+ ]
+} as Meta
+
+export const Default = (args: Args) => (
+
+
+ Notifications
+
+
+)
+Default.storyName = 'Default (uncontrolled)'
+
+export const Controlled = (args: Args) => {
+ const [isOn, setIsOn] = React.useState(false)
+
+ const onClick = React.useCallback(() => {
+ setIsOn(!isOn)
+ }, [setIsOn, isOn])
+
+ const handleSwitchChange = (on: boolean) => {
+ action(`new switch "on" state: ${on}`)
+ }
+
+ return (
+ <>
+
+
+ Notifications
+
+
+ The switch is {isOn ? 'on' : 'off'}
+
+ )
+}
+Controlled.parameters = {controls: {exclude: [...excludedControlKeys, 'on']}}
+
+export const StatusLabelPositionedAtEnd = (args: Args) => (
+ <>
+
+ Notifications
+
+
+
+export default {
+ title: 'ToggleSwitch/fixtrues',
+ component: ToggleSwitch,
+ argTypes: {
+ on: {
+ defaultValue: undefined,
+ control: {
+ type: 'boolean'
+ }
+ },
+ disabled: {
+ defaultValue: false,
+ control: {
+ type: 'boolean'
+ }
+ },
+ loading: {
+ defaultValue: false,
+ control: {
+ type: 'boolean'
+ }
+ },
+ size: {
+ control: {
+ type: 'radio',
+ options: ['small', 'medium']
+ }
+ }
+ },
+ parameters: {
+ controls: {
+ exclude: ['aria-describedby', 'aria-labelledby', 'defaultChecked', 'onChange', 'onClick', 'statusLabelPosition']
+ }
+ },
+ decorators: [
+ Story => {
+ return (
+
+
+
+
+ )
+ }
+ ]
+} as Meta
+
+export const Small = (args: Args) => (
+ <>
+
+ Notifications
+
+
+
+
+ Notifications
+
+
+ Notifications will be delivered via email and the GitHub notification center
+
+
+
+)
+WithCaption.storyName = 'Associated with a caption'
diff --git a/src/theme-preval.js b/src/theme-preval.js
index 2f3ce2b7517..7f2222dd0d5 100644
--- a/src/theme-preval.js
+++ b/src/theme-preval.js
@@ -1,6 +1,6 @@
// @preval
// This file needs to be a JavaScript file using CommonJS to be compatible with preval
-// Cache bust: 2022-03-14 12:00:00 GMT (This file is cached by our deployment tooling, update this timestamp to rebuild this file)
+// Cache bust: 2022-03-24 12:00:00 GMT (This file is cached by our deployment tooling, update this timestamp to rebuild this file)
const {default: primitives} = require('@primer/primitives')
const {partitionColors, fontStack, omitScale} = require('./utils/theme')