Object handles

Handles are used to access the attributes of Liquid objects. By default, a handle is the object's title in lowercase with any spaces and special characters replaced by hyphens (-). Most objects in Shopify (products, collections, blogs, articles, menus) have handles.

For example, a page with the title "About Us" can be accessed in Liquid via its handle about-us as shown below:

<!-- the content of the About Us page -->
{{ pages.about-us.content }}

How handles are created

A product with the title "Shirt" will automatically be given the handle shirt. If there is already a product with the handle shirt, the handle will auto-increment. In other words, all "Shirt" products created after the first one will receive handles like shirt-1, shirt-2, and so on.

Handle 2

Whitespace in titles is replaced by hyphens in handles. For example, the title My Shiny New Title will result in the handle my-shiny-new-title.

Handle 3

The handle also determines the URL of the object. For example, a page with the handle about-us would have the url http://yourshop.myshopify.com/pages/about-us.

Shop designs often rely on static handles for pages, products, and menus. In order to preserve design elements and avoid broken links, if you modify the title of an object, Shopify does not automatically update the handle.

For example, if you were to change your page title from About Us to About Shopify, the handle would still be about-us:

Handle 5

You can change an object's handle manually by changing the value for the URL & Handle box.

Handle 6

Accessing handle attributes

In many cases you may know the handle of a object whose attributes you want to access. You can access its attributes by pluralizing the name of the object, then using either the square bracket ( [ ] ) or dot ( . ) notation.

{{ pages.about-us.title }}
{{ pages["about-us"].title }}

About Us
About Us

Notice that the example uses pages instead of page.

You can also pass in Customize theme page objects using this notation. This is handy for theme designers who want to give the users of their themes the ability to select which content to display in their theme.

{% for product in collections[settings.home_featured_collection].products %}
    {{ product.title }}
{% endfor %}

Awesome Shoes
Cool Shirt
Wicked Socks

Want to discuss this page?

Visit the Shopify Community