The handle object

The handle object returns the handle of the following resources:

  • blogs
  • articles
  • collections
  • pages
  • products.

You can view and edit a resource's handle from the Shopify admin in the Search engine listing preview section:

Targeting webpages

You can use the handle object to target specific webpages for instances where you want to show different content on different pages. For example, to display a message only on a webpage with the handle top-secret, you could add the following code to the theme.liquid template:

Input

{% if handle contains 'secret' %}
  <p>Shh! This is between you and us.</p>
{% endif %}

Output

<!-- On a page with a title of Top Secret, and a handle of top-secret -->
Shh! This is between you and us.

Webpages that don't have their own handle

Not all webpages have their own handle.

Your store's home page, which uses the template index.liquid, will not return any value for handle:

Input

{% if handle %}
  <p>You are either looking at a product, a collection, a page, a blog, or an article in a blog.<p>
{% else %}
  <p>You must be somewhere else. Hope you're having fun!</p>
{% endif %}

Output

<!-- On a store's home page -->
You must be somewhere else. Hope you're having fun!

Special characters

Because handles are used for storefront navigation, they must contain only alpha-numeric characters (a-z, 0 to 9). The following character cannot be used:

  • accents, such as umlauts, and other diacriticals
  • symbols, such as @, #, or $
  • spaces.

Note that spaces will be converted to hyphens, and other characters will either be removed entirely, or converted to an equivalent standard ASCII character.