panoply / qvp

💻 A tiny (1.2kb gzipped) media query utility for programmatic control of screen viewports.

qvp

A tiny (1.2kb gzipped) media query utility for programmatic control in different screen viewports within the browser.

Install

The module is shipped for ESM consumption in the Browser.

pnpm add qvp

Flems Playground

Basic Usage

The module uses a single default export, so assign a default. There a 3 different different option schemas available.

import qvp from 'qvp';

// OPTION 1 ~ Events

qvp({
  sm: '(max-width: 576px)',
  md: '(min-width: 768px) and (max-width: 992px)'
});

// OPTION 2 ~ Methods

qvp([
  {
    id: 'sm',
    query: '(max-width: 576px)',
    onenter: () => {
      console.log('Screen size is below 576px');
    },
    onexit: () => {
      console.log('Screen size is above 576px');
    }
  },
  {
    id: 'md',
    query: '(min-width: 768px) and (max-width: 992px)',
    onenter: () => {
      console.log('Screen size above 768px but below 992px');
    },
    onresize: x => {
      console.log('Screen size is: ' + x);
    },
    onexit: () => {
      console.log('Left the viewport');
    }
  }
]);

// OPTION 3 ~ Specific

qvp({
  id: 'sm',
  query: '(max-width: 576px)',
  oninit: () => {
    console.log('Screen size is below 576px');
  },
  onenter: () => {
    console.log('Screen size is below 576px');
  },
  onexit: () => {
    console.log('Screen size is above 576px');
  }
});

Methods

The module provides several helpful methods for querying and retrieving context of the browsers screen.

import qvp from 'qvp';

qvp.on(event, callback, scope?)       // Method event listening
qvp.off(event, callback | number)     // Remove event emitter
qvp.add(id, {})                       // Extends the screen with new methods
qvp.get(id)                           // Returns the viewport and screen matching the id
qvp.active()                          // List of active screens or single screen
qvp.active(id)                        // Boolean indicating whether the screen is active
qvp.list()                            // List of viewport screens states
qvp.list(ids[])                       // List of viewport screen states matching the ids
qvp.test(id | id[], separator?)       // Test utility for validating screens
qvp.remove(id)                        // Remove a viewport matching the id from store
qvp.destroy()                         // Tear down and remove all instances

Events

Event listeners will fire methods as events. Media query matches will emit and invoke for all defined screens and can be sepcified using the id:method name. The qvp.on()

import qvp from 'qvp';

// Define a set of queries and identifiers
qvp({
  tablet: '(min-width: 768px) and (max-width: 991px)',
  desktop: '(min-width: 992px)'
})

// Events will also fire when using method schema
qvp({
  id: 'mobile',
  query: '(max-width: 777px)',
  oninit: () => {
    console.log('Screen size is below 777px');
  }
})

// ...

// Listen for event methods
qvp.on('desktop:oninit', () => {});
qvp.on('desktop:onenter', () => {});
qvp.on('desktop:onexit', () => {});
qvp.on('desktop:onresize', (screenX) => { console.log(screenX) });

// Optionally bind context to the events
class Component {

  constructor () {
    this.value = 'Hello World!'
    this.event = qvp.on('mobile:onenter', this.method, this) // bind context to callback
  }

  method () {
    console.log(this.value) // logs "Hello World!"
  }

  disconnect () {
    qvp.off(this.event) // remove this event
  }

}

// Listen for resizes
qvp.on('tablet:onresize', (screenX: number) => {

  if(screenX > 800) {
    console.log('Screen size is: ', screenX)
  }

})

qvp.on('mobile:onexit', function () {

  console.log(this.context) // logs "foo"
  console.log(this.binding) // logs "bar"

}, {
  context: 'foo',
  binding: 'bar'
})

Store

The module maintains a store within a constant named viewports which you can access as a named import. The store is maintained within a Mapand each key value uses the screen ids, that values hold the screen instances.

import qvp from 'qvp';

qvp.viewports.forEach(viewport => {


  // SCREEN INSTANCE

  viewport.screen            // The screen instance
  viewport.screen.id         // The screen id value
  viewport.screen.query      // The media query value
  viewport.screen.active     // A boolean value indicating whether the viewport is active
  viewport.screen.oninit     // A Set list of methods to invoke oninit
  viewport.screen.onenter    // A Set list of methods to invoke onenter
  viewport.screen.onexit     // A Set list of methods to invoke onexit
  viewport.screen.onresize   // A Set list of methods to invoke when resizing
  viewport.screen.events     // Event listeners store (also available on viewport.events)

  // EVENTS EMITTERS

  viewport.events            // Event listeners store (same as viewport.screen.events)

  // METHOD TRIGGERS

  viewport.oninit()          // Calls all methods in screen.oninit Set (null if already invoked)
  viewport.onenter()         // Calls all methods in screen.onenter Set
  viewport.onexit()          // Calls all methods in screen.onexit Set
  viewport.onresize()        // Calls all methods in screen.onresize Set

})