Variant Queries

You can fetch variants using variant queries.

{# Create a new variant query #}
{% set myVariantQuery = craft.variants() %}

Once you’ve created a variant query, you can set parameters on it to narrow down the results, and then execute it (opens new window) by calling .all(). An array of Variant (opens new window) objects will be returned.

See Element Queries (opens new window) in the Craft docs to learn about how element queries work.

# Example

We can display a specific variant by its ID in Twig by doing the following:

  1. Create a variant query with craft.variants().
  2. Set the id parameter on it.
  3. Fetch the variant with .one().
  4. Output information about the variant as HTML.
{# Get the requested variant ID from the query string #}
{% set variantId = craft.app.request.getQueryParam('id') %}

{# Create a variant query with the 'id' parameter #}
{% set myVariantQuery = craft.variants()
    .id(variantId) %}

{# Fetch the variant #}
{% set variant = myVariantQuery.one() %}

{# Make sure it exists #}
{% if not variant %}
    {% exit 404 %}
{% endif %}

{# Display the variant #}
<h1>{{ variant.title }}</h1>
<!-- ... -->

Fetching the equivalent with GraphQL could look like this:

# Fetch variant having ID = 46
{
  variants(id: 46) {
    title
  }
}

# Parameters

Variant queries support the following parameters:

Param Description
anyStatus Clears out the status and enabledForSite() (opens new window) parameters.
asArray Causes the query to return matching variants as arrays of data, rather than Variant (opens new window) objects.
clearCachedResult Clears the cached result.
dateCreated Narrows the query results based on the variants’ creation dates.
dateUpdated Narrows the query results based on the variants’ last-updated dates.
fixedOrder Causes the query results to be returned in the order specified by id.
hasProduct Narrows the query results to only variants for certain products.
hasSales Narrows the query results to only variants that are on sale.
hasStock Narrows the query results to only variants that have stock.
height Narrows the query results based on the variants’ height dimension.
id Narrows the query results based on the variants’ IDs.
ignorePlaceholders Causes the query to return matching variants as they are stored in the database, ignoring matching placeholder elements that were set by craft\services\Elements::setPlaceholderElement() (opens new window).
inReverse Causes the query results to be returned in reverse order.
isDefault Narrows the query results to only default variants.
length Narrows the query results based on the variants’ length dimension.
limit Determines the number of variants that should be returned.
maxQty Narrows the query results based on the variants’ max quantity.
minQty Narrows the query results based on the variants’ min quantity.
offset Determines how many variants should be skipped in the results.
orderBy Determines the order that the variants should be returned in. (If empty, defaults to sortOrder ASC.)
preferSites If unique is set, this determines which site should be selected when querying multi-site elements.
price Narrows the query results based on the variants’ price.
product Narrows the query results based on the variants’ product.
productId Narrows the query results based on the variants’ products’ IDs.
relatedTo Narrows the query results to only variants that are related to certain other elements.
search Narrows the query results to only variants that match a search query.
site Determines which site(s) the variants should be queried in.
siteId Determines which site(s) the variants should be queried in, per the site’s ID.
sku Narrows the query results based on the variants’ SKUs.
status Narrows the query results based on the variants’ statuses.
stock Narrows the query results based on the variants’ stock.
title Narrows the query results based on the variants’ titles.
trashed Narrows the query results to only variants that have been soft-deleted.
typeId Narrows the query results based on the variants’ product types, per their IDs.
uid Narrows the query results based on the variants’ UIDs.
unique Determines whether only elements with unique IDs should be returned by the query.
weight Narrows the query results based on the variants’ weight dimension.
width Narrows the query results based on the variants’ width dimension.
with Causes the query to return matching variants eager-loaded with related elements.

# anyStatus

Clears out the status and enabledForSite() (opens new window) parameters.

{# Fetch all variants, regardless of status #}
{% set variants = craft.variants()
    .anyStatus()
    .all() %}

# asArray

Causes the query to return matching variants as arrays of data, rather than Variant (opens new window) objects.

{# Fetch variants as arrays #}
{% set variants = craft.variants()
    .asArray()
    .all() %}

# clearCachedResult

Clears the cached result.

# dateCreated

Narrows the query results based on the variants’ creation dates.

Possible values include:

Value Fetches variants…
'>= 2018-04-01' that were created on or after 2018-04-01.
'< 2018-05-01' that were created before 2018-05-01
['and', '>= 2018-04-04', '< 2018-05-01'] that were created between 2018-04-01 and 2018-05-01.
{# Fetch variants created last month #}
{% set start = date('first day of last month')|atom %}
{% set end = date('first day of this month')|atom %}

{% set variants = craft.variants()
    .dateCreated(['and', ">= #{start}", "< #{end}"])
    .all() %}

# dateUpdated

Narrows the query results based on the variants’ last-updated dates.

Possible values include:

Value Fetches variants…
'>= 2018-04-01' that were updated on or after 2018-04-01.
'< 2018-05-01' that were updated before 2018-05-01
['and', '>= 2018-04-04', '< 2018-05-01'] that were updated between 2018-04-01 and 2018-05-01.
{# Fetch variants updated in the last week #}
{% set lastWeek = date('1 week ago')|atom %}

{% set variants = craft.variants()
    .dateUpdated(">= #{lastWeek}")
    .all() %}

# fixedOrder

Causes the query results to be returned in the order specified by id.

{# Fetch variants in a specific order #}
{% set variants = craft.variants()
    .id([1, 2, 3, 4, 5])
    .fixedOrder()
    .all() %}

# hasProduct

Narrows the query results to only variants for certain products.

Possible values include:

Value Fetches variants…
a ProductQuery (opens new window) object for products that match the query.

# hasSales

Narrows the query results to only variants that are on sale.

Possible values include:

Value Fetches variants…
true on sale
false not on sale

# hasStock

Narrows the query results to only variants that have stock.

Possible values include:

Value Fetches variants…
true with stock.
false with no stock.

# height

Narrows the query results based on the variants’ height dimension.

{# Fetch all variants with a height greater than 100 #}
{% set variants = craft.variants()
    .height("> 100")
    .all() %}

Querying variants by height will restrict the query to only those product types that have dimensions enabled.

# id

Narrows the query results based on the variants’ IDs.

Possible values include:

Value Fetches variants…
1 with an ID of 1.
'not 1' not with an ID of 1.
[1, 2] with an ID of 1 or 2.
['not', 1, 2] not with an ID of 1 or 2.
{# Fetch the variant by its ID #}
{% set variant = craft.variants()
    .id(1)
    .one() %}

This can be combined with fixedOrder if you want the results to be returned in a specific order.

# ignorePlaceholders

Causes the query to return matching variants as they are stored in the database, ignoring matching placeholder elements that were set by craft\services\Elements::setPlaceholderElement() (opens new window).

# inReverse

Causes the query results to be returned in reverse order.

{# Fetch variants in reverse #}
{% set variants = craft.variants()
    .inReverse()
    .all() %}

# isDefault

Narrows the query results to only default variants.

{# Fetch default variants #}
{% set variants = {twig-function}
    .isDefault()
    .all() %}

# length

Narrows the query results based on the variants’ length dimension.

{# Fetch all variants with a length greater than 100 #}
{% set variants = craft.variants()
    .length("> 100")
    .all() %}

Querying variants by length will restrict the query to only those product types that have dimensions enabled.

# limit

Determines the number of variants that should be returned.

{# Fetch up to 10 variants  #}
{% set variants = craft.variants()
    .limit(10)
    .all() %}

# maxQty

Narrows the query results based on the variants’ max quantity.

Possible values include:

Value Fetches variants…
100 with a maxQty of 100.
'>= 100' with a maxQty of at least 100.
'< 100' with a maxQty of less than 100.

# minQty

Narrows the query results based on the variants’ min quantity.

Possible values include:

Value Fetches variants…
100 with a minQty of 100.
'>= 100' with a minQty of at least 100.
'< 100' with a minQty of less than 100.

# offset

Determines how many variants should be skipped in the results.

{# Fetch all variants except for the first 3 #}
{% set variants = craft.variants()
    .offset(3)
    .all() %}

# orderBy

Determines the order that the variants should be returned in. (If empty, defaults to sortOrder ASC.)

{# Fetch all variants in order of date created #}
{% set variants = craft.variants()
    .orderBy('dateCreated asc')
    .all() %}

# preferSites

If unique is set, this determines which site should be selected when querying multi-site elements.

For example, if element “Foo” exists in Site A and Site B, and element “Bar” exists in Site B and Site C, and this is set to ['c', 'b', 'a'], then Foo will be returned for Site C, and Bar will be returned for Site B.

If this isn’t set, then preference goes to the current site.

{# Fetch unique variants from Site A, or Site B if they don’t exist in Site A #}
{% set variants = craft.variants()
    .site('*')
    .unique()
    .preferSites(['a', 'b'])
    .all() %}

# price

Narrows the query results based on the variants’ price.

Possible values include:

Value Fetches variants…
100 with a price of 100.
'>= 100' with a price of at least 100.
'< 100' with a price of less than 100.

# product

Narrows the query results based on the variants’ product.

Possible values include:

Value Fetches variants…
a Product (opens new window) object for a product represented by the object.

# productId

Narrows the query results based on the variants’ products’ IDs.

Possible values include:

Value Fetches variants…
1 for a product with an ID of 1.
[1, 2] for product with an ID of 1 or 2.
['not', 1, 2] for product not with an ID of 1 or 2.

# relatedTo

Narrows the query results to only variants that are related to certain other elements.

See Relations (opens new window) for a full explanation of how to work with this parameter.

{# Fetch all variants that are related to myCategory #}
{% set variants = craft.variants()
    .relatedTo(myCategory)
    .all() %}

Narrows the query results to only variants that match a search query.

See Searching (opens new window) for a full explanation of how to work with this parameter.

{# Get the search query from the 'q' query string param #}
{% set searchQuery = craft.app.request.getQueryParam('q') %}

{# Fetch all variants that match the search query #}
{% set variants = craft.variants()
    .search(searchQuery)
    .all() %}

# site

Determines which site(s) the variants should be queried in.

The current site will be used by default.

Possible values include:

Value Fetches variants…
'foo' from the site with a handle of foo.
['foo', 'bar'] from a site with a handle of foo or bar.
['not', 'foo', 'bar'] not in a site with a handle of foo or bar.
a craft\models\Site (opens new window) object from the site represented by the object.
'*' from any site.

If multiple sites are specified, elements that belong to multiple sites will be returned multiple times. If you only want unique elements to be returned, use unique in conjunction with this.

{# Fetch variants from the Foo site #}
{% set variants = craft.variants()
    .site('foo')
    .all() %}

# siteId

Determines which site(s) the variants should be queried in, per the site’s ID.

The current site will be used by default.

{# Fetch variants from the site with an ID of 1 #}
{% set variants = craft.variants()
    .siteId(1)
    .all() %}

# sku

Narrows the query results based on the variants’ SKUs.

Possible values include:

Value Fetches variants…
'foo' with a SKU of foo.
'foo*' with a SKU that begins with foo.
'*foo' with a SKU that ends with foo.
'*foo*' with a SKU that contains foo.
'not *foo*' with a SKU that doesn’t contain foo.
['*foo*', '*bar*' with a SKU that contains foo or bar.
['not', '*foo*', '*bar*'] with a SKU that doesn’t contain foo or bar.
{# Get the requested variant SKU from the URL #}
{% set requestedSlug = craft.app.request.getSegment(3) %}

{# Fetch the variant with that slug #}
{% set variant = craft.variants()
    .sku(requestedSlug|literal)
    .one() %}

# status

Narrows the query results based on the variants’ statuses.

Possible values include:

Value Fetches variants…
'enabled' (default) that are enabled.
'disabled' that are disabled.
{# Fetch disabled variants #}
{% set variants = craft.variants()
    .status('disabled')
    .all() %}

# stock

Narrows the query results based on the variants’ stock.

Possible values include:

Value Fetches variants…
0 with no stock.
'>= 5' with a stock of at least 5.
'< 10' with a stock of less than 10.

# title

Narrows the query results based on the variants’ titles.

Possible values include:

Value Fetches variants…
'Foo' with a title of Foo.
'Foo*' with a title that begins with Foo.
'*Foo' with a title that ends with Foo.
'*Foo*' with a title that contains Foo.
'not *Foo*' with a title that doesn’t contain Foo.
['*Foo*', '*Bar*'] with a title that contains Foo or Bar.
['not', '*Foo*', '*Bar*'] with a title that doesn’t contain Foo or Bar.
{# Fetch variants with a title that contains "Foo" #}
{% set variants = craft.variants()
    .title('*Foo*')
    .all() %}

# trashed

Narrows the query results to only variants that have been soft-deleted.

{# Fetch trashed variants #}
{% set variants = craft.variants()
    .trashed()
    .all() %}

# typeId

Narrows the query results based on the variants’ product types, per their IDs.

Possible values include:

Value Fetches variants…
1 for a product of a type with an ID of 1.
[1, 2] for product of a type with an ID of 1 or 2.
['not', 1, 2] for product of a type not with an ID of 1 or 2.

# uid

Narrows the query results based on the variants’ UIDs.

{# Fetch the variant by its UID #}
{% set variant = craft.variants()
    .uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
    .one() %}

# unique

Determines whether only elements with unique IDs should be returned by the query.

This should be used when querying elements from multiple sites at the same time, if “duplicate” results is not desired.

{# Fetch unique variants across all sites #}
{% set variants = craft.variants()
    .site('*')
    .unique()
    .all() %}

# weight

Narrows the query results based on the variants’ weight dimension.

{# Fetch all variants with a weight greater than 100 #}
{% set variants = craft.variants()
    .weight("> 100")
    .all() %}

Querying variants by weight will restrict the query to only those product types that have dimensions enabled.

# width

Narrows the query results based on the variants’ width dimension.

{# Fetch all variants with a width greater than 100 #}
{% set variants = craft.variants()
    .width("> 100")
    .all() %}

Querying variants by width will restrict the query to only those product types that have dimensions enabled.

# with

Causes the query to return matching variants eager-loaded with related elements.

See Eager-Loading Elements (opens new window) for a full explanation of how to work with this parameter.

{# Fetch variants eager-loaded with the "Related" field’s relations #}
{% set variants = craft.variants()
    .with(['related'])
    .all() %}