react-superq

🌈  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

2. Wrap your application with MediaQueryProvider

+ import { MediaQueryProvider } from 'react-superq'

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

root.render(
  <React.StrictMode>
+   <MediaQueryProvider>
      <App />
+   </MediaQueryProvider>
  </React.StrictMode>
)

3. 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

2. 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

• Base
• TailwindCSS

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 [e-mail]