Used in the ‘images’ loop to show an individual category image in the loop.

shopp('collection', 'image', 'options')

@param string $object the object or object.tag combination, if object.tag is used, the tag parameter can be omitted
@param string $tag the tag, can be hyphenated or not. Prefix with 'get' as shorthand for the return=true option
@param mixed $options associative array, or url-style name=value pairs separated by ampersands (&). Each pair is passed to the theme api tag as an option.
@returns void by default, the image markup if the return option is used.

Alternative Forms

shopp('collection.image', 'options');
shopp('category.image', 'options');


The default image for a collection is determined by the image sorting options specified in the Presentation Settings.

The shopp(‘collection’,’image’) theme api call is only used for collections of type Product Category. Other product taxonomy terms collections, and smart collections do not have images associated with them.

Universal Options

All Theme API calls have these options.

  • return: when set to true, 1, or on, this option forces the tag to return the value instead of displaying/echoing the value to the page. Alternatively, prefix the tag parameter with get to get the same effect. All theme api tags that return a boolean value will return by default.
  • echo: when set to false, 0, or off, this option forces the tag to display the value to the page. This is the default for all non-boolean tags.
  • is: when set to true, 1, or on, this option will evaluate the return of the theme api call as a boolean true or false value. See how values are converted to boolean.


The following options are valid.

  • index: This option can be used outside the images loop to specify a particular image you wish to work with.

Example: if you have 2 images, these two are equivalent:

// index=1 would select the second image.
<?php shopp('collection','coverimage'); ?>
  • setting: Use to specify a user specified named image setting. For example, if you have configured a named image setting called gallery-previews in your Image Settings, use setting=gallery-previews to automatically set the dimensions, fit, quality, and sharpness of the image.
  • alt: The alt property of the image. By default, will use the alt attribute saved in the image editor, followed by the image name if the alt attribute is unset, followed by the user specified alt attribute using this option.
  • title: Set the title property of the image. By default, the title attribute saved in the image editor will be used, followed by the user specified title specified by this option.
  • zoom: Set to true value (1,on,true) to enable the image zoom effect. Enables the image zoom effect to view the original size image in a modal image viewer (Colorbox)
  • zoomfx: Sets the class name used to enable the zoom effect. Defaults to shopp shopp-zoom. Built in “lightbox” effects are provided by the Colorbox javascript library. You can disable this effect by removing or changing this class name.
  • bg: The background color to use with the matte fit (#rrggbb, default is #ffffff). Set to bg=transparent to use a transparent background.
  • class: Specifies the CSS class of the image
  • property: Overrides the default output of this tag to display a valid property of the image including any of the following: url, width, height, title, alt, id. If an invalid property is requested, the image id is displayed. Use the return=true option to return the property as PHP data.
  • quality: The JPEG image quality (0-100%, default is 80). Example, to set 50% quality, set quality=50.
  • sharpen: Apply an unsharp mask to the image (100%-500%, default is none). Example, to set 100% sharpen, set to sharpen=100.
  • size: The size to use for width and height of the image (used in place of width and height) Set size=original to view original image size. The height and width options are set to the same value if this option is used. Setting size=100 will set the width and height to 100.
  • width: Set the maximum width of the displayed image in pixels.
  • height: Set the maximum height of the displayed image in pixels.
  • fit: The fit of unproportional images to the requested size (defaults to all). See below of fit options.
  • property: use to display one attribute of the image. See below for property options. If the property option is set, the image will not be displayed.
  • img: set the ImageAsset object to use.

Property Options

  • id: Displays the image id. Set property=id to display this value.
  • url: Displays the image source url. Set property=url to display this value.
  • src: Displays the image source url. Set property=src to display this value.
  • title: Displays the title attribute of the image. Set property=title to display this value.
  • alt: Displays the alt attribute of the image. Set property=alt to display this value.
  • width: Displays the width attribute of the image. Set property=width to display this value.
  • height: Displays the height attribute of the image. Set property=height to display this value.
  • class: Displays the class attribute of the image. Set property=class to display this value.

Fit Options

  • width: Scale the image down to fit the image in the new size by the width, cropping any extra height. Set fit=width to use.
  • height: Scale the image down to fit the image in the new size by the height, cropping any extra width. Set fit=height to use.
  • crop: Scale the image down to fit by the smallest dimension to fill the entire image, cropping the extra off the other dimension (specific cropping adjustments can be made in the collection editor). Set fit=crop to use.
  • matte: Scale the image down to fit within the new size filling extra space with a background color. Set fit=matte to use.
  • all: Scale the image down to fit within the new size (the final size may differ from the specified dimensions) Set fit=all to use.


if ( shopp('collection','has-images')):
// user image setting featured-image used for 2nd collection image
shopp('collection', 'image', 'index=1&setting=featured-image');
<?php if ( shopp('collection','has-images') ): ?>
<?php while ( shopp('collection','images') ): ?>
    shopp('collection.image', array(
        'zoom' => 'off', // disable zoom effect
        'height' => 100,
        'width' => 50,
        'fit' => 'matte',
        'bg' => 'transparent',
<?php endwhile; ?>
<?php endif; ?>

Advanced usage

    // Set the collection to product category 5

    // Get the cover image id
    $img_id = shopp('collection.get-cover-image','property=id');
    $image = new CategoryImage($img_id);

    shopp('collection.image', array(
        'img' => $Image,
        'setting' => 'my-image-setting'

See Also

You must be logged in to post a comment.

© Ingenesis Limited. Shopp™ is a registered trademark of Ingenesis Limited.