Retina image support – possible with Kirby?

I recently tried adding retina support (using for images on my Kirby website ( The issue I ran into was that adding both a 1x and 2x image within the project folder only resulted in a duplicate on the page.

Has anyone else tried to add retina image support on their Kirby site?

How to you display the image on the page? To avoid duplicates, you could filter the images:

    $images = $page->images()->filterBy('filename', '*=', '@1');

For everything except photos, I have started using .svgs instead of .pngs. They are resolution-independent, you can edit colors and strokes via CSS, and even include animations (check out the stars in the background of You can compress them so the file size is often smaller as well.

For retina.js I believe it should swap out images automatically as long as you link to the un-prefixed image. (E.g. display image.png but include image@2x.png in the directory and retina.js will take care of the rest.) I may be wrong but I don’t remember needing to work any Kirby magic to display retina assets.

No, you don’t need Kirby magic to display the retina assets, but if you include the images via the template and don’t filter the retina images, all images will appear twice.

hi texnixe, thank you for your response. the filter works. please see below for how i’m displaying images on the page. based on retina.js guidelines, the original images should not include “@1x” in the file name. how would you filter based on that? thanks in advance for your time.

        <ul class="content">
        <?php foreach($page->images()->filterBy('filename', '*=', '@1') as $img): ?>
		  <li style="vertical-align:top;">
			    <img src="<?php echo $img->url() ?>"  alt="<?php echo $img->title() ?>" />
		         <figcaption><?php echo $img->caption() ?></figcaption>
		  <?php endforeach ?> 

Unfortunately, there is no “does not contain”, so depending on your files, you can probably use a custom filter to filter by size or add a meta file to the files and filter by a field in those files?

1 Like

Probably a bit off-topic, but noticed, that I could not add image file bigger than about 2 mb (or it was limit on pixels … image was more than 2000px wide).

Is there any limitations for adding files in Kirby?

I think I remember having read something about a temporary limitation, pls checkout the issues on Github ( or contact @bastianallgeier

1 Like

There’s no limit on the file size or dimensions. Kirby just does stop generating image previews for images, which are larger than 2000 x 2000 px. If you are not able to upload the images in the first place you might need to check out PHP’s max upload and max post size in your php.ini.

I am using Picturefill in combination with automatically generated thumbnails to support retina devices and until now this works quite well.

Is there some way to override this behaviour? A common image size for retina output is 2048px (iPad width), so we need to upload bigger images in galleries most of the time.

We use something similar for some time now: A small lazyloader called unveil, which accepts 2 URLs – 1 for regular pages, the other for retina resolutions. I guess picturefill works similarly and delivers more accessible-friendly results.

Other notes:

When using the thumb() function for generating images, you need to apply much higher compression for retina output.
A popular retina support workflow actually consists of simply supplying highly compressed high-res images for everybody. You can use the same technique on compressed PNG logos which are often smaller than their SVG counterpart. Should be noted that scaling down many images in browser output affects performance.

You can still upload bigger images, only the preview in the panel stops. To change that, you could dig into the actual panel source code: How to show thumbnails of large images in the panel

hi all, thanks so much for all of the comments and suggestions. as the originator of this thread, i thought i’d follow up with how i chose to solve adding retina support to my site (

i ended up using retina.js and thumb plugin. i used the data-at2x attribute rather than the @2x attribute. this thread was also valuable:

<img src="<?php echo thumb($image, array('width' => 900))->url(); ?>"

to keep things simple, i went with a common width of 600 for all images. i upload them at 1200 and the script takes care of the rest. the only downside i’ve noticed so far is that i can’t use gifs. in the end it was more important to set up an efficient system rather than have to hard-code each image and mess with the templates too much.