For accessing a single, specified category from the catalog. By default, displays the category using the format described in the [[category.php template file]].

shopp('storefront', 'category', '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 string Markup for the specified category

For accessing a single, specified category from the catalog. By default, displays the category using the layout described in the category.php template file.


  • controls: Default is on. Overrides the display of “control” elements in the category.php template that would otherwise be shown. Used to highlight a selection of products in a category without all of the extra category controls.
  • id: Specifies the category to be displayed by matching the category ID number. This is an alternative and is a faster database lookup then using the name.
  • load: Default is false. Loads the category into memory, making it available for using category.php template file rather than displaying the category using the category.php template file.
  • pagination: Default is numeric. Set to alpha this option will use alphabetic pagination, otherwise it will default to numeric.
  • order: Default is title. Possible settings include: bestselling, highprice, lowprice, newest, oldest, random, and title
  • reset: Usually used independent of the other options to switch the current category being rendered by shopp('category') tags to the originally request category (the category the brower originally requested by URL)
  • show: No default value. Limits the number of products to show in the category display. Without a limit, this category will show all the products in your catalog (no matter what category they are in). Without a specified limit, a built-in hard limit of 1000 products is used to prevent the server’s resources from being totally consumed.
  • slug: Specifies the category to be displayed by the category name. An exact match is necessary (including uppercase/lowercase letters).
  • title: Specifies the title to be shown for the category layout overriding the default category title.
  • view: No default. Sets the initial view (grid or list) of the category regardless of any shopper preference. The shopper can still change the view using view controls (if available).

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.


Display A Custom Category By ID

<?php shopp('storefront','category','id=1'); ?>

This will display the category on a given page just as if it was directly requested by its permalink using the category.php template file for its layout.

Load A Custom Category By Slug

<?php shopp('storefront','category','slug=paperback-books&load=true'); ?>

This example loads a custom category making it ready to use shopp(‘category’) tags against. It does not display anything itself. This technique allows you to define your own inline layout for the category in place of the category.php template file. For more information, see the tutorial on creating a category.php template file.

Resetting to the Requested Category

<?php shopp('storefront','category','reset=true'); ?>

After rendering parts of a category through the shopp('category') tags, the category context may need switched back to the original category request in order for the page display to render as anticipated.

See Also

  1. …well, it seems I’ve got to apologize, I understand how it’s supposed to work now; for example to print out the names of products in a category:

    shopp("storefront", "category", "id=1&load=true");
        if ( shopp('collection','has-products') ) {
            while ( shopp('collection','products') ) {
                shopp('product','name'); // displays product name
    June 5th   #

You must be logged in to post a comment.

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