Usage

The frame object is used to create a rectangle that acts as a window onto any content we place behind it. It allows us to constrain the content to a particular aspect ratio without squashing or distorting the content.

The most common use case for a frame is to ensure images in a grid are the correct aspect ratio.

See customization options for more information on customizing the frame ratios.

How cropping is done

Content inside a frame is automatically cropped to the aspect ratio defined by the frame.

For replaced elements, such as img and video, this is done by setting the width and height to 100% and giving it object-fit: cover.

/* This is how a frame automatically crops your images and video */
.frame > img, .frame > video {
  height: 100%;
  width: 100%;
  object-fit: cover;
}

For these elements, you can use Tailwind's object-position utilities to change the cropping position. By default, this is 50% 50%, or object-center.

For non-replaced elements, object-fit doesn't apply. Instead, flex is used to achieve the same effect, via align-items and justify-content.

Flex has no effect on replaced-elements, so it safely targets any immediate child using > *.

/* This is how a frame automatically crops all other content */
.frame > * {
  display: flex;
  justify-content: center;
  align-items: center;
}

Modifiers

Ratio

The frame class also includes ratio modifiers out of the box. The default config creates classes for a 1:1 square, a 16:9 rectangle, and the golden ratio 1.618:1.

A frame without a modifier defaults to a rectangular 16:9 ratio. This is true even if 16:9 isn't defined in your tailwind config.

See customization options for more information on customizing the frame ratios.

Responsive

The frame object can have its ratio set at different breakpoints:

<div class="ratio md:ratio--4:3 xl:ratio--16:9">
  <div>...</div>
  <div>...</div>
</div>

Customizing

Ratio

To change the ratios available to the frame class, specify the name and ratio using the ratio option in the theme.frame section of your config file:

// tailwind.config.js
module.exports = {
  theme: {
    frame: {
+     ratio: {
+       '1:1': '1:1',
+       '16:9': '16:9',
+       golden: '1.618:1',
+     },
    }),
  },
}

This would produce the following frame modifiers:

<div class="frame frame--1:1"></div>
<div class="frame frame--16:9"></div>
<div class="frame frame--golden"></div>

Variants

By default, only responsive variants are generated for frame utilities.

You can control which variants are generated for the frame utilities by modifying the frame property in the variants section of your tailwind.config.js file.

For example, this config will disable all variants:

  // tailwind.config.js
  module.exports = {
    variants: {
      // ...
+     frame: [],
    }
  }

Disabling entirely

If you don't plan to use the frame utilities in your project, you can disable them entirely by setting the frame property to false in the captain.plugins section of your config file:

  // tailwind.config.js
  module.exports = {
    captain: {
      plugins: {
        // ...
+       frame: false,
      }
    }
  }