Why is my image appearing in the wrong size or cropped unexpectedly?
Images on the site are automatically resized and cropped to fit the specific dimensions required by each area of the design- a hero banner, a card thumbnail, and a gallery image will all display at different proportions. This cropping happens automatically, and in most cases the result is controlled by where the focal point is set on the image.
Understanding focal points
When Craft CMS crops an image to fit a particular size, it needs to decide which part of the image to keep. By default it crops from the centre. If the most important part of your image- a person's face, a key landmark, a product- is not in the centre, the crop may cut it out unexpectedly.
To avoid this, every image in the media library has a focal point that you can set manually. The focal point tells the CMS which part of the image is most important, and all crops will be centred around that point.
How to set a focal point
To set or adjust the focal point on an image, open the image in the media library by clicking on it. You will see a small circle on the image indicating the current focal point- by default this sits in the centre. Click and drag the circle to the most important part of your image, such as a subject's face or the key visual element. Save the asset once you have positioned it.
The change will apply wherever that image is used across the site, so any cropped versions will now favour the area you have selected.
The image dimensions may not suit the required aspect ratio
Each area of the site expects images within a certain aspect ratio. If your image is very wide and the display area is tall, or vice versa, a significant portion of the image will be cropped away regardless of the focal point. Uploading an image that more closely matches the required proportions for that area of the site will give better results.
As a general guide, images used in wide hero banners should be landscape oriented with a wide aspect ratio, while square or portrait images tend to work better for certain card layouts. If you are unsure of the recommended dimensions for a particular image field, contact your site administrator.
The site may be serving a cached version of the image
If you have updated the focal point or replaced an image but the site is still showing the old crop, the site cache may not have cleared yet. This should resolve automatically after a short time. If it persists, contact your site administrator to request a manual cache clear.
Understanding focal points
When Craft CMS crops an image to fit a particular size, it needs to decide which part of the image to keep. By default it crops from the centre. If the most important part of your image- a person's face, a key landmark, a product- is not in the centre, the crop may cut it out unexpectedly.
To avoid this, every image in the media library has a focal point that you can set manually. The focal point tells the CMS which part of the image is most important, and all crops will be centred around that point.
How to set a focal point
To set or adjust the focal point on an image, open the image in the media library by clicking on it. You will see a small circle on the image indicating the current focal point- by default this sits in the centre. Click and drag the circle to the most important part of your image, such as a subject's face or the key visual element. Save the asset once you have positioned it.
The change will apply wherever that image is used across the site, so any cropped versions will now favour the area you have selected.
The image dimensions may not suit the required aspect ratio
Each area of the site expects images within a certain aspect ratio. If your image is very wide and the display area is tall, or vice versa, a significant portion of the image will be cropped away regardless of the focal point. Uploading an image that more closely matches the required proportions for that area of the site will give better results.
As a general guide, images used in wide hero banners should be landscape oriented with a wide aspect ratio, while square or portrait images tend to work better for certain card layouts. If you are unsure of the recommended dimensions for a particular image field, contact your site administrator.
The site may be serving a cached version of the image
If you have updated the focal point or replaced an image but the site is still showing the old crop, the site cache may not have cleared yet. This should resolve automatically after a short time. If it persists, contact your site administrator to request a manual cache clear.