useMediaQuery

useMediaQuery is a custom hook that helps detect matches between a single media query or multiple media queries.

Installation

API Reference

useMediaQuery is a custom hook that helps detect matches between a single media query or multiple media queries. React Native does not natively support media queries, so useMediaQuery is still limited.

function App() {
  const [isMobile, isTablet, isSmallScreen, isLargeScreen] = useMediaQuery([
    {
      maxWidth: 480,
    },
    {
      minWidth: 481,
      maxWidth: 768,
    },
    {
      minWidth: 769,
      maxWidth: 1440,
    },
    {
      minWidth: 1441,
    },
  ])
  return (
    <Box className="justify-center items-center gap-4">
      <Heading>useMediaQuery</Heading>
      <Text>Resize your browser windows to see changes.</Text>
      <Box className="flex-row flex-wrap gap-8 justify-center">
        <Box
          className={
            "border justify-center items-center w-[120px] h-[80px] rounded gap-2 " +
            (isMobile ? "border-primary-500 bg-background-50" : "")
          }
        >
          <Icon as={Smartphone} size={"xs"} />
          <Text size="sm">Small</Text>
        </Box>
        <Box
          className={
            "border justify-center items-center w-[120px] h-[80px] rounded gap-2 " +
            (isTablet ? "border-primary-500 bg-background-50" : "")
          }
        >
          <Icon as={Tablet} size="sm" />
          <Text size="sm">medium</Text>
        </Box>
        <Box
          className={
            "border justify-center items-center w-[120px] h-[80px] rounded gap-2 " +
            (isSmallScreen ? "border-primary-500 bg-background-50" : "")
          }
        >
          <Icon as={Laptop} size="sm" />
          <Text size="sm">Large</Text>
        </Box>
        <Box
          className={
            "border justify-center items-center w-[120px] h-[80px] rounded gap-2 " +
            (isLargeScreen ? "border-primary-500 bg-background-50" : "")
          }
        >
          <Icon as={Tv} size="sm" />
          <Text size="sm">Extra Large</Text>
        </Box>
      </Box>
    </Box>
  )
}

Installation

CLI

Manual

Run the following command:

npx gluestack-ui add useMediaQuery

Step 1: Copy and paste the following code into index.ts in your project.

import { useWindowDimensions } from "react-native"

type QueryKeys =
  | "maxWidth"
  | "minWidth"
  | "maxHeight"
  | "minHeight"
  | "orientation"

type SubQuery = {
  [queryKey in QueryKeys]?: number | string
}
type Query = Array<SubQuery>

export function useMediaQuery(query: SubQuery | Query) {
  const dims = useWindowDimensions()
  const height = dims?.height
  const width = dims?.width

  return iterateQuery(query, height, width)
}

function queryResolver(query: any, width?: number, height?: number) {
  for (const queryKey in query) {
    if (!calculateQuery(queryKey, query[queryKey], height, width)) {
      return false
    }
  }
  return true
}

function iterateQuery(
  query: SubQuery | Query,
  height?: number,
  width?: number
) {
  const queryResults = []
  if (Array.isArray(query)) {
    query.forEach((subQuery: SubQuery) => {
      queryResults.push(queryResolver(subQuery, width, height))
    })
  } else {
    queryResults.push(queryResolver(query, width, height))
  }
  return queryResults
}

function calculateQuery(
  key: string,
  val?: number | string,
  height?: number,
  width?: number
) {
  let retval
  switch (key) {
    case "maxWidth":
      retval = typeof val === "number" && width ? width <= val : undefined
      break
    case "minWidth":
      retval = typeof val === "number" && width ? width >= val : undefined
      break
    case "maxHeight":
      retval = typeof val === "number" && height ? height <= val : undefined
      break
    case "minHeight":
      retval = typeof val === "number" && height ? height >= val : undefined
      break
    case "orientation":
      if (val) {
        if (width && height && width > height) {
          retval = typeof val === "string" && val === "landscape"
        } else {
          retval = typeof val === "string" && val === "portrait"
        }
      }
      break
    default:
      break
  }
  return retval
}

Important Note

Note: Step 2 is for web only

Step 2: Copy and paste the following code into index.web.ts in your project.

import { useState, useEffect } from "react"

type QueryKeys =
  | "maxWidth"
  | "minWidth"
  | "maxHeight"
  | "minHeight"
  | "orientation"

type SubQuery = {
  [queryKey in QueryKeys]?: number | string
}
type Query = Array<SubQuery>

export function useMediaQuery(query: SubQuery | Query) {
  const [dims, setDims] = useState({
    height: window.innerHeight,
    width: window.innerWidth,
  })

  useEffect(() => {
    const handleResize = () => {
      setDims({
        height: window.innerHeight,
        width: window.innerWidth,
      })
    }
    window.addEventListener("resize", handleResize)

    return () => {
      window.removeEventListener("resize", handleResize)
    }
  }, [])

  const { height, width } = dims
  return iterateQuery(query, height, width)
}

function queryResolver(query: any, width?: number, height?: number) {
  for (const queryKey in query) {
    if (!calculateQuery(queryKey, query[queryKey], height, width)) {
      return false
    }
  }
  return true
}

function iterateQuery(
  query: SubQuery | Query,
  height?: number,
  width?: number
) {
  const queryResults = []
  if (Array.isArray(query)) {
    query.forEach((subQuery: SubQuery) => {
      queryResults.push(queryResolver(subQuery, width, height))
    })
  } else {
    queryResults.push(queryResolver(query, width, height))
  }
  return queryResults
}

function calculateQuery(
  key: string,
  val?: number | string,
  height?: number,
  width?: number
) {
  let retval
  switch (key) {
    case "maxWidth":
      retval = typeof val === "number" && width ? width <= val : undefined
      break
    case "minWidth":
      retval = typeof val === "number" && width ? width >= val : undefined
      break
    case "maxHeight":
      retval = typeof val === "number" && height ? height <= val : undefined
      break
    case "minHeight":
      retval = typeof val === "number" && height ? height >= val : undefined
      break
    case "orientation":
      if (val) {
        if (width && height && width > height) {
          retval = typeof val === "string" && val === "landscape"
        } else {
          retval = typeof val === "string" && val === "portrait"
        }
      }
      break
    default:
      break
  }
  return retval
}

Step 3: Update the import paths to match your project setup.

API Reference

To use this component in your project, include the following import statement in your file.

import { useMediaQuery } from "@/components/ui/utils/use-media-query"

const flexDir = useMediaQuery({
  minWidth: 480,
  maxWidth: 1280,
})

Hook Arguments

This section provides a comprehensive reference list for the hook arguments, detailing descriptions, properties, types, and default behavior for easy project integration.

useBreakPointValue

Name	Type	Default
options	{ [key: maxHeight \| maxWidth \| minHeight \| minWidth \| orientation] : value } Array<{ [key: maxHeight \| maxWidth \| minHeight \| minWidth \| orientation] : value }>	-

Return Value

The useMediaQuery hook returns an array of booleans, indicating whether the given query matches or queries match.

Why an array?

useMediaQuery accepts both an object and an array of object, but will always return an array. This way, you can combine multiple media queries which will be individually matched in a single call. The options to use are still limited to maxWidth, minWidth, maxHeight, minHeight, orientation.