Variant Queries

You can fetch variants in your templates or PHP code using variant queries.

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

# Example

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

{# 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>
<!-- ... -->

#anyStatus

Clears out the status() and enabledForSite() 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 objects.

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

#dateCreated

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

Possible values include:

{# 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:

{# 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:

#hasSales

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

Possible values include:

#hasStock

Narrows the query results to only variants that have stock.

Possible values include:

#id

Narrows the query results based on the variants’ IDs.

Possible values include:

{# Fetch the variant by its ID #}
{% set variant = craft.variants()
    .id(1)
    .one() %}

#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() %}

#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:

#minQty

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

Possible values include:

#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.

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

#price

Narrows the query results based on the variants’ price.

Possible values include:

#product

Narrows the query results based on the variants’ product.

Possible values include:

#productId

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

Possible values include:

#relatedTo

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

See Relations 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() %}

#search

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

See Searching 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 the variants should be queried in.

The current site will be used by default.

Possible values include:

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

#siteId

Determines which site 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:

{# 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() %}

#stock

Narrows the query results based on the variants’ stock.

Possible values include:

#title

Narrows the query results based on the variants’ titles.

Possible values include:

{# 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 = {twig-function}
    .trashed()
    .all() %}

#typeId

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

Possible values include:

#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() %}

#with

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

See Eager-Loading Elements 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() %}