npm version npm downloads License

?  React Super Simple Media Queries

Easy-to-use media queries for your React project

Features

  • ⚡️  Fast & Light with MatchMedia API ⚡️
  • ?  Auto detects the device viewport from Cookie & User-Agent
  • ?  Zero configuration to start
  • ?️  Supports IE9+

Quick Setup

  1. Add react-superq dependency to your project

# Using npm
npm add react-superq
# Using yarn
yarn add react-superq
# Using pnpm
pnpm add react-superq
  1. Wrap your application with MediaQueryProvider

+ import { MediaQueryProvider } from 'react-superq'

const root = ReactDOM.createRoot(document.getElementById('root'))

root.render(
  <React.StrictMode>
+   <MediaQueryManager>
      <App />
+   </MediaQueryManager>
  </React.StrictMode>
)
  1. Use useMediaQuery in any component!

// App.tsx

import React, { useMemo } from 'react'
import { useMediaQuery } from 'react-superq'

const App: React.FC = () => {
  const mediaQuery = useMediaQuery()

  // You can use it in your code.
  const isDesktopOrHigher = useMemo(() => {
    return mediaQuery.isLessThan('desktop') && mediaQuery.isGreaterThan('mobileWide')
  }, [mediaQuery.breakpoint])

  return (
    <div>
      <h1>This is my App!</h1>

      {/* Or directly in the markup! */}
      {mediaQuery.isLessThan('tablet') && <div>I will be visible only on mobile!</div>}
    </div>
  )
}

Quick Setup for Next.JS

  1. Add react-superq dependency to your project

# Using npm
npm add react-superq
# Using yarn
yarn add react-superq
# Using pnpm
pnpm add react-superq
  1. Wrap your application with MediaQueryProvider & initialize the MediaQueryManager (for SSR)

Before

// pages/_app.tsx

function MyApp({ Component, pageProps }: AppProps) {
  return (
    <Component {...pageProps} />
  )
}

After

// pages/_app.tsx

import { MediaQueryManager, MediaQueryProvider } from 'react-superq'

type InitialProps = {
  contextBreakpoint: string
}

const mediaQueryManager = new MediaQueryManager()

function MyApp({ Component, contextBreakpoint, pageProps }: AppProps & InitialProps) {
  return (
    <MediaQueryProvider contextBreakpoint={contextBreakpoint}>
      <Component {...pageProps} />
    </MediaQueryProvider>
  )
}

// Detect the breakpoint on the server.
MyApp.getInitialProps = async ({ ctx }: AppContextType) => {
  const contextBreakpoint = await mediaQueryManager.detectBreakpoint(
    ctx.req?.headers.cookie,
    ctx.req?.headers['user-agent'],
  )

  return {
    contextBreakpoint,
  } as InitialProps
}

Tune-up the MediaQueryManager

Note You can initialize an endless amount of MediaQueryManager, but each new one will refer to the first one.

const mediaQueryManager = new MediaQueryManager({
  // ...
})

Configuration

breakpoints

  • Type: Object

An object where the key is the name of the mediaQuery, and the value is the breakpoint size.

cookieName

  • Type: String
  • Default: breakpoint

The key for the document cookie.

defaultBreakpoints

  • Type: Object
  • Detectable devices: console, desktop, embedded, mobile, smarttv, tablet, wearable

An object where the key is the name of the detected device, and the value is the breakpoint key.

fallbackBreakpoint

  • Type: String
  • Default: desktop

The breakpoint key to be used, if the device was not detected.

Default configuration

{
  breakpoints: {
    desktop: 1024,
    desktopMedium: 1280,
    desktopWide: 1600,

    mobile: 320,
    mobileMedium: 375,
    mobileWide: 425,

    tablet: 768,
  },

  cookieName: 'breakpoint',

  defaultBreakpoints: {
    desktop: 'desktop',
    mobile: 'mobile',
    tablet: 'tablet',
  },

  fallbackBreakpoint: 'desktop',
}

Presets

API

MediaQueryManager

  • detectBreakpoint(cookie?: string, userAgent?: string): Promise<string>
  • getMediaQueries(): Record<string, string>
  • usePreset(key: keyof typeof PRESETS): MediaQueryManager<Record<string, number>>

MediaQueryManagerOptions

  • defaultBreakpoints: Partial<Record<'console' | 'desktop' | 'embedded' | 'mobile' | 'smarttv' | 'tablet' | 'wearable', string>>
  • breakpoints: Record<string, number>
  • cookieName: string
  • fallbackBreakpoint: string

useMediaQuery

  • readonly breakpoint: string
  • isGreaterThan(input: string): boolean
  • isGreaterOrEquals(input: string): boolean
  • isLessThan(input: string): boolean
  • match(input: string): boolean
  • matches(...input: string[]): boolean

License

MIT License

Copyright (c) mvrlin [email protected]

GitHub

View Github