PicturePerfect.js

Get your images to fit in their container. Squares? Circles? No problem.

What's New Download ZIP Download TAR Ball View On GitHub

PicturePerfect.js is a jQuery plugin that detects whether or not a picture is landscape (wider than it is tall) or portrait (taller than it is wide) and then sizes it appropriately to fit circle or square containers.

Why? Because circles and squares are so hot right now but image assets are never delivered as perfect squares.

Say You Have a Bunch of Images

And they're all going to need to fit into circles. You have one image to use as an example:

I can do this with CSS, you think. This will be easy. Sure enough:

Great! Nothing to it. Then the client sends you a new image. Can you test this one, too?

No problemo! The CSS is already there, so you just have to stick it in the same DOM elements, right?

Wait. What? Cary is cut off at the bottom! This will not do. Of course, Cary is a landscape/horizontal image, so he needs his height set to 100%. But Audrey up top is a portrait/vertical image, so she needs her width set to 100%. What if we set both the height and width to 100%?

Well that doesn't work; they look all distorted! We need a solution that fits any orientation of image inside its container. That's where PicturePerfect.js comes in. Simply initiate it on your container div, and your images will fit in their containers no matter what odd shape the client sends them in. So all these images:

Will look like this:


They're even centered!

What about rectangles and ovals?

Rectangles and ovals are no problem! In fact, you can have a bunch of differently sized containers all holding randomly sized images and PicturePerfect will size and center them all.

Get Started

Ready to use PicturePerfect.js? Getting setup is easy!

Step 1: Install Dependencies

PicturePerfect.js depends on jQuery and the imagesLoaded plugin. Make sure you have them loaded before PicturePerfect.js in your document.

Step 2: Download PicturePerfect.js and Include it in your Document

Step 3: Get your DOM and CSS Ready

For PicturePerfect.js to work correctly, you'll need to make sure your images are correctly placed in your DOM and you're styling them correctly.

For the DOM setup, you should have each image inside of a container:


                <div class="image-container">
                  <img src="images/my-image.jpg"/>
                </div>
                <div class="image-container">
                  <img src="images/another-image.jpg"/>
                </div>

For the CSS, set the container to the specific height and width you want your images to be, set the overflow to hidden, and add a border radius if you want your images to appear as circles or ovals. The image should be initialized to have a height and width of auto (default) and a relative position. 


                  .image-container {
                    border-radius: 50%;
                    height: 200px;
                    margin: 0 auto;
                    overflow: hidden;
                    width: 200px;
                  }

                  .image-container img {
                    position: relative;
                  }

Step 4: Call the Function on your Container

Call the picturePerfect function on the element which contains the images you want to contain.


                $('.picture-perfect').picturePerfect();

And you're good to go!

Options

selector: string - set the selector (class) of your image container. (default: .image-container)
centered: bool - set if images will be centered in their containers or not. (default: true) 


                $('.picture-perfect').picturePerfect({
                  selector: '.image-container',
                  centered: true
                });