tailwindcss-container-query

A plugin that provides CSS Container Queries.

BEFORE STARTING

This plugin relies on container-query-polyfill. You must add it to make this plugin work. We have to rely on polyfills until all browsers have implemented them. see the support table

Installation

Install the plugin from npm:

# Using npm
npm install tailwindcss-container-query

# Using Yarn
yarn add tailwindcss-container-query

Then add the plugin to your tailwind.config.js file:

// tailwind.config.js
module.exports = {
  theme: {
    // ...
  },
  plugins: [
    require('tailwindcss-container-query'),
    // ...
  ],
}

Usage

Container Queries up to 10 are generated by default:

| Class | Query | | --- | --- | | cq-w-4 | @container (min-width: 64px) | | cq-w-6 | @container (min-width: 96px) | | cq-w-9 | @container (min-width: 144px) | | cq-w-16 | @container (min-width: 256px) | | cq-w-22 | @container (min-width: 352px) | | cq-h-4 | @container (min-height: 64px) | | cq-h-6 | @container (min-height: 96px) | | cq-h-9 | @container (min-height: 144px) | | cq-h-16 | @container (min-height: 256px) | | cq-h-22 | @container (min-height: 352px) |

Utilities:

| Class | Property | | --- | --- | | container-type-size | container-type: size | | container-type-inline-size | container-type: inline-size | | container-type-block-size | container-type: block-size | | container-type-style | container-type: style | | container-type-state | container-type: state |

There are no any container-name utilities by default. You should define your own utilities in tailwind.config.js.

Example Usage

<div class="overflow-auto bg-gray-300 resize h-60 w-60 container-type-size">
  <h1 class="bg-green-300 cq-w-6:bg-yellow-400">Resize the container and see the background color change</h1>
</div>

.cq-w-6:bg-yellow-400 output:

@container (min-width: 96px) {
  .cq-w-6\:bg-yellow-400 {
    --tw-bg-opacity: 1;
    background-color: rgb(96 165 250 / var(--tw-bg-opacity));
  }
}

You can use arbitrary variants too. (You should be using v3.1.0 or higher!)

<div class="cq-w-[238px]:bg-yellow-400"></div>

.cq-w-6:bg-yellow-400 output:

@container (min-width: 238px) {
  .cq-w-\[238px\]\:bg-yellow-400 {
    --tw-bg-opacity: 1;
    background-color: rgb(96 165 250 / var(--tw-bg-opacity));
  }
}

Using Container Names

<div class="overflow-auto bg-gray-300 resize h-60 w-60 container-type-size container-name-sb">
  <h1 class="bg-green-300 cq-w-sb-6:bg-yellow-400">Resize the container and see the background color change</h1>
</div>

// tailwind.config.js
module.exports = {
  theme: {
    containerName: {
      sb: 'sidebar'
    },
    // ...
  }
}

.cq-w-sb-6:bg-yellow-400 output:

@container sidebar (min-width: 96px) {
  .cq-w-sb-6\:bg-yellow-400 {
    --tw-bg-opacity: 1;
    background-color: rgb(96 165 250 / var(--tw-bg-opacity));
  }
}

Configuration

You can configure which values and variants are generated by this plugin under the containerQuery, containerType and containerName keys in your tailwind.config.js file:

// tailwind.config.js
module.exports = {
  theme: {
    // P.S. Container Query thresholds can only be specified using pixels because of the polyfill I recommended.
    containerQuery: {
      xs: '120px',
      sm: '240px',
      md: '360px',
    },
    containerType: {
      size: 'size',
    }
  }
}

Demo Page