Using Selector-Query for Responsive, Column-Driven Layouts

We've all heard about media queries. We've used them extensively in our themes to make them responsive. They're great for most purposes, but when it comes to column-driven layouts, we sometimes need more control to make our designs stand out.

In this article, you will learn about the Selector-Query jQuery plugin, and how to use it in your WordPress themes.

What is it? Well, think of it as something like media queries, but instead of using the browser width as the reference, it uses the element's current width.

What Are Media Queries?

Before we head on to the nitty gritty of Selector-Query, let's first talk about what media queries are. In a nutshell, media queries allow styles in your CSS to be applied only when the browser's width gets within a certain range.

Media queries are the heart and soul of responsive design. Within just a single webpage and CSS file, we can make it display differently when viewed with different screen resolutions and devices. With media queries, there's no need to create two different desktop and mobile versions of a website.

Let's take a quick review on its usage. For desktops and tablets, we can wrap our CSS rules with the following media query. The CSS below would be followed for browser widths of 768px and above:

For smaller devices such as smart phones, we can use the following. This one would be followed for widths of 767px and below:

We Want More Control

When designing websites, we can adjust our design to exactly the way we want it to look at different screen sizes by using media queries. However, when it comes to designing WordPress themes, we need more control.

As WordPress theme authors, we want our themes to be both flexible and look awesome at the same time. We put in features like shortcodes and multi-column layouts, and we give our users the freedom to do whatever they want.

The happier the customer, the happer we are.

Example: Testimonial Content

Let's say for example, one of our customers wanted to put a testimonial shortcode inside a full-width column. Let's say we only designed this shortcode to be placed side-by-side with other testimonials (or any other content) within 3 or more columns:


For this certain scenario, it might be better if there was a different design when the testimonial shortcode was placed in a larger container. Perhaps a design like this would be better for a full-width column:


Unfortunately, media queries won't be able to help in this one. Why? Because the screen width is still the same whether the testimonial was placed in a full-width column or a one-third column!

Okay, so you might be thinking, "How about just using the column's class in the CSS?" You'll probably end up with something like this in your CSS file:

Well, something like the CSS above would work. However, I have a more elegant proposal: Selector-Query.

The Selector-Query jQuery Plugin

Selector-Query is a lightweight jQuery plugin that allows different styles to be applied to your elements based on their width.

Basically, what this plugin does it apply additional class names to your elements depending on their current width. When the browser gets resized, the class names are updated appropriately to reflect the new element width.

You can then use these different class names to style the different layouts for your content.

What Selector-Query does is wait for debounced browser resize events, then it takes the width of your HTML elements and checks them against an array of widths called widthStops. If the element width is below any of these widthStop values, the class names of the larger ones are added to the element.

I will explain widthStops later with an example, for now let's talk about how to use the plugin.

Selector-Query Usage

The first thing we need to do is to include the jQuery plugin script. You can download Selector-Query from its GitHub repo then include it in your theme directory. Place it in your js folder to keep your file structure clean.

Once you have it in your theme directory, you can add this code in your functions.php to enqueue Selector-Query right before the body is closed. This would save us some page load time:

Enabling the jQuery plugin is simple. All you have to do is call selectorQuery on your elements:

And that's it!

Additionally, the plugin has two configurable options that you can pass during initialization.

You can customize these values to your liking:

widthStops are the widths used to check the element's width against. The classPrefix is used together with widthStops to generate the class names. Let's check out an example to explain things better.

Example: Testimonial Content Redux

Let's use our testimonial example above and apply Selector-Query to it so that we can get a clearer picture of how it works and how we can benefit from it. For example, let's say that our testimonial's HTML is written like this:

If our testimonial div had a width of 1000px, using the default values for widthStops above, Selector-Query would add some new class names to it. We would end up with:

Then if the testimonial div gets resized smaller to 800px, it would then look like this:

We can use these dynamically added class names to style different layouts for our testimonial. We can use .max-1024 to style widths of 1024 and larger; and we can use .max-960 to override styles for our smaller designs.

If we were to design the testimonial content like this:


We can use this one as our CSS:

The best thing about using Selector-Query is that we don't need to know where this testimonial content is placed. It will get styled depending on its width, unlike in our earlier CSS where our design for the large testimonial content depended on its parent (remember we used .one-column .testimonial in the earlier example).


In this article, we learned of a new way of styling our content depending on their width with Selector-Query. Hopefully, you would find some awesome use for this jQuery plugin in your designs.

If you want a live sample of Selector-Query in action, you can check out the demo in the Github repo.

I hope you enjoyed this article. I highly appreciate any feedback, comments and suggestions. Let me know what you think of Selector-Query.

Will you be using this plugin in one of your upcoming WordPress themes? Share your thoughts below!



Related Articles