README.md

jsincss-element-query

An element query plugin for jsincss

About

This plugin is a JavaScript module that works with JS-in-CSS stylesheets, to add element query (container query) functionality to CSS.

Downloading

You can download jsincss-element-query and add it to your codebase manually, or download it with npm:

npm install jsincss-element-query

Another option that works for building or testing, that isn't ideal for production use, is linking to the module directly from a CDN like unpkg:

<script type=module>
  import element from 'https://unpkg.com/jsincss-element-query/index.vanilla.js'
</script>

Importing

This plugin exists in three different formats:

• CommonJS module: index.js
• Vanilla JS module: index.vanilla.js
• Browser function: index.browser.js

You can import this plugin using the native import statement in JavaScript. Here you can assign any name you want to the function you are importing, and you only need to provide a path to the plugin's index.vanilla.js file:

import element from './index.vanilla.js'

You can also use the CommonJS-formatted module located at index.js with require() for use with bundlers that don't use vanilla JS modules.

Once you have imported this plugin into your module, you can use the plugin as element()

Using JS-in-CSS Stylesheets

The main goal of this plugin is to allow CSS authors the ability to toggle stylesheets based on querying properties (like width, height, aspect-ratio, orientation, number of characters of text content, number of child elements, and scroll position) of elements as they are rendered in the browser.

The plugin has the following format:

element(selector, conditions, stylesheet)

• selector is a string containing a CSS selector
• condition is an object containing as many different feature queries as you want, all must pass for the stylesheet to apply
• stylesheet is a string or template string containing a CSS stylesheet, where :self is a selector that can be used to target the element(s) that pass the test

Features

• minWidth: number <= offsetWidth,
• maxWidth: number >= offsetWidth,
• minHeight: number <= offsetHeight,
• maxHeight: number >= offsetHeight,
• minChildren: number <= children.length,
• maxChildren: number >= children.length,
• minCharacters: number <= ((value && value.length) || textContent.length),
• maxCharacters: number >= ((value && value.length) || textContent.length),
• minScrollX: number <= scrollLeft,
• maxScrollX: number >= scrollLeft,
• minScrollY: number <= scrollTop,
• maxScrollY: number >= scrollTop,
• minAspectRatio: number <= offsetWidth / offsetHeight,
• maxAspectRatio: number >= offsetWidth / offsetHeight,
• orientation: 'portrait', 'square' ,'landscape'

Examples

This example will use the jsincss plugin to load a JS-in-CSS stylesheet making use of this plugin. To test it in a JavaScript module, import both the jsincss package and any helper plugins you want:

<script type=module>
  import jsincss from 'https://unpkg.com/jsincss/index.vanilla.js'
  import element from 'https://unpkg.com/jsincss-element-query/index.vanilla.js'

  jsincss(() => `

    ${element('div', {minWidth: 500}, `
      :self {
        background: lime;
      }
    `)}

  `)
</script>

It's also possible to write your stylesheets as a separate JavaScript module like this, where you import any helper plugins at the top of the stylesheet:

import element from 'https://unpkg.com/jsincss-element-query/index.vanilla.js'

export default () => `

  ${element('div', {minWidth: 500}, `
    :self {
      background: lime;
    }
  `)}

`

And then import both the jsincss plugin and the stylesheet into your code and run them like this, suppling any selector or events list the jsincss plugin might need to apply the stylesheet only the the element(s) and event(s) you require, depending on what you're doing:

import jsincss from 'https://unpkg.com/jsincss/index.vanilla.js'
import stylesheet from './path/to/stylesheet.js'

jsincss(stylesheet)

For a more advanced example, check out the test file which includes element-query.js and element-query-scroll.js and includes them in a module like this:

import jsincss from '//unpkg.com/jsincss/index.vanilla.js'
import stylesheet from './element-query-test.js'
import scrollStyles from './element-query-scroll-test.js'

jsincss(stylesheet)
jsincss(scrollStyles, ['[class*="-scroll-"]'], ['scroll'])

Compatible JS-in-CSS Stylesheet Loaders

• jsincss