Nicely Packaged Make

    react-superq
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.1 • Public • Published

    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>
    +   <MediaQueryProvider>
          <App />
    +   </MediaQueryProvider>
      </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 mvrlin@pm.me

    Install

    npm i react-superq

    DownloadsWeekly Downloads

    2

    Version

    1.0.1

    License

    MIT

    Unpacked Size

    37.7 kB

    Total Files

    7

    Last publish

    Collaborators

    • mvrlin