feat(useMediaQuery): Add initializeWithValue option

This allows us to give the users the media query match state immediately on first render and
optionally give them SSR compatibility.

BREAKING CHANGE: Returned value is no longer undefined on first render. Set initializeWithValue to
false to re-enable this behavior.
fix #1000

Author: ArttuOll

src/useMediaQuery/__docs__/story.mdx

@@ -22,7 +22,11 @@ Tracks the state of CSS media query.
 ## Reference
 
 ```ts
-export function useMediaQuery(query: string): boolean | undefined;
+interface UseMediaQueryOptions {
+  initializeWithValue?: boolean;
+}
+
+export function useMediaQuery(query: string, options?: UseMediaQueryOptions): boolean | undefined;
 ```
 
 #### Importing
@@ -32,7 +36,12 @@ export function useMediaQuery(query: string): boolean | undefined;
 #### Arguments
 
 - **query** _`string`_ - CSS media query to track.
+- **options** _`object`_ - Hook options:
+    - **initializeWithValue** _`boolean`_ _(default: true)_ - Determine media query match state on first
+    render. Setting this to false will make the hook yield `undefined` on first render. We suggest
+    setting this to `false` during SSR.
 
 #### Return
 
-`boolean` - `true` in case document matches media query, `false` otherwise.
+`boolean` - `true` if document matches the media query, `false` if not. `undefined` on first render
+if `initializeWithValue` was set to `false`.

src/useMediaQuery/__tests__/dom.ts

@@ -54,8 +54,19 @@ describe('useMediaQuery', () => {
     expect(result.error).toBeUndefined();
   });
 
-  it('should return value on first render', () => {
-    const { result } = renderHook(() => useMediaQuery('max-width : 768px'));
+  it('should return undefined on first render, if initializeWithValue is false', () => {
+    const { result } = renderHook(() =>
+      useMediaQuery('max-width : 768px', { initializeWithValue: false })
+    );
+    expect(result.all.length).toBe(2);
+    expect(result.all[0]).toBe(undefined);
+    expect(result.current).toBe(false);
+  });
+
+  it('should return value on first render, if initializeWithValue is true', () => {
+    const { result } = renderHook(() =>
+      useMediaQuery('max-width : 768px', { initializeWithValue: true })
+    );
     expect(result.all.length).toBe(1);
     expect(result.current).toBe(false);
   });

src/useMediaQuery/__tests__/ssr.ts

@@ -7,12 +7,16 @@ describe('useMediaQuery', () => {
   });
 
   it('should render', () => {
-    const { result } = renderHook(() => useMediaQuery('max-width : 768px'));
+    const { result } = renderHook(() =>
+      useMediaQuery('max-width : 768px', { initializeWithValue: false })
+    );
     expect(result.error).toBeUndefined();
   });
 
-  it('should return undefined on first render', () => {
-    const { result } = renderHook(() => useMediaQuery('max-width : 768px'));
+  it('should return undefined on first render, if initializeWithValue is set to false', () => {
+    const { result } = renderHook(() =>
+      useMediaQuery('max-width : 768px', { initializeWithValue: false })
+    );
     expect(result.current).toBeUndefined();
   });
 });

src/useMediaQuery/useMediaQuery.ts

@@ -1,5 +1,4 @@
 import { Dispatch, useEffect, useState } from 'react';
-import { isBrowser } from '../util/const';
 
 const queriesMap = new Map<
   string,
@@ -55,14 +54,21 @@ const queryUnsubscribe = (query: string, setState: QueryStateSetter): void => {
   }
 };
 
+interface UseMediaQueryOptions {
+  initializeWithValue?: boolean;
+}
+
 /**
  * Tracks the state of CSS media query.
  *
  * @param query CSS media query to track.
+ * @param options Hook options:
+ * `initializeWithValue` (default: `true`) - Determine media query match state on first render. Setting
+ * this to false will make the hook yield `undefined` on first render.
  */
-export function useMediaQuery(query: string): boolean | undefined {
+export function useMediaQuery(query: string, options?: UseMediaQueryOptions): boolean | undefined {
   const [state, setState] = useState<boolean | undefined>(() => {
-    if (isBrowser) {
+    if (options?.initializeWithValue ?? true) {
       let entry = queriesMap.get(query);
       if (!entry) {
         entry = createQueryEntry(query);

src/useScreenOrientation/useScreenOrientation.ts

@@ -9,7 +9,7 @@ export type ScreenOrientation = 'portrait' | 'landscape';
  * hook uses CSS3 `orientation` media-query to check screen orientation.
  */
 export function useScreenOrientation(): ScreenOrientation | undefined {
-  const matches = useMediaQuery('(orientation: portrait)');
+  const matches = useMediaQuery('(orientation: portrait)', { initializeWithValue: false });
 
   return typeof matches === 'undefined' ? undefined : matches ? 'portrait' : 'landscape';
 }