Vue Container Query 2

🧐 Because vue-container-query was taken, and API is a little like vue-container-query package. So, thank you the maintainer.

Vue plugin for working with css container query as easy as possible.

💥 This is the beta version. It's safe for production, but keep an eye on documentations if you wanted to upgrade the package. There probably will be breaking changes in first major release

Installation

npm install vue-container-query-2
// or
yarn add vue-container-query-2

This is also available on jsdeliver and unpkg.

Usage

Import and register the vue-container-query-2 plugin first.

import VueContainerQuery from 'vue-container-query-2';
Vue.use(VueContainerQuery, options);

And :tada: voila, now you have a cq option in every SFCs like below

export default {
  name: 'SearchField',
  cq: {
    large: { minWidth: 900 },
    medium: { maxWidth: 600 },
    small: { maxWidth: 460 }
  },
  data() {
      return {}
  },
  ...

:warning: for maxWidth you get <=, but for minWidth it's > and no =. So the behavior is not quite like CSS Media Queries. Although it's a little bit more well formatted. But it may change during next major release. so, heads up.

After defining breakpoints, you'll have reactive $cq variable in your component. You can use this anyhow you need. Maybe dynamic classes, maybe show/hide other element or components, whatever.

<div
    :class="{
        'search--small': $eq.small
    }
>
    <span v-if="$eq.large">
        Yo. I only get rendered if the componenet is 900px or wider
    </span>
</div>

This is a sample of how $eq object looks like in the instance's context:

{
    contentRect: {
        x:0,
        y: 0,
        width:1300, 
        height: 2124, 
        top: 0,
        right: 1300,
        bottom: 2124,
        left:0
    },
    breakpoints: {
        large: { minWidth: 900 }
        medium: { maxWidth: 600 },
        small: { maxWidth: 460 }
    },
    resizeObserver: [object ResizeObserver],
    large: true
    medium: true,
    small: false
}

Options

This is default options:

{
    classNames: {
        sizes: {
            xsmall: 'xsmall',
            small: 'small',
            medium: 'medium',
            large: 'large',
            xlarge: 'xlarge'
        },
        prepend: ''
    },
    useBEM: true,
    utilityClassNamesRegex: /$^/,
    ignoredClasses: ['']
}

You can override these when registering the plugin:

Vue.use(VueContainerQuery, {
  classNames: {
    sizes: {
      xsmall: 'size:xsmall',
      small: 'size:small',
      medium: 'size:medium',
      large: 'size:large',
      xlarge: 'size:xlarge'
    }
  },
  useBEM: true,
  utilityClassNamesRegex: /u-/g,
});

☝ All options are only useful when you are using v-cq directive. the core works fine without any provided option

useBEM

If this set as true, the classes will respect the BEM convention. Say your element has search class, then when small condition is on, a search--small class adds to element. VCQ is smart enough to ignore -- classes when generating new class names. But if your element has multiple classes like search header, you will get both search--small and header--small. so if you are using useBEM make sure you implement the true BEM. otherwise this plugin won't work that nice.

utilityClassNamesRegex

You can set a regex to ignore any sort of utility class that you don't want to consider as semantic class.

ignoredClasses

You can set an array to ignore any sort of class that you don't want to consider as semantic class.

Directive

This may be the best feature of thin package. There also is a handy v-cq directive available to automate the process of setting size classes. so, all you need to make the element to get size classes is like below:

<div
    v-cq
    class="card"
>
    ...
></div>

<!-- <div class="card card--small"><div> -->
<!-- <div class="card card--medium"><div> -->
<!-- <div class="card card--large"><div> -->

See there? no :class and checking for $cq.small or anything. size classes will automatically get calculated and attached to element. remember that size classes are based on what you did set in options, if not, default ones as fallback.

👨‍💻 ToDo

• [ ] Add unit tests.
• [x] Detect utility classes to prevent adding "size classes" to them.
• [x] Add option to explicitly mention main class name. It's very useful if you're using utility first CSS classes.