Image Component

The Image component allows you to place an image on your page. In-component editing options offer the ability to crop an image.

For other methods of adding images to a page, see the Text & Image Component, Carousel Component and Image Gallery Component.

When should it be used?

Use an image component whenever you need to place an image on a page.

Images for display on the web need to be .jpeg, .png, or .gif. Other file types, such as .tiff, .psd, etc are documents meant for download and editing and will not be displayed on the page.

By default, images are rendered at 100% of their container element's width. The image resizes depending on the width of its container. Where possible, authors are encouraged to use high-resolution images of up to 2000px in width at 72dpi, depending on the context. This will allow the image to look optimized for the largest screen, as well as retina devices, which serve up images at double the standard resolution.

Note: .png and .gif files with a transparent background are replaced with a white background. This is because AEM automatically optimizes images in the DAM, reducing their file size so that web pages load quickly. To keep the transparency, follow the steps in the next section.

Cropping an Image

The Image component makes it easy to crop an image to a preset aspect ratio. Preset aspect ratios are especially useful when you need to make a group of images have the same height and width. Images can also be cropped free form.

Cropping an image is non-destructive. You can always return the image back to its original uncropped version.

To crop an image, complete the following steps:

  1. Bring up the Image component properties by double-clicking the component.
  2. Click the Crop button.

    The Image crop tools toolbar will appear.

    This toolbar can be moved if it gets in the way, just like the Sidekick.

  3. Click the drop-down menu and select an aspect ratio. The default option is Free Crop, which allows you to crop the image to any ratio.

    In this example, the 1:1 (Square) option is selected.

  4. To change the size of the crop area, click and drag the corners. It will keep the aspect ratio when the size is changed.

  5. To change the position of the crop area, click and drag the middle of the crop area.

  6. Once you've settled on a crop area, click the OK button.

    Final cropped image.

To revert the image back to its original uncropped version, go back into the crop mode, select Free Crop from the Image crop tools toolbar, and drag the corners to the edges of the image.

Advanced Image Properties

Title - Text that appears when a mouse pointer is hovering on the image

Alt Text - Text that appears for browsers that do not display images.  If left blank, it will use any text that is entered in the Title field

Link to - Add a link to a file or page in AEM  

Description - A caption that appears underneath the image

Size - Sets a maximum width or height for images. Important note: do not put a size value in both of the Size fields as it will distort your image on the published website. Instead, set either a maximum width (first field) or maximum height (second field). 

CSS Class - Allows an author to provide an optional class name that will apply a style to the contents.  See Styles section below for a list of styles that can be applied to an image component.

Preserving Image Transparency

  1. In the DAM, double-click the image thumbnail.

  2. A new set of properties will appear. Click the Tags field in the middle panel and enter "use-original". Select the matching tag.

    The "use-original" tag is selected.

  3. At the bottom of the middle panel, click the Save button. The "use-original" tag tells AEM to not optimize the image, thus the transparent background will remain when the image is used.

    Example of an image with a transparent background using the "use-original" tag.

Example of Image Component usage

Students in a classroom at SFU


To override the default 100% width that image renders, please use the following CSS classes (available only in CLF2):

Renders the image at 50% its usual width.

Renders the image at 33% its usual width.

Renders the image at 66% its usual width.

Predefined pixel based constraints:

Constrains the container to a maximum width of 908px

Constrains the container to a maximum width of 726px

Constrains the container to a maximum width of 545px

Constrains the container to a maximum width of 363px

Constrains the container to a maximum width of 181px

Tips & Tricks

Always upload your image to the DAM rather than uploading it directly to the component. When an image is uploaded to the DAM, AEM will process the image and create a variety of renditions (small, medium, large). AEM will then select the right rendition to use for a given component. Images that are uploaded directly to the component will not be processed. The image may end up being too large for the context, and may result in a slow-loading page.

If you are unable to find a higher-quality version of an image, one of the following work-arounds may be appropriate:

  • Add a 2-column or 3-column component to the page. Place the image in the smaller column and fill the other column(s) with text, or leave it empty.
  • Use one of the styles listed above. Test the results on a variety of browsers and devices to ensure that the image doesn't appear too small. (If you do not have access to other devices, simply resize your browser window to see the effects.)