When to use the `thumbs()` method vs the `resize()` or `crop()` methods

Hi all -

I’m using a very basic ‘files’ field in the panel to add images and loop through them to create a lightbox gallery (currently using the ‘Lity’ jquery plugin).

It works fine but I’m wondering what the benefits of using kirby’s built in thumbs functionality is for something like this and indeed it’s best usage scenerios outside of this?

In this rough example code I’m calling 2 versions of the uploaded image; one cropped and one original. I can’t really work out why it’s better to have kirby generate the thumb if I can do it this way; or is the method there so you can globally control thumb parameters?

Many thanks!

Main use cases are reducing file size of uploaded images, responsive layout or layout in general, i.e. to create cropped images.

Thanks for the reply; what I’m having trouble understanding is what is the difference between requesting a thumb and just requesting a version of the image in the same specified spec?

So for example, if i defined a crop of 300 in my config for thumbs, what would be the difference between $image->thumb and $image->crop(300) ?

Thanks for your patience, just trying to learn as I go!

I guess you are talking about thumb presets? The thumb() method has a lot of different options (width, height, blur, bw, crop etc.) , while crop() is a thumb shortcut for cropping, similar to resize(), bw() etc. Maybe I don’t quite understand the question.

In the example yes; but in general im still struggling to work out why i’d use thumbs over just calling the image at the appropriate size

What does that mean, calling the image at the appropriate size?

So in your first response you said the main use case was to reduce the file size of the image, for example cropping it. But I can do that with the crop and size filters for images, so im not sure what the difference between doing that or using the thumbs feature is.

That’s what I explained 2 of my posts above: When to use thumbs

Please check out the documentation for the different methods and their options.

I think we’re talking past eachother a bit here, but appreciate the help as always. I’ll do some more digging!


These are the options you have with the thumbs method:

$options = [
  'autoOrient' => true,
  'crop'       => false,
  'blur'       => false,
  'grayscale'  => false,
  'height'     => null,
  'quality'    => 90,
  'width'      => null,

You can’t use grayscale or blur()with crop() or resize().

The missing piece of the puzzle is probably this: A cropped image is also a thumb, just like an image manipulated with the bw() method is also a thumb. So the end result is just the same no matter if you call thumb() or crop(), but crop() is a shortcut if you only need cropping.


Ahhh thanks so much, that IS the missing piece! I’ve been trying to work out the difference you see!

Would like to use a global thumb-quality for cropped images.
Just found out, the crop-method can’t use the configured quality by default. is that true?
(but it takes the default format)
Any recommendation, which crop-method works better for that case?

'thumbs' => [
  'quality' => 80,
  'format' => 'webp',
src="<?= $image->thumb(['width' => 320, 'height' => 426, 'crop' => true])->url() ?>"
src="<?= $image->crop(320, 426, option('thumbs.quality'))->url() ?>"

Which Kirby version are you using? According to the source code of 3.7.5, the quality is respected when set and in my test it worked.

Thx @texnixe , works now (in K3.7.5)
But to see the difference on change global quality setting, we have to delete the media-folder first. :cowboy_hat_face:
I guess that is, because global quality settings are not being added to the filename, isn’t it?

No, the quality setting is applied to the generated thumb file name (e.g. -crop-q80).

Unfortunately not in my case, when the quality-settings is global by config.php
But i can definitly see that it takes effect in the image. (after remove media!)
(K3.7.5, PHP 8.1, Apache)

When i add quality localy to the crop the filename changes to -q10

You mean without explicitly calling the config option in the crop method?

'thumbs' => [
  'quality' => 80,
  'format' => 'webp',
src="<?= $image->crop(320, 426)->url() ?>"

results in path 320x426-crop.webp

src="<?= $image->crop(320, 426, option('thumbs.quality'))->url() ?>"

leads to 320x426-crop-q80.webp (as expected)

Yes, the crop function doesn’t automatically apply those default settings, you have to pass that option explicitly, see the source code, the default setting for quality is null.

You could create a custom crop method that does this by default.