Giter Club home page Giter Club logo

fine-mq's Introduction

fine-mq

A fine API to use media queries in JS with ease and with first-class integration with Vue.js/Nuxt.js.

Read the doc here.

# Install using NPM or Yarn:
npm i --save fine-mq
# or
yarn add fine-mq

Usage

In JS

import { createFineMediaQueries }  from 'fine-mq'

const mq = createFineMediaQueries({
  // Fine Mq supports modifiers for sizes shortcuts  (see below for examples)
  sm: 680, // <=> [0, 680]
  md: [681, 1024],
  lg: [1025], // <=> [1025, Infinity]
  landscape: '(orientation: landscape)',
  custom1: 'only screen and (max-width: 480px)',
  custom2: 'only screen and (min-width: 480px) and (max-width: 720px)',
  an_alias_object: {
    screen: true,
    minWidth: '23em',
    maxWidth: '768px'
  }
})

// => This example will register the following aliases:
// {
//   sm: '(max-width: 680px)',
//   'sm+': '(min-width: 681px)',
//   md: '(min-width: 681px) and (max-width: 1024px)',
//   'md+': '(min-width: 1025px)',
//   'md!': '(min-width: 681px)',
//   lg: '(min-width: 1025px)',
//   landscape: '(orientation: landscape)',
//   an_alias_name: 'screen and (min-width: 380px) and (max-width: 768px)'
// }

// !: means «current and above»
// +: means «above»

const defaultColor = '#FFF'

const changeColor = color => ({ matches, mediaQuery, alias }) => {
  document.body.style.backgroundColor = matches ? color : defaultColor
}

mq.on('small', changeColor('blue'))
mq.on('medium', changeColor('green'))
mq.on({
  screen: true,
  maxWidth: '1200px'
}, changeColor('cyan'))
mq.on('only screen and (min-width: 720px)', changeColor('red'))
mq.off('only screen and (min-width: 720px)')

NOTE 1: Absurd modifiers will not be created for (ex: when the lower bound is 0, there is no need for the «!» modifier, or if the upper bound is Infinity, there is no need for both «!» and «+» modifiers).

NOTE 2: If you specify the unit for your size (px, em, rem), the + 1 operation will not be performed for modifiers.

See FineMq for details about the API.

As a Vue plugin

import { FineMqPlugin } from 'fine-mq'


// Define your aliases as plugin options (defaults to `{ sm: 680, md: [681, 1024], lg: [1025] }` for Vue.js only, not the JS API)
Vue.use(FineMqPlugin, {
  aliases: {
    sm: 680, // <=> [0, 680], can also be a size in px, em or rem
    md: [681, 1024],
    lg: [1025], // <=> [1025, Infinity]
    landscape: '(orientation: landscape)',
    an_alias_name: {
      screen: true,
      minWidth: '23em',
      maxWidth: '768px'
    }
  }
  // Define the default values for your matching aliases for SSR
  defaultMatchedMediaQueries: {
    sm: false,
    md: false,
    lg: true,
  }
})

// Three reactive properties will then be available on Vue instances:
// - `$mq` is an object that contains the matching state for each alias in the form { [alias]: true/false }.
// - `$lastActiveAlias` will contain the last alias that was matched and triggered by the listener.
// - `$fineMq` is a FineMq instance for advanced usages.

With Nuxt.js

// In your nuxt.config.js
export default {
  // ...
  
  // Build Configuration (https://go.nuxtjs.dev/config-build)
  build: {
    transpile: ['fine-mq'],
  },
  
  modules: ['fine-mq/nuxt'],

  // Pass options here
  fineMq: {
    defaultMatchingAliases: {
      md: true,
    },
    aliases: {
      sm: 640,
      md: [641, 768],
      lg: [769, 1024],
      xl: [1025, 1280],
      '2xl': [1281],
    },
  },

  // ...
}

FineMq API

const mq = createFineMediaQueries(aliases, defaultMatchedMediaQueries)

Initialize helpers for your media query aliases. Other aliases can be registered afterwards.

defaultMatchedMediaQueries is for universal apps that need default values on SSR.

mq.addAlias(alias[, query]) / mq.removeAlias(alias)

Register an alias for a query, or register multiple aliases at once by passing an object.

mq.addAlias('small', '(max-width: 100px)')
mq.addAlias({
  small: '(max-width: 100px)',
  medium: {
    screen: true,
    maxWidth: 200
  },
})

Then you can unregister previously registered aliases with mq.removeAlias(alias).

mq.on(query, callback)

Register a callback which will be executed everytime the match state (true/false) for a query or alias changes.

// `alias` is the given alias, mediaQuery is the actual media query matched and `matches` is a boolean indicating the match state.
mq.on('(max-width: 400px)', ({ matches, alias, mediaQuery }) => {})
const unregister = mq.on('smartphones', ({ matches, alias, mediaQuery }) => {}, {})

unregister() // this removes the handler you just added.

mq.off(query, callback)

Remove all handlers for all media queries:

mq.off()

Remove all handlers for a media query or alias:

mq.off('(max-width: 400px)')
mq.off('small')

Remove a specific handler for a query or alias:

mq.off('(max-width: 400px)', myHandler)
mq.off('small', myHandler)

Browser Support

This library relies on matchMedia API to detect screensize change. You can use a polyfill if you need this package to work for older browsers. Check this out: Paul Irish: matchMedia polyfill

Credits

This package is highly inspired by the work made on other packages (links below), I just shamelessly copied their work and combined them !

Contributing

Please open an issue for support. Thanks in advance for any kind of contribution !

  1. Fork it!
  2. Create your feature branch: git checkout -b my-new-feature
  3. Commit your changes: git commit -am 'Add some feature'
  4. Push to the branch: git push origin my-new-feature
  5. Submit a pull request :D

fine-mq's People

Contributors

nash403 avatar semantic-release-bot avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar

fine-mq's Issues

[Question] $fineMq reactive prop undefined / Register .on callback with plugin

  • I'm submitting a ...
    [x] question about how to use this project

  • Summary
    The Readme tells me that I have the following three instances available:

// Three reactive properties will then be available on Vue instances:
// - $mq is an object that contains the matching state for each alias in the form { [alias]: true/false }.
// - $lastActiveAlias will contain the last alias that was matched and triggered by the listener.
// - $fineMq is a FineMq instance for advanced usages.

Now I can access
context.root.$mq and context.root.$lastActiveAlias but I can't access
context.root.$fineMq because this is undefined.

I am using fineMq as a plugin and I would like to register an .on callback, now I don't really know how I could register that..

import Vue from 'vue'
import FineMq from 'fine-mq'

Vue.use(FineMq, {
  aliases: {
    mobile: 574,
    tablet: [575, 1024],
    mobilefooter: 1024,
    desktop: [1025, 1279],
    mobilenav: 1279,
    widescreen: [1280, 1365],
    ipadpro: [1366],
    landscape: '(orientation: landscape)'
  }

And than later on within a composable of my composition api I would like to register this .on callback, but I don't know how to achieve that.

Help is very welcome. Thank you in advance.

Cheers

Add a «-» modifier that would mean "everything under my upper bound" ?

Example

For default aliases, it would generate for example the following queries:

{
  sm: '(max-width: 680px)',
  'sm+': '(min-width: 681px)',
  md: '(min-width: 681px) and (max-width: 1024px)',
  'md-': '(max-width: 1024px)',
  'md+': '(min-width: 1025px)',
  'md!': '(min-width: 681px)',
  lg: '(min-width: 1025px)',
  'lg-': '(max-width: 1024px)',
  landscape: '(orientation: landscape)',
  an_alias_name: 'screen and (min-width: 380px) and (max-width: 768px)'
}

Special rules

It wouldn't generate a «-» modifier for sm because it's lower bound is 0.
But lg- is generated for lg because lg's upper bound is Infinty.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.