fix(useMediaQuery): add option to martch media query on first render (#1020)

* fix(useMediaQuery): Return boolean describing media query match on first render instead of undefined

This gets rid of the value changing from undefined to boolean on the first renders, which might
trigger undesired side-effects for users.

BREAKING CHANGE: `useMediaQuery` and `useScreenOrientation` now returns matched media query state 
on first render by default, SSR users can change that behaviour via hook options.
fix #1000

Author: ArttuOll

src/useMediaQuery/__docs__/story.mdx

@@ -1,6 +1,6 @@
-import { Canvas, Meta, Story } from '@storybook/addon-docs';
-import { Example } from './example.stories';
-import { ImportPath } from '../../__docs__/ImportPath';
+import {Canvas, Meta, Story} from '@storybook/addon-docs';
+import {Example} from './example.stories';
+import {ImportPath} from '../../__docs__/ImportPath';
 
 <Meta title="Sensor/useMediaQuery" component={Example} />
 
@@ -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,8 +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.
-`undefined` - initially, when media query isn't matched yet.
+`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,13 +54,23 @@ describe('useMediaQuery', () => {
     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 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);
+  });
+
   it('should return match state', () => {
     const { result } = renderHook(() => useMediaQuery('max-width : 768px'));
     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 } from 'react';
-import { useSafeState } from '../useSafeState/useSafeState';
+import { Dispatch, useEffect, useState } from 'react';
 
 const queriesMap = new Map<
   string,
@@ -8,24 +7,28 @@ const queriesMap = new Map<
 
 type QueryStateSetter = (matches: boolean) => void;
 
+const createQueryEntry = (query: string) => {
+  const mql = matchMedia(query);
+  const dispatchers = new Set<QueryStateSetter>();
+  const listener = () => {
+    dispatchers.forEach((d) => d(mql.matches));
+  };
+
+  if (mql.addEventListener) mql.addEventListener('change', listener, { passive: true });
+  else mql.addListener(listener);
+
+  return {
+    mql,
+    dispatchers,
+    listener,
+  };
+};
+
 const querySubscribe = (query: string, setState: QueryStateSetter) => {
   let entry = queriesMap.get(query);
 
   if (!entry) {
-    const mql = matchMedia(query);
-    const dispatchers = new Set<QueryStateSetter>();
-    const listener = () => {
-      dispatchers.forEach((d) => d(mql.matches));
-    };
-
-    if (mql.addEventListener) mql.addEventListener('change', listener, { passive: true });
-    else mql.addListener(listener);
-
-    entry = {
-      mql,
-      dispatchers,
-      listener,
-    };
+    entry = createQueryEntry(query);
     queriesMap.set(query, entry);
   }
 
@@ -51,15 +54,29 @@ const queryUnsubscribe = (query: string, setState: QueryStateSetter): void => {
   }
 };
 
+interface UseMediaQueryOptions {
+  initializeWithValue?: boolean;
+}
+
 /**
  * Tracks the state of CSS media query.
  *
- * Return undefined initially and later receives correct value.
- *
  * @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 {
-  const [state, setState] = useSafeState<boolean>();
+export function useMediaQuery(query: string, options?: UseMediaQueryOptions): boolean | undefined {
+  const [state, setState] = useState<boolean | undefined>(() => {
+    if (options?.initializeWithValue ?? true) {
+      let entry = queriesMap.get(query);
+      if (!entry) {
+        entry = createQueryEntry(query);
+        queriesMap.set(query, entry);
+      }
+      return entry.mql.matches;
+    }
+  });
 
   useEffect(() => {
     querySubscribe(query, setState);

src/useScreenOrientation/__docs__/story.mdx

@@ -1,6 +1,6 @@
-import { Canvas, Meta, Story } from '@storybook/addon-docs';
-import { Example } from './example.stories';
-import { ImportPath } from '../../__docs__/ImportPath';
+import { Canvas, Meta, Story } from '@storybook/addon-docs'
+import { Example } from './example.stories'
+import { ImportPath } from '../../__docs__/ImportPath'
 
 <Meta title="Sensor/useScreenOrientation" component={Example} />
 
@@ -36,6 +36,13 @@ function useScreenOrientation(): ScreenOrientation;
 
 <ImportPath />
 
+#### Arguments
+
+- **options** _`object`_ - Hook options:
+  - **initializeWithValue** _`boolean`_ _(default: true)_ - Determine the screen orientation 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
 
-A string representing screen orientation
+A string representing the screen orientation.

src/useScreenOrientation/__tests__/dom.ts

@@ -55,6 +55,12 @@ describe('useScreenOrientation', () => {
     expect(result.error).toBeUndefined();
   });
 
+  it('should initialize without value if initializeWithValue option is set to false', () => {
+    const { result } = renderHook(() => useScreenOrientation({ initializeWithValue: false }));
+    expect(result.all[0]).toBeUndefined();
+    expect(result.all[1]).toBe('landscape');
+  });
+
   it('should return `portrait` in case media query matches and `landscape` otherwise', () => {
     const { result } = renderHook(() => useScreenOrientation());
     expect(result.current).toBe('landscape');

src/useScreenOrientation/__tests__/ssr.ts

@@ -6,8 +6,8 @@ describe('useScreenOrientation', () => {
     expect(useScreenOrientation).toBeDefined();
   });
 
-  it('should render', () => {
-    const { result } = renderHook(() => useScreenOrientation());
+  it('should render if initializeWithValue option is set to false', () => {
+    const { result } = renderHook(() => useScreenOrientation({ initializeWithValue: false }));
     expect(result.error).toBeUndefined();
   });
 });

src/useScreenOrientation/useScreenOrientation.ts

@@ -2,14 +2,22 @@ import { useMediaQuery } from '../useMediaQuery/useMediaQuery';
 
 export type ScreenOrientation = 'portrait' | 'landscape';
 
+interface UseScreenOrientationOptions {
+  initializeWithValue?: boolean;
+}
+
 /**
  * Checks if screen is in `portrait` or `landscape` orientation.
  *
  * As `Screen Orientation API` is still experimental and not supported by Safari, this
  * hook uses CSS3 `orientation` media-query to check screen orientation.
  */
-export function useScreenOrientation(): ScreenOrientation | undefined {
-  const matches = useMediaQuery('(orientation: portrait)');
+export function useScreenOrientation(
+  options?: UseScreenOrientationOptions
+): ScreenOrientation | undefined {
+  const matches = useMediaQuery('(orientation: portrait)', {
+    initializeWithValue: options?.initializeWithValue ?? true,
+  });
 
   return typeof matches === 'undefined' ? undefined : matches ? 'portrait' : 'landscape';
 }