fix: first render consistency in SSR+CSR envs

.changeset/thick-swans-attend.md

@@ -2,5 +2,8 @@
 "@chakra-ui/media-query": patch
 ---
 
-Fixed an issue that undefined is returned when calling the hook `useBreakpoint`
-with `defaultValue` specified in SSR
+- Fixed an issue that undefined is returned when calling the hook
+  `useBreakpoint` with `defaultValue` specified in SSR
+
+- Fixed an issue where the value of `useBreakpointValue` in CSR did not match
+  SSR.

packages/media-query/src/use-breakpoint-value.ts

@@ -8,7 +8,7 @@ import { useBreakpoint } from "./use-breakpoint"
  * provided responsive values object.
  *
  * @param values
- * @param defaultBreakpoint default breakpoint name
+ * @param [defaultBreakpoint="base"] default breakpoint name
  * (in non-window environments like SSR)
  *
  * For SSR, you can use a package like [is-mobile](https://github.com/kaimallea/isMobile)
@@ -19,7 +19,7 @@ import { useBreakpoint } from "./use-breakpoint"
  */
 export function useBreakpointValue<T = any>(
   values: Partial<Record<string, T>> | T[],
-  defaultBreakpoint?: string,
+  defaultBreakpoint = "base", // default value ensures SSR+CSR consistency
 ): T | undefined {
   const breakpoint = useBreakpoint(defaultBreakpoint)
   const theme = useTheme()

packages/media-query/src/use-breakpoint.ts

@@ -25,18 +25,9 @@ export function useBreakpoint(defaultBreakpoint?: string) {
   )
 
   const [currentBreakpoint, setCurrentBreakpoint] = React.useState(() => {
-    if (env.window.matchMedia) {
-      // set correct breakpoint on first render
-      const matchingBreakpointDetail = queries.find(
-        ({ query }) => env.window.matchMedia(query).matches,
-      )
-      if (matchingBreakpointDetail) {
-        return matchingBreakpointDetail.breakpoint
-      }
-    }
-
     if (defaultBreakpoint) {
-      // use fallback if available
+      // use default breakpoint to ensure render consistency in SSR + CSR environments
+      // => first render on the client has to match the render on the server
       const fallbackBreakpointDetail = queries.find(
         ({ breakpoint }) => breakpoint === defaultBreakpoint,
       )
@@ -45,6 +36,16 @@ export function useBreakpoint(defaultBreakpoint?: string) {
       }
     }
 
+    if (env.window.matchMedia) {
+      // set correct breakpoint on first render if no default breakpoint was provided
+      const matchingBreakpointDetail = queries.find(
+        ({ query }) => env.window.matchMedia(query).matches,
+      )
+      if (matchingBreakpointDetail) {
+        return matchingBreakpointDetail.breakpoint
+      }
+    }
+
     return undefined
   })