ThemeProvider: Fixes mismatch in rendered output for theming with server side rendering

.changeset/themeprovider-ssr-auto.md

@@ -0,0 +1,5 @@
+---
+'@primer/react': patch
+---
+
+Fixes a bug for theming with server side rendering where the output of the server and client mismatch [#1773](https://github.com/primer/react/issues/1773)

docs/content/theming.md

@@ -176,6 +176,16 @@ function Example() {
 }
 ```
 
+#### `preventSSRMismatch` prop
+
+If you are doing server-side rendering, pass the `preventSSRMismatch` prop to ensure the rendered output from the server and browser match even when they resolve "auto" color mode differently.
+
+```jsx
+<ThemeProvider colorMode="auto" preventSSRMismatch>
+ ...
+</ThemeProvider>
+```
+
 ### Setting color schemes
 
 To choose which color schemes will be displayed in `day` and `night` mode, use the `dayScheme` and `nightScheme` props on `ThemeProvider` or the `setDayScheme` and `setNightScheme` functions from the `useTheme` hook:

src/ThemeProvider.tsx

@@ -17,6 +17,7 @@ export type ThemeProviderProps = {
  colorMode?: ColorModeWithAuto
  dayScheme?: string
  nightScheme?: string
+ preventSSRMismatch?: boolean
 }
 
 const ThemeContext = React.createContext<{
@@ -47,21 +48,50 @@ export const ThemeProvider: React.FC<ThemeProviderProps> = ({children, ...props}
 
  // Initialize state
  const theme = props.theme ?? fallbackTheme ?? defaultTheme
+
+ const resolvedColorModePassthrough = React.useRef(
+ // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+ // @ts-ignore This custom variable does not exist on window because we set it outselves
+ typeof window !== 'undefined' ? window.__PRIMER_RESOLVED_SERVER_COLOR_MODE : undefined
+ )
+
  const [colorMode, setColorMode] = React.useState(props.colorMode ?? fallbackColorMode ?? defaultColorMode)
  const [dayScheme, setDayScheme] = React.useState(props.dayScheme ?? fallbackDayScheme ?? defaultDayScheme)
  const [nightScheme, setNightScheme] = React.useState(props.nightScheme ?? fallbackNightScheme ?? defaultNightScheme)
  const systemColorMode = useSystemColorMode()
- const resolvedColorMode = resolveColorMode(colorMode, systemColorMode)
+ const resolvedColorMode = resolvedColorModePassthrough.current || resolveColorMode(colorMode, systemColorMode)
  const colorScheme = chooseColorScheme(resolvedColorMode, dayScheme, nightScheme)
  const {resolvedTheme, resolvedColorScheme} = React.useMemo(
  () => applyColorScheme(theme, colorScheme),
  [theme, colorScheme]
  )
 
+ // this effect will only run on client
+ React.useEffect(
+ function updateColorModeAfterServerPassthorugh() {
+ const resolvedColorModeOnClient = resolveColorMode(colorMode, systemColorMode)
+
+ if (resolvedColorModePassthrough.current) {
+ // if the resolved color mode passed on from the server is not the resolved color mode on client, change it!
+ if (resolvedColorModePassthrough.current !== resolvedColorModeOnClient) {
+ window.setTimeout(() => {
+ // override colorMode to whatever is resolved on the client to get a re-render
+ setColorMode(resolvedColorModeOnClient)
+ // immediately after that, set the colorMode to what the user passed to respond to system color mode changes
+ setColorMode(colorMode)
+ })
+ }
+
+ resolvedColorModePassthrough.current = null
+ }
+ },
+ [colorMode, systemColorMode]
+ )
+
  // Update state if props change
  React.useEffect(() => {
  setColorMode(props.colorMode ?? fallbackColorMode ?? defaultColorMode)
- }, [props.colorMode, fallbackColorMode])
+ }, [props.colorMode, resolvedColorMode, fallbackColorMode])
 
  React.useEffect(() => {
  setDayScheme(props.dayScheme ?? fallbackDayScheme ?? defaultDayScheme)
@@ -86,7 +116,12 @@ export const ThemeProvider: React.FC<ThemeProviderProps> = ({children, ...props}
  setNightScheme
  }}
  >
- <SCThemeProvider theme={resolvedTheme}>{children}</SCThemeProvider>
+ <SCThemeProvider theme={resolvedTheme}>
+ {children}
+ {props.preventSSRMismatch ? (
+ <script dangerouslySetInnerHTML={{__html: `__PRIMER_RESOLVED_SERVER_COLOR_MODE='${resolvedColorMode}'`}} />
+ ) : null}
+ </SCThemeProvider>
  </ThemeContext.Provider>
  )
 }