A foundational overview of how to build an adaptive and accessible theme switch component.
 Adam Argyle [X](https://twitter.com/argyleink) [GitHub](https://github.com/argyleink) [Homepage](https://nerdy.dev)
`](https://developer.mozilla.org/docs/Web/HTML/Element/button)
should be used for the toggle, as you then benefit from browser-provided
interaction events and features, such as click events and focusability.
### The button
The button needs a class for use from CSS and an ID for use from JavaScript.
Additionally, since the button content is an icon rather than text, add a
[title](https://developer.mozilla.org/docs/Web/HTML/Global_attributes/title)
attribute to provide information about the button's purpose. Last, add an
[`[aria-label]`](https://developer.mozilla.org/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-label_attribute)
to hold the state of the icon button, so screen readers can share the state of
the theme to folks who are visually impaired.
...
#### `aria-label` and `aria-live` polite
To indicate to screen readers that changes to `aria-label` should be announced,
add
[`aria-live="polite"`](https://developer.mozilla.org/docs/Web/Accessibility/ARIA/Attributes/aria-live#:%7E:text=on%20that%20region.-,polite,-Indicates%20that%20updates)
to the button.
...
This markup addition signals to screen readers to politely, instead of
[`aria-live="assertive"`](https://developer.mozilla.org/docs/Web/Accessibility/ARIA/ARIA_Live_Regions#:%7E:text=aria%2Dlive%3D%22assertive%22%20should%20only%20be%20used%20for%20time%2Dsensitive/critical%20notifications%20that%20absolutely%20require%20the%20user%27s%20immediate%20attention.),
tell the user what changed. In the case of this button, it will announce "light"
or "dark" depending on what the `aria-label` has become.
### The scalable vector graphic (SVG) icon
[SVG](https://developer.mozilla.org/docs/Web/SVG) provides a way to create
high-quality, scalable shapes with minimal markup. Interacting with the button
can trigger new visual states for the vectors, making SVG great for icons.
The following SVG markup goes inside the ``:
...
[`aria-hidden`](https://developer.mozilla.org/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-hidden_attribute)
has been added to the SVG element so screen readers know to ignore it as it's
marked presentational. This is great to do for visual decorations, like the icon
inside a button. In addition to the required `viewBox` attribute on the element,
add height and width for [similar reasons that images should get inline
sizes](https://web.dev/learn/design/responsive-images).
#### The sun
The sun graphic consists of a circle and lines which SVG conveniently has shapes
for. The `` is centered by setting the `cx` and `cy` properties to 12,
which is half of the viewport size (24), and then given a radius (`r`) of `6`
which sets the size.
Additionally, the mask property points to an [SVG element's
ID](https://developer.mozilla.org/docs/Web/CSS/url()#:%7E:text=url(myFont.woff)%3B-,url(%23IDofSVGpath),-%3B%0A%0A/*%20associated%20properties%20*/%0Abackground),
which you will create next, and finally given a fill color that matches the
page's text color with
[`currentColor`](https://developer.mozilla.org/docs/Web/CSS/color_value#currentcolor_keyword).
#### The sun beams
Next, the sunbeam lines are added just below the circle, inside of a group
element [``](https://developer.mozilla.org/docs/Web/SVG/Element/g)
group.
This time, instead of the value of
[fill](https://developer.mozilla.org/docs/Web/SVG/Attribute/fill) being
`currentColor`, each line's
[stroke](https://developer.mozilla.org/docs/Web/SVG/Attribute/stroke) is
set. The lines plus the circle shapes create a nice sun with beams.
> [!NOTE]
> **Note:** Icon SVG sourced from with minor adjustments made.
#### The moon
To create the illusion of a seamless transition between light (sun) and dark
(moon), the moon is an augmentation of the sun icon, using an SVG mask.
...
[Masks](https://developer.mozilla.org/docs/Web/SVG/Element/mask) with SVG
are powerful, allowing the colors white and black to either remove or include
parts of another graphic. The sun icon will be eclipsed by a moon
[``](https://developer.mozilla.org/docs/Web/SVG/Element/circle)
shape with an SVG mask, simply by moving a circle shape in and out of a mask
area.
#### What happens if CSS doesn't load?
It can be nice to test your SVG as if CSS didn't load to ensure the result isn't
super large or causing layout issues. The inline height and width attributes on
the SVG plus the use of `currentColor` give minimal style rules for the browser
to use if CSS doesn't load. This makes for nice defensive styles against network
turbulence.
## Layout
The theme switch component has little surface area, so you don't need grid or
flexbox for layout. Instead, SVG positioning and CSS transforms are used.
## Styles
### `.theme-toggle` styles
The `` element is the container for the icon shapes and styles. This
parent context will hold adaptive colors and sizes to pass down to SVG.
The first task is to make the button a circle and remove the default button
styles:
.theme-toggle {
--size: 2rem;
background: none;
border: none;
padding: 0;
inline-size: var(--size);
block-size: var(--size);
aspect-ratio: 1;
border-radius: 50%;
}
Next, add some interaction styles. Add a cursor style for mouse users. Add
`touch-action: manipulation` for a [fast reacting touch
experience](https://twitter.com/argyleink/status/1405881231695302659?s=20).
Remove the semi-transparent highlight iOS applies to buttons. Last, give the
focus state outline some breathing room from the edge of the element:
.theme-toggle {
--size: 2rem;
background: none;
border: none;
padding: 0;
inline-size: var(--size);
block-size: var(--size);
aspect-ratio: 1;
border-radius: 50%;
cursor: pointer;
touch-action: manipulation;
-webkit-tap-highlight-color: transparent;
outline-offset: 5px;
}
The SVG inside of the button needs some styles as well. The SVG should fit the size of the button and, for visual softness, round out the line ends:
.theme-toggle {
--size: 2rem;
background: none;
border: none;
padding: 0;
inline-size: var(--size);
block-size: var(--size);
aspect-ratio: 1;
border-radius: 50%;
cursor: pointer;
touch-action: manipulation;
-webkit-tap-highlight-color: transparent;
outline-offset: 5px;
& > svg {
inline-size: 100%;
block-size: 100%;
stroke-linecap: round;
}
}
> [!NOTE]
> **Note:** The [CSS @nest](https://www.w3.org/TR/css-nesting-1/) feature, used with [PostCSS Nesting](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-nesting), allows authoring new styles without leaving a selectors context. The above nested selector creates `.theme-toggle > svg` because the `&` character is dynamically represented as `.theme-toggle`.
#### Adaptive sizing with the `hover` media query
The icon button size is a bit small at `2rem`, which is fine for mouse users but
can be a struggle for a coarse pointer like a finger. Make the button meet many
[touch size
guidelines](https://developer.apple.com/design/human-interface-guidelines/sign-in-with-apple/overview/buttons/#:%7E:text=buttons%20that%20measure%2044x44%20pt)
by using a [hover media
query](https://developer.mozilla.org/docs/Web/CSS/@media/hover) to specify
a size increase.
.theme-toggle {
--size: 2rem;
...
@media (hover: none) {
--size: 48px;
}
}
### Sun and moon SVG styles
The button holds the interactive aspects of the theme switch component while SVG
inside will hold the visual and animated aspects. This is where the icon can be
made beautiful and brought to life.
#### Light theme
For scale and rotate animations to happen from the center of SVG shapes, set
their `transform-origin: center center`. The adaptive colors provided by the
button are used here by the shapes. The moon and sun use the button provided
`var(--icon-fill)` and `var(--icon-fill-hover)` for their fill, while the
sunbeams use the variables for stroke.
.sun-and-moon {
& > :is(.moon, .sun, .sun-beams) {
transform-origin: center center;
}
& > :is(.moon, .sun) {
fill: var(--icon-fill);
@nest .theme-toggle:is(:hover, :focus-visible) > & {
fill: var(--icon-fill-hover);
}
}
& > .sun-beams {
stroke: var(--icon-fill);
stroke-width: 2px;
@nest .theme-toggle:is(:hover, :focus-visible) & {
stroke: var(--icon-fill-hover);
}
}
}
> [!NOTE]
> **Note:** `@nest` is used again, this time to make a new selector that targets a parent button being hovered or focused. `@nest .theme-toggle:is(:hover, :focus-visible) &` in this usage is the same as `@nest .theme-toggle:is(:hover, :focus-visible) .sun-and-moon > .sun-beams`.
#### Dark theme
The moon styles need to remove the sunbeams, scale up the sun circle and move
the circle mask.
.sun-and-moon {
@nest [data-theme="dark"] & {
& > .sun {
transform: scale(1.75);
}
& > .sun-beams {
opacity: 0;
}
& > .moon > circle {
transform: translateX(-7px);
@supports (cx: 1px) {
transform: translateX(0);
cx: 17px;
}
}
}
}
Notice the dark theme has no color changes or transitions. The parent button
component owns the colors, where they're already adaptive within a dark and
light context. The transition information should be behind a user's motion
preference media query.
## Animation
The button should be functional and stateful but without transitions at this
point. The following sections are all about defining **how** and **what**
transitions.
### Sharing media queries and importing easings
To make it easy to put transitions and animations behind a user's operating
system motion preferences, the [PostCSS](https://postcss.org/) plugin [Custom
Media](https://github.com/postcss/postcss-custom-media) enables usage of the
[drafted CSS specification for media query
variables](https://drafts.csswg.org/mediaqueries-5/#custom-mq) syntax:
@custom-media --motionOK (prefers-reduced-motion: no-preference);
/* usage example */
@media (--motionOK) {
.sun {
transition: transform .5s var(--ease-elastic-3);
}
}
For unique and easy to use CSS easings, import the
[easings](https://open-props.style/#easing) portion of [Open
Props](https://open-props.style/):
@import "https://unpkg.com/open-props/easings.min.css";
/* usage example */
.sun {
transition: transform .5s var(--ease-elastic-3);
}
### The sun
The sun transitions will be more playful than the moon, achieving this effect
with bouncy easings. The sunbeams should bounce a small amount as they rotate
and the center of the sun should bounce a small amount as it scales.
The default (light theme) styles define the transitions and the dark theme
styles define customizations for the transition to light:
.sun-and-moon {
@media (--motionOK) {
& > .sun {
transition: transform .5s var(--ease-elastic-3);
}
& > .sun-beams {
transition:
transform .5s var(--ease-elastic-4),
opacity .5s var(--ease-3)
;
}
@nest [data-theme="dark"] & {
& > .sun {
transform: scale(1.75);
transition-timing-function: var(--ease-3);
transition-duration: .25s;
}
& > .sun-beams {
transform: rotateZ(-25deg);
transition-duration: .15s;
}
}
}
}
In the [Animation](https://developer.chrome.com/docs/devtools/css/animations)
panel in Chrome DevTools, you can find a timeline for animation transitions. The
duration of the total animation, the elements, and the easing timing can be
inspected.
 Light to dark transition  Dark to light transition
### The moon
The moon light and dark positions are already set, add transition styles inside
of the `--motionOK` media query to bring it to life while respecting the user's
motion preferences.
The timing with delay and duration are critical in making this transition clean.
If the sun is eclipsed too early, for example, the transition doesn't feel
orchestrated or playful, it feels chaotic.
.sun-and-moon {
@media (--motionOK) {
& .moon > circle {
transform: translateX(-7px);
transition: transform .25s var(--ease-out-5);
@supports (cx: 1px) {
transform: translateX(0);
cx: 17px;
transition: cx .25s var(--ease-out-5);
}
}
@nest [data-theme="dark"] & {
& > .moon > circle {
transition-delay: .25s;
transition-duration: .5s;
}
}
}
}
 Light to dark transition  Dark to light transition
### Prefers reduced motion
In most [GUI Challenges](https://web.dev/shows/gui-challenges) I try to keep
some animation, like opacity cross fades, for users who prefer reduced motion.
This component felt better with instant state changes however.
## JavaScript
There's a lot of work for JavaScript in this component, from managing ARIA
information for screen readers to getting and setting values from [local
storage](https://developer.mozilla.org/docs/Web/API/Window/localStorage).
### The page load experience
It was important that no color flashing occurs on page load. If a user with a
dark color scheme indicates they preferred light with this component, then
reloaded the page, at first the page would be dark then it would flash to light.
Preventing this meant running a small amount of blocking JavaScript with the
goal to set the HTML attribute `data-theme` as early as possible.
To achieve this, a plain `