URL filters

URL filters output links to assets on Shopify's Content Delivery Network (CDN). They are also used to create links for filtering collections and blogs.

In many URL filter outputs, you will see a question mark (?) with a number appended to the asset's file path. This is the file's version number. For example, the version number in this URL is 28253:

URL filters will always load the latest version of an asset.

asset_url

Returns the URL of a file in the "assets" folder of a theme.

asset_img_url

Returns the asset URL of an image in the "assets" folder of a theme. asset_img_url accepts an image size parameter.

file_url

Returns the URL of a file in the Files page of the admin.

file_img_url

Returns the asset URL of an image in the Files page of the admin. file_img_url accepts an image size parameter.

customer_login_link

Generates a link to the customer login page.

global_asset_url

Returns the URL of a global asset. Global assets are kept in a directory on Shopify's servers. Using global assets can improve the load times of your pages.

The following global assets are available:

image_url

Returns the URL of an image. You can use image_url on the following objects:

• product
• variant
• line item
• collection
• article
• image

You can also use image_url on the image or src attributes of an object:

image_url can't transform icon files (.ico). If you specify a size or format for an icon file, then image_url returns the original file.

For line items, image_url returns the URL of the line item's variant image. If the variant does not have an assigned image, image_url returns the URL of the product's featured image.

The image_url filter requires either a width or height attribute. Learn more about size parameters.

Parameters

The image_url filter accepts the following parameters.

Learn more about each parameter below.

Size parameters

You can specify exact dimensions in pixels for an image's width and height, up to a maximum of 5760 x 5760 px.

The image_url filter requires either a width or height attribute. If neither width nor height are provided, then the image isn't displayed and the message at least one of width or height must be supplied is returned.

If only one attribute is provided, then the image is resized with the aspect ratio maintained.

If both attributes are provided and the aspect ratio doesn't match the original image, then the image is cropped. In this case, you should specify a crop or a pad_color for the image. If you don't specify a crop or pad_color, then crop defaults to center.

No matter what size you specify, an image can never be resized to be larger than its original dimensions.

crop

You can specify a crop parameter to make sure that the resulting image's dimensions match the requested dimensions. If the entire image won't fit in your requested dimensions, the crop parameter specifies what part of the image to show. Valid options are:

• top
• center
• bottom
• left
• right

If you specify both a width and height, and no crop or pad_color setting is provided, then crop defaults to center.

format

The format parameter lets you specify what file format to use for the displayed image. Valid options are jpg and pjpg.

pjpg is progressive JPEG. A browser loads a full-sized progressive JPEG with gradually increasing quality, instead of loading the full-quality image from top to bottom like a traditional JPEG.

Shopify can do the following format conversions for you:

• PNG to JPG
• PNG to PJPG
• JPG to PJPG

It's not practical to convert a lossy image format like JPG to a lossless one like PNG, so those conversions aren't possible.

pad_color

The pad_color parameter lets you specify a color to pad the image with if the provided image is smaller than the requested dimensions. pad_color accepts only hex color codes.

link_to

Generates an HTML link.

This filter requires a parameter to pass the URL of the link. For example:

Additionally, you can add supported HTML attributes, separated by a comma (,), in the format of:

For example, you can set the title and class attributes:

link_to_vendor

Creates an HTML link to a collection page that lists all products belonging to a vendor.

Additionally, you can add supported HTML attributes in the format of:

For example, you can set the class attribute:

link_to_type

Creates an HTML link to a collection page that lists all products belonging to a product type.

Additionally, you can add supported HTML attributes in the format of:

For example, you can set the class attribute:

link_to_tag

Creates a link to all products in a collection that have a given tag.

link_to_add_tag

Creates a link to all products in a collection that have a given tag as well as any tags that have been already selected.

link_to_remove_tag

Generates a link to all products in a collection that have the given tag and all the previous tags that might have been added already.

payment_type_img_url

Returns the URL of the payment type's SVG image. Used in conjunction with the shop.enabled_payment_types variable.

shopify_asset_url

Returns the URL of a global assets that are found on Shopify's servers. Globally-hosted assets include:

• option_selection.js
• api.jquery.js
• shopify_common.js
• customer_area.js
• currencies.js
• customer.css

sort_by

Creates a URL to a collection page with the provided sort_by parameter. This filter must be applied to a collection URL.

url_for_type

Creates a URL that links to a collection page containing products with a specific product type.

url_for_vendor

Creates a URL that links to a collection page containing products with a specific product vendor.

When a product is collection-aware, its product template can access the collection output of the collection that it belongs to. This allows you to add in collection-related content, such as related products.