If used effectively, images can serve much more of purpose than making your design look great. Images add visual interest and can bring your department, center, or office to life.

Adding Images

All images available for use on your site are part of the Media Library. Images can be uploaded there, but often you will instead be uploading them directly when you need to use one. It's important to note that no matter how you uploaded the image, it's always part of the media library and can be reused in many areas of your site.

For example, most content types have a Featured Image field which has a button to either select an existing image from your media library or to upload a new image right there. You can also upload an image when embedding it in the WYSIWYG text editor in the main body of your page or other content.

When images are uploaded, the website stores the original copy and uses it to create smaller, sometimes cropped, versions of it depending on where it's displayed.

No matter how you upload a new image, you'll always be presented a form with the following fields:


A descriptive name for the image. This may be pre-filled with the filename of the image you uploaded, but it's typically better to use a more human-readable name. This is to help content editors find the image easily and to keep your media library organized.

Alternative (Alt) Text

Adding alternative text (alt text) for images is an important aspect of web accessibility. Alt text provides a textual alternative to non-text content in web pages. Alt text is used by screen readers, search engines, and when the image cannot be loaded for any reason. By adding alt text you can also improve search engine optimization (SEO).

In some situations, it's not appropriate to provide alt text. In these situations, you can check the Decorative checkbox to indicate the image is decorative and should not have alternative text provided. You are encouraged to read more about decorative images to better understand how they should be used.


A caption can be added to all images, but it may or may not be displayed depending on the context. The appearance of your image caption will also be determined by your theme.

Image File Size, Type, Resolution, and Aspect Ratio Requirements

When selecting images to upload to your site, users often have a lot of questions, like how large the image should be in pixels. There is not one right answer to such questions, but these general guidelines can help:

  • Type: You can upload images in PNG, GIF, or JPEG formats. JPEG (.jpg or .jpeg) files are the most common.
  • Size: The maximum image file size you can upload is 15 megabytes, but in most cases the images you upload should not be larger than 1 or 2 megabytes.
  • Maximum resolution: No higher than 4000 pixels wide by 2250 pixels high. You can in fact upload images that are larger than this, but the original copy that gets stored on your website will be down-scaled to fit within those dimensions, reducing quality (and then down-scaled again when it's actually output, reducing quality even further). You may get an error if you try uploading an image that's way too large in resolution or file size.
  • Minimum resolution: There's no minimum, but WDS recommends no lower than 750 pixels wide by 750 pixels high. Smaller resolution images will not look sharp on modern displays.
  • Aspect Ratio: This always depends on how the image will be used on your site. If you're site is configured to display images in a portrait aspect ratio, it's best to upload an image in that aspect ratio. However, Princeton Site Builder will automatically crop the image to fit aspect ratio that you configure it to display in.

Aspect Ratios Available for Output

As mentioned above, your website stores the original, unmodified version of images you upload. However, this original image is almost never output on your website directly. It's typically cropped and scaled down to fit depending on the context.

There are several possible aspect ratios an image can be output as on your site:

  • Super Wide (8:3)
  • Wide (16:9)
  • Landscape (3:2)
  • Landscape (4:3)
  • Square (1:1)
  • Portrait (3:4)

In addition to those options, you'll sometimes also be able to output an image as "freeform". This is a unrestricted aspect ratio option that, by default, uses the original aspect ratio of your image and simple scales it down as needed.

Cropping Images

When images are output on your site, you typically have a choice for what aspect ratio to output them as. For example, when adding a Featured Image to a Page, you have a choice to display it using 16x9 or 8x3 aspect ratios.

To support all the various options that are presented for outputting images, your website will automatically crop the original image you uploaded to fit the selected aspect ratio. It does this by treating the center of the image as the most important and cropping away the edges as necessary.

Sometimes the automatically applied crop is not desirable. This is most common when uploading an image that is in a wide aspect ratio and trying to use it in a tall aspect ratio.

To resolve this problem, you can control how the image is cropped so it will focus on a different area of the image instead:

  1. Find the image in the media library and edit it.
  2. Expand the "Crop" section to reveal a list of aspect ratios on the left and a crop tool on the right.
  3. Select the aspect ratio you intend to output the image with on the left.
  4. Drag a box over the image preview on the right to achieve the desired crop.
  5. Save.

If your image is displayed in multiple aspect ratios on your site, you can create your own crop for each ratio.

Using Images

Images can be used on numerous ways on your site. Here's a few examples:

  • As a Featured Image on content.
  • Embedded in the main text of a A individual item of content. For example, a page, a news article, and an event are all content items, which correspond to the Page, News, and Event content types, respectively. .
  • Selected as the image for the Billboard or Feature blocks.

Embedding Images in Text Editor

  1. Edit the content item where you want to embed the image in.
  2. Click media browser icon in the WYSIWYG editor.
image media browser
  1. Select an existing image from your media library or upload a new one.
  2. Click Select 
  3. Select Display as option (Freeform, Small, Medium, Large)
  4. Select Align options (None, Left, Center, Right)
  5. Click Embed

The display options for embedded images relate to the size the image will be displayed and its position. In all cases, the image is never cropped to a specific aspect ratio. The original image aspect ratio is used.

More options

Media Management

Upload and manage your media files using the Media Library.

Retina Compatibility - Logo

To avoid having your website's logo appear blurry on displays with a high pixel density (also known as “retina displays”), the logo file must be sized at least twice as large as its intended size. Then use CSS to reduce the display size of the logo.

For example. if you have a square logo that looks good at 100x100 pixels, start with a 200x200 pixel logo file. Then add this bit of CSS to a CSS Injector rule to ensure the logo displays correctly. Height and width can be adjusted based on the size of the logo.

.header__logo img { height: 100px; width: 100px; }

Featured Images vs. Embedded Images

Most content types have a field to upload a Featured image. The display of your featured image is controlled by the Featured Image Display option to provide flexibility for a variety of use cases.

You may also embed images using your WYSIWYG editor tool into the main text of your content. You can alter the general size and position of embedded images as it related to the surrounding text.